# enticra/school architecture

> Architecture diagram of the GitHub repository enticra/school, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enticra/school
- Repository: https://github.com/enticra/school

## Overview

Enticra School is a multi-school portal for staff, parents and administrators. Users sign in, then the React portal dispatches role-specific actions through an API abstraction to the shared Portal domain service; it enforces tenant and role access while managing attendance, homework, assessments, AI-assisted script correction, student profiles, reports, school settings and parent messaging. The API persists domain state in PostgreSQL and records WhatsApp messages; the README says delivery is simulated. The browser demo instead runs the domain locally with localStorage. Some showcase areas are documented in the tree but their runtime wiring was not sampled, so their links are conservative.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/enticra/school/blob/main/apps/web/src/App.tsx) (Role-based portal), [`apps/web/src/ui.tsx`](https://github.com/enticra/school/blob/main/apps/web/src/ui.tsx) (Shared UI and data hooks), [`apps/api/src/app.ts`](https://github.com/enticra/school/blob/main/apps/api/src/app.ts) (RPC and HTTP server), [`packages/core/src/portal.ts`](https://github.com/enticra/school/blob/main/packages/core/src/portal.ts) (Portal domain service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web portal"]
  node_portal_ui["Role-based portal<br/>[App.tsx]"]
  node_api_client["API and demo client<br/>[api.ts]"]
  node_attendance_ui["Attendance screens<br/>[Attendance.tsx]"]
  node_homework_ui["Homework screens<br/>[Homework.tsx]"]
  node_tests_ui["Tests and marks<br/>[Tests.tsx]"]
  node_correction_ui["Script correction<br/>[Correction.tsx]"]
  node_student_ui["Student profiles<br/>[Students.tsx]"]
  node_reports_ui["Reports<br/>[Reports.tsx]"]
  node_messages_ui["Message history<br/>[Messages.tsx]"]
  node_admin_ui["School administration<br/>[Admin.tsx]"]
  node_academic_showcase["Academic tools<br/>[Academics.tsx]"]
  node_engagement_showcase["Family engagement<br/>[Engage.tsx]"]
  node_exam_showcase["Exam tools<br/>[Exams.tsx]"]
  node_office_showcase["School office<br/>[Office.tsx]"]
  node_people_showcase["People tools<br/>[People.tsx]"]
  node_school_showcase["School tools<br/>[School.tsx]"]
  node_staff_showcase["Staff desk<br/>[StaffDesk.tsx]"]
  node_family_showcase["Parent tools<br/>[Family.tsx]"]
  node_student_app["Student app<br/>[StudentApp.tsx]"]
  node_shared_ui["Shared UI and data hooks<br/>[ui.tsx]"]
end

subgraph group_domain["School domain"]
  node_portal_domain["Portal domain service<br/>[portal.ts]"]
  node_grading["Grading engine<br/>[grading.ts]"]
  node_exam_seating["Exam seating<br/>[seating.ts]"]
  node_message_templates["Message templates<br/>[templates.ts]"]
  node_domain_types["Tenant domain model<br/>[types.ts]"]
  node_seed_data["Sample school data<br/>[seed.ts]"]
end

subgraph group_backend["API services"]
  node_api_server["RPC and HTTP server<br/>[app.ts]"]
  node_auth["Phone OTP auth<br/>[auth.ts]"]
  node_page_prep["Script page preparation<br/>[pages.ts]"]
  node_claude_grader["Claude vision grader<br/>[claudeGrader.ts]"]
end

subgraph group_state["Persistence and messaging"]
  node_db_store[("PostgreSQL storage<br/>[store.ts]")]
  node_whatsapp["WhatsApp outbox<br/>[whatsapp.ts]"]
end

node_users(("School users"))
node_whatsapp_service["WhatsApp service"]

node_users -->|"use"| node_portal_ui
node_portal_ui -->|"dispatches actions"| node_api_client
node_portal_ui -->|"renders"| node_attendance_ui
node_portal_ui -->|"renders"| node_homework_ui
node_portal_ui -->|"renders"| node_tests_ui
node_portal_ui -->|"renders"| node_correction_ui
node_portal_ui -->|"renders"| node_student_ui
node_portal_ui -->|"renders"| node_reports_ui
node_portal_ui -->|"renders"| node_messages_ui
node_portal_ui -->|"renders"| node_admin_ui
node_portal_ui -->|"routes to"| node_academic_showcase
node_portal_ui -->|"routes to"| node_exam_showcase
node_portal_ui -->|"routes to"| node_office_showcase
node_portal_ui -->|"routes to"| node_family_showcase
node_api_client -->|"invokes methods"| node_portal_domain
node_api_client -->|"loads demo data"| node_seed_data
node_attendance_ui -.->|"uses hooks"| node_shared_ui
node_homework_ui -->|"uses hooks"| node_shared_ui
node_correction_ui -->|"uploads pages"| node_api_client
node_correction_ui -->|"uses hooks"| node_shared_ui
node_student_ui -->|"uses hooks"| node_shared_ui
node_reports_ui -->|"uses document tools"| node_shared_ui
node_messages_ui -->|"calls API"| node_api_client
node_messages_ui -->|"uses hooks"| node_shared_ui
node_admin_ui -->|"uses UI"| node_shared_ui
node_school_showcase -->|"uses UI"| node_shared_ui
node_engagement_showcase -->|"uses UI"| node_shared_ui
node_people_showcase -->|"uses tools"| node_staff_showcase
node_family_showcase -->|"uses tools"| node_engagement_showcase
node_student_app -->|"uses tools"| node_people_showcase
node_student_app -->|"uses tools"| node_academic_showcase
node_api_server -->|"dispatches RPC"| node_portal_domain
node_api_server -->|"authenticates"| node_auth
node_api_server -->|"prepares uploads"| node_page_prep
node_api_server -->|"configures delivery"| node_whatsapp
node_api_server -->|"persists state"| node_db_store
node_api_server -->|"configures grader"| node_claude_grader
node_portal_domain -->|"uses grading"| node_grading
node_portal_domain -->|"uses seating"| node_exam_seating
node_portal_domain -->|"renders messages"| node_message_templates
node_portal_domain -->|"uses model"| node_domain_types
node_seed_data -->|"renders samples"| node_message_templates
node_whatsapp -.->|"optional live send"| node_whatsapp_service
node_api_client -->|"stores local demo"| node_db_store

click node_portal_ui "https://github.com/enticra/school/blob/main/apps/web/src/App.tsx"
click node_api_client "https://github.com/enticra/school/blob/main/apps/web/src/api.ts"
click node_attendance_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Attendance.tsx"
click node_homework_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Homework.tsx"
click node_tests_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Tests.tsx"
click node_correction_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Correction.tsx"
click node_student_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Students.tsx"
click node_reports_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Reports.tsx"
click node_messages_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Messages.tsx"
click node_admin_ui "https://github.com/enticra/school/blob/main/apps/web/src/pages/Admin.tsx"
click node_academic_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/Academics.tsx"
click node_engagement_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/Engage.tsx"
click node_exam_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/Exams.tsx"
click node_office_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/Office.tsx"
click node_people_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/People.tsx"
click node_school_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/School.tsx"
click node_staff_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/StaffDesk.tsx"
click node_family_showcase "https://github.com/enticra/school/blob/main/apps/web/src/showcase/Family.tsx"
click node_student_app "https://github.com/enticra/school/blob/main/apps/web/src/showcase/StudentApp.tsx"
click node_shared_ui "https://github.com/enticra/school/blob/main/apps/web/src/ui.tsx"
click node_portal_domain "https://github.com/enticra/school/blob/main/packages/core/src/portal.ts"
click node_grading "https://github.com/enticra/school/blob/main/packages/core/src/grading.ts"
click node_exam_seating "https://github.com/enticra/school/blob/main/packages/core/src/seating.ts"
click node_message_templates "https://github.com/enticra/school/blob/main/packages/core/src/templates.ts"
click node_domain_types "https://github.com/enticra/school/blob/main/packages/core/src/types.ts"
click node_seed_data "https://github.com/enticra/school/blob/main/packages/core/src/seed.ts"
click node_api_server "https://github.com/enticra/school/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/enticra/school/blob/main/apps/api/src/auth.ts"
click node_page_prep "https://github.com/enticra/school/blob/main/apps/api/src/pages.ts"
click node_claude_grader "https://github.com/enticra/school/blob/main/apps/api/src/claudeGrader.ts"
click node_db_store "https://github.com/enticra/school/blob/main/apps/api/src/store.ts"
click node_whatsapp "https://github.com/enticra/school/blob/main/apps/api/src/whatsapp.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_portal_ui,node_api_client,node_attendance_ui,node_homework_ui,node_tests_ui,node_correction_ui,node_student_ui,node_reports_ui,node_messages_ui,node_admin_ui,node_academic_showcase,node_engagement_showcase,node_exam_showcase,node_office_showcase,node_people_showcase,node_school_showcase,node_staff_showcase,node_family_showcase,node_student_app,node_shared_ui,node_users toneBlue
class node_portal_domain,node_grading,node_exam_seating,node_message_templates,node_domain_types,node_seed_data toneAmber
class node_api_server,node_auth,node_page_prep,node_claude_grader toneMint
class node_db_store,node_whatsapp toneRose
class node_whatsapp_service toneIndigo
```

## Components

### Web portal

- [Role-based portal](https://github.com/enticra/school/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API and demo client](https://github.com/enticra/school/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Attendance screens](https://github.com/enticra/school/blob/main/apps/web/src/pages/Attendance.tsx): `apps/web/src/pages/Attendance.tsx`
- [Homework screens](https://github.com/enticra/school/blob/main/apps/web/src/pages/Homework.tsx): `apps/web/src/pages/Homework.tsx`
- [Tests and marks](https://github.com/enticra/school/blob/main/apps/web/src/pages/Tests.tsx): `apps/web/src/pages/Tests.tsx`
- [Script correction](https://github.com/enticra/school/blob/main/apps/web/src/pages/Correction.tsx): `apps/web/src/pages/Correction.tsx`
- [Student profiles](https://github.com/enticra/school/blob/main/apps/web/src/pages/Students.tsx): `apps/web/src/pages/Students.tsx`
- [Reports](https://github.com/enticra/school/blob/main/apps/web/src/pages/Reports.tsx): `apps/web/src/pages/Reports.tsx`
- [Message history](https://github.com/enticra/school/blob/main/apps/web/src/pages/Messages.tsx): `apps/web/src/pages/Messages.tsx`
- [School administration](https://github.com/enticra/school/blob/main/apps/web/src/pages/Admin.tsx): `apps/web/src/pages/Admin.tsx`
- [Academic tools](https://github.com/enticra/school/blob/main/apps/web/src/showcase/Academics.tsx): `apps/web/src/showcase/Academics.tsx`
- [Family engagement](https://github.com/enticra/school/blob/main/apps/web/src/showcase/Engage.tsx): `apps/web/src/showcase/Engage.tsx`
- [Exam tools](https://github.com/enticra/school/blob/main/apps/web/src/showcase/Exams.tsx): `apps/web/src/showcase/Exams.tsx`
- [School office](https://github.com/enticra/school/blob/main/apps/web/src/showcase/Office.tsx): `apps/web/src/showcase/Office.tsx`
- [People tools](https://github.com/enticra/school/blob/main/apps/web/src/showcase/People.tsx): `apps/web/src/showcase/People.tsx`
- [School tools](https://github.com/enticra/school/blob/main/apps/web/src/showcase/School.tsx): `apps/web/src/showcase/School.tsx`
- [Staff desk](https://github.com/enticra/school/blob/main/apps/web/src/showcase/StaffDesk.tsx): `apps/web/src/showcase/StaffDesk.tsx`
- [Parent tools](https://github.com/enticra/school/blob/main/apps/web/src/showcase/Family.tsx): `apps/web/src/showcase/Family.tsx`
- [Student app](https://github.com/enticra/school/blob/main/apps/web/src/showcase/StudentApp.tsx): `apps/web/src/showcase/StudentApp.tsx`
- [Shared UI and data hooks](https://github.com/enticra/school/blob/main/apps/web/src/ui.tsx): `apps/web/src/ui.tsx`

### School domain

- [Portal domain service](https://github.com/enticra/school/blob/main/packages/core/src/portal.ts): `packages/core/src/portal.ts`
- [Grading engine](https://github.com/enticra/school/blob/main/packages/core/src/grading.ts): `packages/core/src/grading.ts`
- [Exam seating](https://github.com/enticra/school/blob/main/packages/core/src/seating.ts): `packages/core/src/seating.ts`
- [Message templates](https://github.com/enticra/school/blob/main/packages/core/src/templates.ts): `packages/core/src/templates.ts`
- [Tenant domain model](https://github.com/enticra/school/blob/main/packages/core/src/types.ts): `packages/core/src/types.ts`
- [Sample school data](https://github.com/enticra/school/blob/main/packages/core/src/seed.ts): `packages/core/src/seed.ts`

### API services

- [RPC and HTTP server](https://github.com/enticra/school/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Phone OTP auth](https://github.com/enticra/school/blob/main/apps/api/src/auth.ts): `apps/api/src/auth.ts`
- [Script page preparation](https://github.com/enticra/school/blob/main/apps/api/src/pages.ts): `apps/api/src/pages.ts`
- [Claude vision grader](https://github.com/enticra/school/blob/main/apps/api/src/claudeGrader.ts): `apps/api/src/claudeGrader.ts`

### Persistence and messaging

- [PostgreSQL storage](https://github.com/enticra/school/blob/main/apps/api/src/store.ts): `apps/api/src/store.ts`
- [WhatsApp outbox](https://github.com/enticra/school/blob/main/apps/api/src/whatsapp.ts): `apps/api/src/whatsapp.ts`

### Other components

- **School users**
- **WhatsApp service**

## Connections

- School users → Role-based portal: use (evidence: `apps/web/src/App.tsx`)
- Role-based portal → API and demo client: dispatches actions (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Attendance screens: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Homework screens: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Tests and marks: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Script correction: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Student profiles: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Reports: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Message history: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → School administration: renders (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Academic tools: routes to (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Exam tools: routes to (evidence: `apps/web/src/App.tsx`)
- Role-based portal → School office: routes to (evidence: `apps/web/src/App.tsx`)
- Role-based portal → Parent tools: routes to (evidence: `apps/web/src/App.tsx`)
- API and demo client → Portal domain service: invokes methods (evidence: `apps/web/src/api.ts`)
- API and demo client → Sample school data: loads demo data (evidence: `apps/web/src/api.ts`)
- Attendance screens → Shared UI and data hooks: uses hooks
- Homework screens → Shared UI and data hooks: uses hooks (evidence: `apps/web/src/pages/Homework.tsx`)
- Script correction → API and demo client: uploads pages (evidence: `apps/web/src/pages/Correction.tsx`)
- Script correction → Shared UI and data hooks: uses hooks (evidence: `apps/web/src/pages/Correction.tsx`)
- Student profiles → Shared UI and data hooks: uses hooks (evidence: `apps/web/src/pages/Students.tsx`)
- Reports → Shared UI and data hooks: uses document tools (evidence: `apps/web/src/pages/Reports.tsx`)
- Message history → API and demo client: calls API (evidence: `apps/web/src/pages/Messages.tsx`)
- Message history → Shared UI and data hooks: uses hooks (evidence: `apps/web/src/pages/Messages.tsx`)
- School administration → Shared UI and data hooks: uses UI (evidence: `apps/web/src/pages/Admin.tsx`)
- School tools → Shared UI and data hooks: uses UI (evidence: `apps/web/src/showcase/School.tsx`)
- Family engagement → Shared UI and data hooks: uses UI (evidence: `apps/web/src/showcase/Engage.tsx`)
- People tools → Staff desk: uses tools (evidence: `apps/web/src/showcase/People.tsx`)
- Parent tools → Family engagement: uses tools (evidence: `apps/web/src/showcase/Family.tsx`)
- Student app → People tools: uses tools (evidence: `apps/web/src/showcase/StudentApp.tsx`)
- Student app → Academic tools: uses tools (evidence: `apps/web/src/showcase/StudentApp.tsx`)
- RPC and HTTP server → Portal domain service: dispatches RPC (evidence: `apps/api/src/app.ts`)
- RPC and HTTP server → Phone OTP auth: authenticates (evidence: `apps/api/src/app.ts`)
- RPC and HTTP server → Script page preparation: prepares uploads (evidence: `apps/api/src/app.ts`)
- RPC and HTTP server → WhatsApp outbox: configures delivery (evidence: `apps/api/src/app.ts`)
- RPC and HTTP server → PostgreSQL storage: persists state (evidence: `apps/api/src/server.ts`)
- RPC and HTTP server → Claude vision grader: configures grader (evidence: `apps/api/src/server.ts`)
- Portal domain service → Grading engine: uses grading (evidence: `packages/core/src/portal.ts`)
- Portal domain service → Exam seating: uses seating (evidence: `packages/core/src/portal.ts`)
- Portal domain service → Message templates: renders messages (evidence: `packages/core/src/portal.ts`)
- Portal domain service → Tenant domain model: uses model (evidence: `packages/core/src/portal.ts`)
- Sample school data → Message templates: renders samples (evidence: `packages/core/src/seed.ts`)
- WhatsApp outbox → WhatsApp service: optional live send (evidence: `apps/api/src/whatsapp.ts`)
- API and demo client → PostgreSQL storage: stores local demo (evidence: `apps/web/src/api.ts`)
