# ZCMSS API — Modular Architecture

The Laravel API follows a **modular monolith** pattern aligned with the ZCMSS monorepo's DDD bounded contexts ([04-backend-architecture.md](../../zcmssNext_Mono/docs/04-backend-architecture.md)).

## Module Layout

Each module is a self-contained bounded context:

```
modules/{ModuleName}/
├── module.json              # Metadata and dependencies
├── Providers/
│   └── {Module}ServiceProvider.php
├── routes/
│   └── api.php              # Routes (loaded under /api/v1)
├── database/
│   ├── migrations/
│   │   ├── central/         # Central DB migrations
│   │   └── tenant/          # Per-tenant DB migrations
│   └── seeders/
└── src/
    ├── Application/         # Use cases / actions
    ├── Domain/              # Entities, value objects (future)
    ├── Http/
    │   ├── Controllers/
    │   ├── Requests/
    │   └── Resources/
    ├── Infrastructure/      # Repositories, external services
    ├── Jobs/
    └── Models/
```

## Active Modules

| Module | Bounded Context | Responsibility |
|---|---|---|
| **Core** | Shared | Tenancy resolution, middleware, base controller |
| **Identity** | Identity | Super admin + tenant auth, users, roles, permissions |
| **Platform** | Tenant + Billing | Registration, provisioning, plans, domains, subscriptions |
| **Crm** | CRM | Leads, contacts, accounts, deals, pipelines, dashboard |
| **Activity** | Activity | Tasks, meetings, call logs |
| **Hr** | HR | Employees, departments, role permissions |

## Phase 2 Modules (Complete)

See module routes under `/api/v1/` when authenticated with tenant context.

## Adding a New Module

1. Create `modules/{Name}/` with the layout above
2. Add a `{Name}ServiceProvider` extending `App\Support\Modules\ModuleServiceProvider`
3. Register in `config/modules.php` under `enabled` and `map`
4. Add PSR-4 autoload entry in `composer.json`
5. Run `composer dump-autoload`

Example future modules: `Finance`, `Support`, `Communication`.

## Route Loading

All module routes are included from `routes/api.php`:

```php
Route::prefix('v1')->group(function () {
    foreach (config('modules.enabled') as $module) {
        require config('modules.path')."/{$module}/routes/api.php";
    }
});
```

## Migrations

- **Central**: Auto-loaded via each module's `ServiceProvider::loadModuleMigrations('central')`
- **Tenant**: Run automatically during provisioning via `TenantDatabaseManager`, iterating all module `database/migrations/tenant` paths in module order

## Cross-Module Dependencies

- **Platform** depends on **Identity** (seeds tenant users/roles during provisioning)
- **Core** is shared by all modules (tenancy, middleware)
- Modules communicate via public model/application interfaces — avoid reaching into another module's internals

## Alignment with Frontend Monorepo

| Frontend Package/App | API Module |
|---|---|
| `@zcmss/api-client` central endpoints | Platform + Identity |
| `@zcmss/api-client` tenant endpoints | Identity + Crm + Activity + Hr |
| `@zcmss/types` | Shared API contract (types mirror module resources) |
| Companyten CRM UI (`apps/companyten`) | Crm + Activity + Hr modules |