# Architecture

## Tenant Isolation

The default model uses a shared database with `tenant_id` on operational tables. Every tenant-scoped API must apply tenant middleware, tenant-aware policies, and query scopes. This keeps deployment simple while supporting strong logical isolation.

For regulated clients, the same application can be extended to database-per-tenant by replacing the tenant resolver and connection manager.

## Modules

Modules are package-controlled feature gates. Package `features` determine access to attendance, payroll, leave, finance, API access, GPS, face recognition, holiday OT, and shift management.

## Realtime Events

Recommended event channels:

- `super-admin.monitoring` for global client, device, and attendance activity.
- `tenant.{tenantId}.dashboard` for company-specific dashboard metrics.
- `tenant.{tenantId}.devices` for device online/offline and sync status.
- `tenant.{tenantId}.payroll` for payroll generation progress.

## Queues

Queue these workloads:

- Device log sync.
- Attendance recalculation.
- Rule evaluation.
- Payroll generation.
- Report exports.
- Invoice and renewal notifications.
- Contract expiry reminders.

## Security

- Use Sanctum or OAuth2 tokens for API clients.
- Encrypt device secrets and integration tokens.
- Enforce role permissions at route, policy, and UI levels.
- Store audit logs for mutations and login activities.
- Add IP whitelist checks for admin and device routes.