40227-vm/docs/development-path.md

# Development Path

## Context

The repository currently contains three relevant parts:

- `backend/`: generated Node.js/Express backend with PostgreSQL, Sequelize models, JWT auth, roles, permissions, email services, file handling, Swagger, and school-domain entities.
- `frontend/`: customer-approved Vite/React interface with Tailwind, Radix/shadcn UI, React Query, role-based modules, backend API integration, and intentionally static product content. This is the frontend that will be developed going forward.
- `ref-frontend/`: generated Next.js frontend with CRUD pages and Redux slices for the generated backend entities. This is a temporary reference only and can be removed after the working frontend is fully integrated.

The customer-approved interface defines the expected product experience. The generated backend already covers much of the SaaS infrastructure and core school-chain data model.

## Decision

Use `frontend/` as the product frontend base and keep `backend/` as the backend base.

Do not continue building on the generated Next.js frontend UI in `ref-frontend/`. Its most useful parts are API usage patterns, auth flow, entity coverage, and contracts with the generated backend. The visual layer and user workflows should come from `frontend/`.

## Rationale

This path is the least risky and most direct because:

- The approved UI is already in `frontend/`; rebuilding it inside the generated reference frontend would duplicate work and risk visual drift.
- The generated backend already has entities for organizations, campuses, staff, students, guardians, classes, attendance, assessments, messages, documents, roles, permissions, invoices, payments, and email flows.
- The generated reference frontend uses a different stack from the approved UI: Next.js, MUI, Redux, and i18n. The active approved UI uses Vite, React 19, Tailwind, Radix/shadcn, React Query, and lucide icons.
- The approved UI must use the backend for authentication, tenant scoping, permissions, and persisted data ownership.
- Replacing the generated frontend with the approved UI plus a typed API client preserves the approved UX while keeping SaaS infrastructure centralized in the existing backend.

## Migration Plan

### 1. Frontend Replacement

The generated `frontend/` application has been moved to `ref-frontend/`, and the approved UI has been moved into `frontend/`.

Keep and adapt:

- Tailwind/Radix/shadcn UI components.
- Customer-approved module layout and styling.
- Role-based module navigation.
- React Query-based data loading.
- Vite build pipeline unless deployment constraints require Next.js.

Remove or replace:

- Direct browser-to-database access from app code.
- Demo role switcher in production mode.
- Silent mock/static data behavior for data that must be persisted.
- Inline `console.error` handling in data functions.
- Directly embedded demo users and static campus assumptions where backend data should be authoritative.

### 2. Frontend API Layer

Create a dedicated frontend API layer that talks to `backend/`.

Recommended structure:

- `frontend/src/shared/api/httpClient.ts`
- `frontend/src/shared/api/auth.ts`
- `frontend/src/shared/api/campuses.ts`
- `frontend/src/shared/api/staff.ts`
- `frontend/src/shared/api/frameworks.ts`
- `frontend/src/shared/api/attendance.ts`
- `frontend/src/shared/api/messages.ts`
- `frontend/src/shared/api/documents.ts`

Use aliases with `@` for all imports. Keep response and request types strict. Do not introduce `any` or casts.

### 3. Backend Alignment

Keep the generated backend and extend it where the approved UI has modules that do not map cleanly to existing entities.

Existing backend coverage:

- Multi-tenant base: `organizations` and organization links across generated entities.
- Campuses: `campuses`.
- Staff and users: `staff`, `users`, `roles`, `permissions`.
- Attendance: `attendance_sessions`, `attendance_records`.
- Communication: `messages`, `message_recipients`.
- Documents and policies: `documents`, `file`.
- Academic records: `classes`, `students`, `guardians`, `assessments`, `assessment_results`.
- Finance-related base: `fee_plans`, `invoices`, `payments`.

Likely new backend modules needed:

- FRAME weekly entries.
- Staff zone check-ins and progress.
- Safety quiz results.
- Personality quiz results.
- Walk-through check-ins.
- Campus attendance summaries/configuration if the existing attendance model is not enough.
- Content catalog for classroom strategies, signs, handbook/policies, community services, vocational opportunities, and ESA content if these need admin editing.

### 4. Multi-Tenancy

Use `organizations` as the tenant boundary.

Required work:

- Ensure every tenant-owned query is scoped by `currentUser.organizationId` or equivalent organization relation.
- Keep global access only for true platform/admin roles.
- Verify create/update/delete operations cannot cross tenant boundaries.
- Add tests for tenant isolation on high-risk entities: users, staff, campuses, students, attendance, messages, documents, and new customer UI modules.

### 5. Auth And Roles

Use backend JWT auth as the source of truth.

Map approved UI roles to backend roles/permissions:

- `teacher`
- `para`
- `office`
- `director`
- `superintendent`

Required work:

- Keep auth context backed by the backend JWT API.
- Load current user from `/api/auth/me`.
- Derive role and campus from backend user/staff profile.
- Enforce access both in frontend navigation and backend permissions.
- Keep UI route hiding as convenience only; backend authorization must be authoritative.

### 6. Error Handling

Backend:

- Use centralized exception classes instead of ad hoc errors.
- Remove direct logging from business logic where centralized error handling should own observability.

Frontend:

- Replace silent returns such as `return []`, `return false`, or `return null` after failed API calls with explicit error states.
- Show user-facing errors using the existing toast/error UI.
- Keep native external-service errors from Gemini/OpenAI unchanged where applicable.

### 7. Documentation

For each migrated module:

- Add or update backend docs in `backend/docs/`.
- Add frontend module docs in `frontend/docs/`.
- Document API contracts, permissions, tenant behavior, and known operational assumptions.

## Implementation Order

1. Make the Vite React application in `frontend/` build in place.
2. Add frontend shared constants and aliases.
3. Keep frontend auth integrated with backend JWT auth.
4. Add typed HTTP client and convert one vertical slice end-to-end, starting with campuses/staff/profile.
5. Convert role navigation to backend roles and permissions.
6. Convert FRAME weekly entries.
7. Convert attendance and walk-through modules.
8. Convert messaging, safety quiz results, personality quiz results, progress, and document/policy modules.
9. Add tenant isolation tests and API integration tests.
10. Remove `ref-frontend/` after the product frontend no longer needs the generated reference contracts.

## Rejected Alternative

Adapting the generated Next.js frontend in `ref-frontend/` to look and behave like the product frontend is not recommended.

Reasons:

- It preserves generated CRUD pages that are not the approved customer experience.
- It requires rebuilding the approved interaction model in a different UI stack.
- It keeps more generated code alive than needed.
- It increases the chance of divergence between the approved interface and the shipped product.

## Open Questions

- Should the production frontend remain Vite, or is Next.js required by hosting/deployment constraints?
- Which product frontend modules must be editable by admins versus shipped as static curated content?
- Which product modules should be implemented immediately after auth/profile and staff profile integration?
- What is the final role naming expected in user-facing copy?
- Which email flows are required for launch: invite, verification, password reset, parent communication, staff notifications?