# Architecture Notes

## Tenancy model
Shared database, shared schema. Tenant-owned operational rows carry `tenant_id`; school-owned rows additionally carry `school_id`. Platform catalog tables such as subscription plans and permissions are global.

## Tenant resolution
The `tenant` middleware resolves context from `X-Tenant-ID` or the session. It requires authentication, active tenant status, and membership. Platform administrators can access a tenant context but still should use explicit audit logging for support access.

## Security invariants
- Client-supplied tenant identifiers are selectors, never authorization.
- Tenant membership is verified on every request.
- New tenant-owned models must scope every read/write by tenant.
- Use composite unique constraints for tenant-local identifiers.
- Apply policies to all sensitive actions.
- Add regression tests for cross-tenant read/write attempts.

## Subscription lifecycle
Subscriptions currently support trial, active, past_due, suspended, cancelled and expired states. Beta 1 creates a 14-day trial during tenant registration. Payment processing and enforcement are not yet implemented.