# arun-devcode/cohort-analysis-platform architecture

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

- Interactive diagram: https://gitdiagram.com/arun-devcode/cohort-analysis-platform
- Repository: https://github.com/arun-devcode/cohort-analysis-platform

## Overview

This is a student-progress platform for managing training batches and reviewing learner outcomes across uploaded workbook snapshots. The main workflow is to authenticate, upload a report, ingest it into a batch snapshot, and explore analytics, comparisons, attendance, assignments, content consumption, at-risk learners, and reports. Follow-ups, student profiles, settings, and backup are additional product areas. The tree and excerpts show several server-side call paths; most frontend wiring and unsampled service internals are not shown, so those links are omitted or marked unverified.

Main entry points: [`server/src/db/schema/index.ts`](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/db/schema/index.ts) (PostgreSQL data), [`app/src/core/api/client.ts`](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/core/api/client.ts) (API client), [`server/src/routes/batch.routes.ts`](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/routes/batch.routes.ts) (Batch API routes), [`app/src/App.tsx`](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/App.tsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Application shell<br/>[App.tsx]"]
  node_upload_ui["Workbook upload<br/>[UploadModal.tsx]"]
  node_client_parse["Workbook parsing<br/>[workbookParser.ts]"]
  node_api_client["API client<br/>[client.ts]"]
  node_auth_ui["Authentication<br/>[AuthPage.tsx]"]
  node_dashboard["Progress dashboard"]
  node_compare_ui["Snapshot comparison<br/>[CompareView.tsx]"]
end

subgraph group_api["API and access"]
  node_batch_routes["Batch API routes<br/>[batch.routes.ts]"]
  node_batch_controller["Batch operations"]
  node_auth_controller["Account operations<br/>[auth.controller.ts]"]
  node_auth_service["Token and password service<br/>[auth.service.ts]"]
end

subgraph group_ingest["Workbook ingestion"]
  node_ingestion_controller["Upload handling"]
  node_ingestion_service["Workbook ingestion<br/>[index.ts]"]
end

subgraph group_insights["Progress insights"]
  node_analytics_controller["Analytics endpoints"]
  node_analytics_service["Analytics calculations"]
  node_report_service["Report export<br/>[report.service.ts]"]
end

subgraph group_domain["Learner operations"]
  node_followup_controller["Follow-up operations"]
  node_followup_service["Follow-up rules"]
  node_student_service["Student records<br/>[student.service.ts]"]
  node_database[("PostgreSQL data<br/>[index.ts]")]
end

node_user(("Platform user"))

node_user -.->|"uses"| node_web
node_web -.->|"offers upload"| node_upload_ui
node_upload_ui -.->|"parses workbook"| node_client_parse
node_web -.->|"calls API"| node_api_client
node_api_client -.->|"HTTP requests"| node_batch_routes
node_batch_routes -->|"dispatches"| node_batch_controller
node_batch_routes -->|"dispatches upload"| node_ingestion_controller
node_batch_routes -->|"dispatches analytics"| node_analytics_controller
node_batch_controller -.->|"reads and writes"| node_database
node_ingestion_controller -->|"ingests workbook"| node_ingestion_service
node_ingestion_controller -->|"queries and inserts"| node_database
node_auth_controller -->|"verifies and signs"| node_auth_service
node_auth_controller -.->|"loads accounts"| node_database
node_auth_ui -.->|"submits credentials"| node_api_client
node_dashboard -.->|"requests summaries"| node_api_client
node_compare_ui -.->|"requests comparison"| node_api_client
node_analytics_controller -.->|"calculates insights"| node_analytics_service
node_analytics_controller -.->|"exports report"| node_report_service
node_followup_controller -->|"delegates"| node_followup_service
node_followup_service -.->|"persists follow-ups"| node_database
node_student_service -.->|"accesses records"| node_database
node_ingestion_service -.->|"stores snapshots"| node_database

click node_web "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/App.tsx"
click node_upload_ui "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/upload/UploadModal.tsx"
click node_client_parse "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/core/parsers/workbookParser.ts"
click node_api_client "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/core/api/client.ts"
click node_auth_ui "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/auth/AuthPage.tsx"
click node_dashboard "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/dashboard/OverviewDashboard.tsx"
click node_compare_ui "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/compare/CompareView.tsx"
click node_batch_routes "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/routes/batch.routes.ts"
click node_batch_controller "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/batch.controller.ts"
click node_auth_controller "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/auth.controller.ts"
click node_auth_service "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/auth.service.ts"
click node_ingestion_controller "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/upload.controller.ts"
click node_ingestion_service "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/ingestion/index.ts"
click node_analytics_controller "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/analytics.controller.ts"
click node_analytics_service "https://github.com/arun-devcode/cohort-analysis-platform/tree/master/server/src/services/analytics"
click node_report_service "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/report.service.ts"
click node_followup_controller "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/followup.controller.ts"
click node_followup_service "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/followup.service.ts"
click node_student_service "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/student.service.ts"
click node_database "https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/db/schema/index.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_web,node_upload_ui,node_client_parse,node_api_client,node_auth_ui,node_dashboard,node_compare_ui,node_user toneBlue
class node_batch_routes,node_batch_controller,node_auth_controller,node_auth_service toneAmber
class node_ingestion_controller,node_ingestion_service toneMint
class node_analytics_controller,node_analytics_service,node_report_service toneRose
class node_followup_controller,node_followup_service,node_student_service,node_database toneIndigo
```

## Components

### Web client

- [Application shell](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/App.tsx): `app/src/App.tsx`
- [Workbook upload](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/upload/UploadModal.tsx): `app/src/features/upload/UploadModal.tsx`
- [Workbook parsing](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/core/parsers/workbookParser.ts): `app/src/core/parsers/workbookParser.ts`
- [API client](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/core/api/client.ts): `app/src/core/api/client.ts`
- [Authentication](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/auth/AuthPage.tsx): `app/src/features/auth/AuthPage.tsx`
- [Progress dashboard](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/dashboard/OverviewDashboard.tsx): `app/src/features/dashboard/OverviewDashboard.tsx`
- [Snapshot comparison](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/app/src/features/compare/CompareView.tsx): `app/src/features/compare/CompareView.tsx`

### API and access

- [Batch API routes](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/routes/batch.routes.ts): `server/src/routes/batch.routes.ts`
- [Batch operations](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/batch.controller.ts): `server/src/controllers/batch.controller.ts`
- [Account operations](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/auth.controller.ts): `server/src/controllers/auth.controller.ts`
- [Token and password service](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/auth.service.ts): `server/src/services/auth.service.ts`

### Workbook ingestion

- [Upload handling](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/upload.controller.ts): `server/src/controllers/upload.controller.ts`
- [Workbook ingestion](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/ingestion/index.ts): `server/src/services/ingestion/index.ts`

### Progress insights

- [Analytics endpoints](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/analytics.controller.ts): `server/src/controllers/analytics.controller.ts`
- [Analytics calculations](https://github.com/arun-devcode/cohort-analysis-platform/tree/master/server/src/services/analytics): `server/src/services/analytics`
- [Report export](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/report.service.ts): `server/src/services/report.service.ts`

### Learner operations

- [Follow-up operations](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/controllers/followup.controller.ts): `server/src/controllers/followup.controller.ts`
- [Follow-up rules](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/followup.service.ts): `server/src/services/followup.service.ts`
- [Student records](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/services/student.service.ts): `server/src/services/student.service.ts`
- [PostgreSQL data](https://github.com/arun-devcode/cohort-analysis-platform/blob/master/server/src/db/schema/index.ts): `server/src/db/schema/index.ts`

### Other components

- **Platform user**

## Connections

- Platform user → Application shell: uses
- Application shell → Workbook upload: offers upload
- Workbook upload → Workbook parsing: parses workbook
- Application shell → API client: calls API
- API client → Batch API routes: HTTP requests
- Batch API routes → Batch operations: dispatches (evidence: `server/src/routes/batch.routes.ts`)
- Batch API routes → Upload handling: dispatches upload (evidence: `server/src/routes/batch.routes.ts`)
- Batch API routes → Analytics endpoints: dispatches analytics (evidence: `server/src/routes/batch.routes.ts`)
- Batch operations → PostgreSQL data: reads and writes
- Upload handling → Workbook ingestion: ingests workbook (evidence: `server/src/controllers/upload.controller.ts`)
- Upload handling → PostgreSQL data: queries and inserts (evidence: `server/src/controllers/upload.controller.ts`)
- Account operations → Token and password service: verifies and signs (evidence: `server/src/controllers/auth.controller.ts`)
- Account operations → PostgreSQL data: loads accounts
- Authentication → API client: submits credentials
- Progress dashboard → API client: requests summaries
- Snapshot comparison → API client: requests comparison
- Analytics endpoints → Analytics calculations: calculates insights
- Analytics endpoints → Report export: exports report
- Follow-up operations → Follow-up rules: delegates (evidence: `server/src/controllers/followup.controller.ts`)
- Follow-up rules → PostgreSQL data: persists follow-ups
- Student records → PostgreSQL data: accesses records
- Workbook ingestion → PostgreSQL data: stores snapshots