# ShasPOS Pro — PHP Backend Project Structure

Target: PHP 8.x + MySQL/MariaDB, shared-hosting/cPanel safe, REST API first, no framework required.

```text
shaspos-pro-server/
├── app/
│   ├── Controllers/
│   │   ├── Api/V1/
│   │   └── Admin/
│   ├── Core/
│   │   ├── App.php
│   │   ├── DB.php
│   │   ├── Router.php
│   │   ├── Request.php
│   │   ├── Response.php
│   │   ├── Validator.php
│   │   ├── Transaction.php
│   │   └── Config.php
│   ├── Middleware/
│   │   ├── AuthMiddleware.php
│   │   ├── TenantMiddleware.php
│   │   ├── OutletMiddleware.php
│   │   ├── PermissionMiddleware.php
│   │   ├── SubscriptionMiddleware.php
│   │   └── RateLimitMiddleware.php
│   ├── Models/
│   ├── Repositories/
│   ├── Services/
│   │   ├── Auth/
│   │   ├── Tenancy/
│   │   ├── Rbac/
│   │   ├── Billing/
│   │   ├── Payments/
│   │   │   ├── Contracts/PaymentGatewayInterface.php
│   │   │   ├── DTO/
│   │   │   └── Gateways/ShasPayGateway.php
│   │   ├── Catalog/
│   │   ├── Inventory/
│   │   ├── Sales/
│   │   ├── Purchasing/
│   │   ├── Costing/
│   │   ├── Finance/
│   │   └── Reporting/
│   ├── Policies/
│   └── Support/
├── bootstrap/
│   └── bootstrap.php
├── config/
│   ├── app.php
│   ├── database.php
│   ├── security.php
│   ├── mail.php
│   └── payments.php
├── database/
│   ├── migrations/
│   ├── seeds/
│   └── schema.sql
├── routes/
│   ├── api_v1.php
│   └── admin.php
├── public/
│   ├── index.php
│   ├── .htaccess
│   └── assets/
├── storage/
│   ├── logs/
│   ├── uploads/
│   ├── exports/
│   ├── cache/
│   └── tmp/
├── cron/
│   ├── worker.php
│   ├── subscriptions.php
│   ├── cleanup.php
│   └── backup.php
├── tests/
├── .env.example
└── README.md
```

## Mandatory boundaries

- `Controllers` parse/authorize requests and hand work to services; they do not contain SQL/business posting logic.
- `Repositories` own persistence queries and always accept/derive tenant scope.
- `Services` own business transactions and invariants.
- All money/stock posting services use `DB::transaction()` and fail atomically.
- All API responses go through one response helper and stable machine-readable error codes.
- Payment-provider code only exists behind `PaymentGatewayInterface`.
- `ShasPayGateway` receives secrets from server environment/config only.
- Super Admin routes and merchant API authorization are separate security domains.
- Production document root points to `/public`; `/app`, `/config`, `/storage`, `/database`, and secrets are never web-accessible.

## Shared-hosting compatibility

The host does not need Composer at runtime. If third-party libraries are later used, dependencies can be built/vendor-packaged before upload. Long-running workers are avoided; cPanel cron invokes finite PHP CLI jobs that lock/claim rows from `job_queue`, process a bounded batch, and exit.