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.organizationsId 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?