# Design

## Architecture

This task keeps the app in a single Next.js project and adds a small server-side domain layer inside `modules/`:

- `modules/core/server/`: server-only persistence, session, permissions, and audit helpers.
- `modules/auth/`: UI and client interactions for setup, login, logout, and session state.
- `modules/elders/`: elder schemas/types, server actions or API client helpers, and UI components.
- `modules/settings/`: role/account/audit display components.
- `app/api/.../route.ts`: Route Handlers for auth, session, elders, accounts, and audit APIs.

The persistence boundary should be centralized behind helper functions that read/write JSON files. UI and route handlers must not know file paths directly.

## Data Storage

Use a JSON file store under `.data/teatea.json` by default. The file should contain:

```ts
type AppData = {
  accounts: Account[];
  sessions: Session[];
  elders: Elder[];
  auditLogs: AuditLog[];
};
```

The store module owns initialization, read, write, and update operations. Updates should read the current snapshot, apply a synchronous mutation callback, and write the full file back. This is enough for the MVP and gives a clear future replacement boundary for Drizzle/Postgres.

## API Contracts

Route Handlers return a consistent response shape:

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

Planned endpoints:

- `GET /api/auth/bootstrap`: returns whether setup is required.
- `POST /api/auth/setup`: creates the first admin account, creates a session, logs setup.
- `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 and permissions.
- `GET /api/elders`: lists elder profiles.
- `POST /api/elders`: creates an elder profile.
- `PATCH /api/elders/[id]`: updates an elder profile.
- `DELETE /api/elders/[id]`: deletes an elder profile.
- `GET /api/settings/accounts`: lists accounts for authorized roles.
- `GET /api/settings/roles`: lists built-in role definitions.
- `GET /api/audit-logs`: lists recent audit events.

## Authentication

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

Passwords are never stored in plain text. For the MVP, use Node built-in crypto with a per-account salt and `scryptSync` or `scrypt` for password hashing. This avoids adding a dependency while keeping the current local milestone meaningfully better than browser-only auth.

## Permissions

Define built-in role permissions in one server/shared constants module:

- `account:read`
- `account:manage`
- `audit:read`
- `elder:read`
- `elder:create`
- `elder:update`
- `elder:delete`

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

## Audit Logging

Audit logging is implemented as a server helper that appends immutable records to the store:

- timestamp
- actor account ID/email if known
- action
- target type
- target ID
- result: `success` or `denied` or `failure`
- reason

Audit writes are part of the route handler flow. The MVP accepts best-effort logging for logout when a session has already expired.

## UI Flow

Protected app pages should use server session state where practical instead of a client-only `AuthGate`. The app layout can fetch session data and redirect unauthenticated users before rendering protected content.

The elder page becomes a real data view:

- Server Component loads initial elders.
- Client component handles create/edit/delete forms and refreshes after mutations.
- Controls are disabled or hidden based on current permissions.

The settings page becomes a server-loaded administrative view:

- Role definitions table.
- Accounts table.
- Recent audit log table.

## 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, and Tailwind/Radix-compatible UI components.

## Risks and Rollback

- File persistence is not safe for high-concurrency production writes. This is acceptable for MVP and documented as a migration boundary.
- Replacing `AuthGate` with server-side auth can affect all `/app` routes. Rollback point: keep the old component until server session redirect is working.
- Password hashing must use Node runtime APIs, so affected Route Handlers should run in the Node runtime if needed.