# Design

## Architecture

This task keeps the app in a single Next.js project and continues the Drizzle/PostgreSQL-backed server domain layer inside `modules/`:

- `modules/core/server/`: Drizzle connection, schema, session, permissions, audit helpers, and compatibility read models.
- `modules/auth/`: UI and client interactions for setup, register, login, logout, and session state.
- `modules/elders/`: elder schemas/types, validation, and CRUD UI components.
- `modules/settings/`: role/account/organization/audit/status display and management components.
- `modules/facilities` or existing page-local modules: room, bed, occupancy, admission, transfer, and discharge UI as the feature grows.
- `app/api/.../route.ts`: Route Handlers for auth, session, elders, facilities, admissions, accounts, roles, organizations, status, and audit APIs.

The persistence boundary is now Drizzle/PostgreSQL, not JSON files. UI and route handlers should use domain helpers or direct Drizzle queries through `getDatabase()` in server-only modules. New mutation paths must not use `writeData()` or `updateData()`.

## Data Storage

The current persistent model is PostgreSQL with Drizzle schema in `modules/core/server/schema.ts` and generated migrations under `drizzle/`.

Important existing tables:

- Identity and tenancy: `accounts`, `sessions`, `organizations`, `memberships`, `join_requests`, `organization_invitations`.
- Authorization: `roles`, `permissions`, `role_permissions`.
- Operations: `elders`, `rooms`, `beds`, `admissions`.
- Governance and status: `audit_logs`, `system_incidents`, `system_settings`.

`modules/core/server/store.ts` should be treated as a compatibility read model only:

- `readData()` may aggregate Drizzle rows into existing UI-friendly types while legacy pages are migrated.
- `writeData()` and `updateData()` intentionally throw after the PostgreSQL migration.
- New feature work should prefer focused query helpers so the compatibility model does not become the long-term domain layer.

## API Contracts

Route Handlers return a consistent response shape:

```ts
type ApiResult<T extends Record<string, unknown>> =
  | ({ success: true; reason: string } & T)
  | { success: false; reason: string };
```

Existing or expected endpoints:

- `GET /api/auth/bootstrap`: returns whether setup is required.
- `POST /api/auth/setup`: creates the first platform admin, first organization, session, roles/membership, and audit log.
- `POST /api/auth/register`: creates a user registration or invitation-based account flow where enabled.
- `POST /api/auth/login`: validates credentials, creates a session, logs login.
- `POST /api/auth/logout`: deletes current session cookie/session, logs logout.
- `GET /api/auth/session`: returns current account, organization, membership, and permissions.
- `GET /api/elders`: lists elder profiles for the active organization.
- `POST /api/elders`: creates an elder profile and optional active admission.
- `PATCH /api/elders/[id]`: updates an elder profile.
- `DELETE /api/elders/[id]`: deletes an elder profile.
- `GET /api/facilities/rooms`: lists rooms for the active organization.
- `POST /api/facilities/rooms`: creates room records when facility management UI exposes this.
- `GET /api/facilities/beds`: lists beds and current occupancy.
- `POST /api/facilities/beds`: creates bed records when facility management UI exposes this.
- `GET /api/admissions`: lists admission and transfer history.
- `POST /api/admissions`: admits or transfers an elder into an available bed.
- Planned: `PATCH /api/admissions/[id]` or equivalent mutation endpoint for transfer/discharge if POST cannot express the workflow cleanly.
- `GET /api/settings/accounts`: lists accounts for authorized roles.
- `GET /api/settings/roles`: lists built-in and organization roles.
- `GET /api/settings/permissions`: lists permission coverage.
- `GET /api/audit-logs`: lists recent audit events.

## Authentication

Sessions use an HTTP-only cookie named `teatea_session`. Route Handlers read and write cookies with `await cookies()` from `next/headers`, matching current Next.js behavior.

Passwords are never stored in plain text. The current implementation uses Node built-in crypto with per-account salt and `scryptSync`, which is acceptable for this local MVP until a dedicated auth library is introduced in a separate task.

Protected app routes should use server session state where practical instead of client-only localStorage guards. Server-rendered pages that depend on session cookies must opt out of static prerendering with `export const dynamic = "force-dynamic"` where needed.

## Permissions

Permissions and role definitions live in the core server/shared type boundary:

- Platform: `platform:manage`, `organization:read`, `organization:manage`.
- Account/role/security: `account:read`, `account:manage`, `role:read`, `role:manage`, `permission:read`, `audit:read`.
- Operations: `facility:read`, `facility:manage`, `admission:read`, `admission:manage`, `elder:read`, `elder:create`, `elder:update`, `elder:delete`.
- Status: `incident:read`, `incident:manage`.

Route Handlers call a shared `requirePermission(permission)` helper. This helper returns an authenticated context or a structured forbidden/unauthorized response and writes denied audit entries.

## Admission Transactions

Bed/admission mutations must run inside a Drizzle transaction.

Admit flow:

1. Validate active organization and `admission:manage`.
2. Validate elder belongs to the active organization.
3. Validate target bed belongs to the active organization and has status `available`.
4. Close or transfer any active admission for that elder if the operation is a transfer.
5. Insert a new `admissions` row with status `active`.
6. Set target bed status to `occupied`.
7. Set elder status to `active`.
8. Record an audit log.

Transfer flow:

1. Find active admission for the elder.
2. Set previous admission status to `transferred` and `dischargedAt` to now.
3. Set previous bed status to `available`.
4. Insert the new active admission and occupy the target bed.
5. Record an audit log.

Discharge flow:

1. Find active admission.
2. Set admission status to `discharged` and `dischargedAt` to now.
3. Set bed status to `available`.
4. Set elder status to `discharged` or another explicitly selected status.
5. Record an audit log.

All conflict checks must return structured API failures rather than partially mutating state.

## UI Flow

The app should remain an operational workspace: dense, restrained, and action-oriented.

Elder page:

- Server Component loads initial elders and available beds.
- Client component handles create/edit/delete forms and refreshes after mutations.
- Controls are disabled or hidden based on current permissions, while APIs still enforce permission checks.

Bed/admission page:

- Replace raw API placeholders with page-local controls.
- Use tabs or segmented navigation for overview, bed status, admissions/history, and management actions.
- Place admit/transfer/discharge actions inside the bed/admission workspace, not as a dead global top-bar button.
- Show occupancy metrics, active admissions, room/bed tables, and history from Drizzle-backed data.

Dashboard:

- Replace hard-coded counters for implemented domains with Drizzle-backed data.
- Use a standard chart library for selected charts such as occupancy distribution or admission activity.
- Keep chart usage modest; tables and status lists remain the primary record surfaces.

Screenshot feedback:

- Move page-level secondary navigation into tabs where appropriate.
- Remove oversized intro/hero blocks from routine operational pages.
- Remove redundant header action controls that are not wired to the current page workflow.

## Compatibility

Static module pages not in scope remain untouched except for auth/layout integration. Existing visual design should be preserved: dense operational screens, restrained cards/tables, project UI adapters under `components/ui/*`, and Tailwind-compatible layout.

## Risks and Rollback

- Drizzle schema and migrations are now the persistence source of truth; mismatches between schema and migrations can block deployment. Rollback point: keep migration changes separate from UI-only work.
- Admission mutations touch multiple tables. Rollback point: keep transaction helpers isolated and temporarily render read-only admission data if mutation UI is unstable.
- Replacing global header actions can affect user navigation habits. Rollback point: remove only the dead top-bar "入住" button while keeping the sidebar and pages stable.
- Adding a chart library increases client bundle size. Rollback point: limit chart usage to one focused client component and keep tables as the fallback data surface.