# debguin452/uttarpatra architecture

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

- Interactive diagram: https://gitdiagram.com/debguin452/uttarpatra
- Repository: https://github.com/debguin452/uttarpatra

## Overview

Uttarpatro is a Bengali/English coaching learning platform for students in classes 5–12 and competitive-exam aspirants, with teacher and staff consoles. A user signs in, the app loads their server profile and role, then presents learning, enrollment, assessment, teacher, or admin screens; requests go through the Worker API, which owns D1 access. Tests are started and submitted through the server for timed, server-scored results. The README documents capabilities whose individual screen or route implementations were not sampled; their links below cite that documentation rather than implying source inspection.

Main entry points: [`apps/web/src/app.tsx`](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/app.tsx) (App routing), [`apps/web/src/lib/api.ts`](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/lib/api.ts) (API client), [`workers/api/src/index.ts`](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/index.ts) (API routing), [`apps/web/src/screens/Enroll.tsx`](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Enroll.tsx) (Enrollment payment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routing<br/>[app.tsx]"]
  node_session["Identity session<br/>[session.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_learning["Learning workflows"]
  node_catalog["Batch catalogue<br/>[Batches.tsx]"]
  node_batch_detail["Batch details<br/>[BatchDetail.tsx]"]
  node_enrollment["Enrollment payment<br/>[Enroll.tsx]"]
  node_test_ui["Test taking<br/>[TestRunner.tsx]"]
  node_test_results["Test results<br/>[TestResult.tsx]"]
end

subgraph group_staff["Teacher and admin"]
  node_teacher_console["Teacher console<br/>[TeacherShell.tsx]"]
  node_teacher_tests["Teacher tests<br/>[TeacherTests.tsx]"]
  node_admin_console["Admin console<br/>[Admin.tsx]"]
  node_admin_tests["Admin tests<br/>[AdminTests.tsx]"]
end

subgraph group_api["Worker API"]
  node_worker["API routing<br/>[index.ts]"]
  node_auth["Token and role checks<br/>[firebaseAuth.ts]"]
  node_batches_api["Batch routes<br/>[batches.ts]"]
  node_attempts_api["Attempt scoring<br/>[attempts.ts]"]
  node_teacher_api["Teacher routes<br/>[teacher.ts]"]
  node_admin_api["Admin routes<br/>[index.ts]"]
  node_session_guard["Rate-limit guard<br/>[SessionGuard.ts]"]
  node_d1[("D1 database")]
end

subgraph group_shared["Shared services"]
  node_firebase["Firebase Authentication"]
  node_shared_schema["Shared schemas<br/>[schema.ts]"]
  node_pricing["Pricing rules<br/>[pricing.ts]"]
  node_scoring["Scoring rules<br/>[scoring.ts]"]
end

node_learner(("Student"))
node_staff_actor(("Staff or teacher"))

node_learner -->|"uses"| node_app
node_staff_actor -->|"uses"| node_app
node_app -->|"checks profile"| node_session
node_app -->|"routes to"| node_catalog
node_app -->|"routes to"| node_batch_detail
node_app -->|"routes to"| node_enrollment
node_app -->|"routes to"| node_test_ui
node_app -->|"routes to"| node_test_results
node_app -->|"role selects"| node_teacher_console
node_app -->|"role selects"| node_admin_console
node_session -->|"loads profile"| node_api_client
node_api_client -->|"gets token"| node_firebase
node_catalog -.->|"requests data"| node_api_client
node_enrollment -.->|"submits payment"| node_api_client
node_test_ui -->|"submits attempt"| node_api_client
node_teacher_console -->|"offers tests"| node_teacher_tests
node_teacher_tests -->|"saves tests"| node_api_client
node_admin_console -.->|"offers test admin"| node_admin_tests
node_admin_tests -->|"manages tests"| node_api_client
node_api_client -->|"calls API"| node_worker
node_worker -->|"checks requests"| node_auth
node_worker -->|"mounts routes"| node_batches_api
node_worker -->|"mounts routes"| node_attempts_api
node_worker -->|"mounts routes"| node_teacher_api
node_worker -->|"mounts routes"| node_admin_api
node_auth -->|"verifies token"| node_firebase
node_auth -->|"reads account"| node_d1
node_worker -->|"rate limits"| node_session_guard
node_batches_api -.->|"serves batches"| node_d1
node_attempts_api -.->|"stores attempts"| node_d1
node_attempts_api -.->|"scores server-side"| node_scoring
node_teacher_api -.->|"serves teacher data"| node_d1
node_admin_api -.->|"manages records"| node_d1
node_teacher_tests -->|"validates input"| node_shared_schema
node_enrollment -.->|"quotes coupons"| node_pricing

click node_app "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/app.tsx"
click node_session "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/lib/session.ts"
click node_api_client "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/lib/api.ts"
click node_catalog "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Batches.tsx"
click node_batch_detail "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/BatchDetail.tsx"
click node_enrollment "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Enroll.tsx"
click node_test_ui "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/TestRunner.tsx"
click node_test_results "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/TestResult.tsx"
click node_teacher_console "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/teacher/TeacherShell.tsx"
click node_teacher_tests "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/teacher/TeacherTests.tsx"
click node_admin_console "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Admin.tsx"
click node_admin_tests "https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/admin/AdminTests.tsx"
click node_worker "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/index.ts"
click node_auth "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/middleware/firebaseAuth.ts"
click node_batches_api "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/batches.ts"
click node_attempts_api "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/attempts.ts"
click node_teacher_api "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/teacher.ts"
click node_admin_api "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/admin/index.ts"
click node_session_guard "https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/do/SessionGuard.ts"
click node_shared_schema "https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/schema.ts"
click node_pricing "https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/pricing.ts"
click node_scoring "https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/scoring.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_app,node_session,node_api_client toneBlue
class node_catalog,node_batch_detail,node_enrollment,node_test_ui,node_test_results toneAmber
class node_teacher_console,node_teacher_tests,node_admin_console,node_admin_tests toneMint
class node_worker,node_auth,node_batches_api,node_attempts_api,node_teacher_api,node_admin_api,node_session_guard,node_d1 toneRose
class node_firebase,node_shared_schema,node_pricing,node_scoring,node_learner,node_staff_actor toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/app.tsx): `apps/web/src/app.tsx`
- [Identity session](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/lib/session.ts): `apps/web/src/lib/session.ts`
- [API client](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Learning workflows

- [Batch catalogue](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Batches.tsx): `apps/web/src/screens/Batches.tsx`
- [Batch details](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/BatchDetail.tsx): `apps/web/src/screens/BatchDetail.tsx`
- [Enrollment payment](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Enroll.tsx): `apps/web/src/screens/Enroll.tsx`
- [Test taking](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/TestRunner.tsx): `apps/web/src/screens/TestRunner.tsx`
- [Test results](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/TestResult.tsx): `apps/web/src/screens/TestResult.tsx`

### Teacher and admin

- [Teacher console](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/teacher/TeacherShell.tsx): `apps/web/src/screens/teacher/TeacherShell.tsx`
- [Teacher tests](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/teacher/TeacherTests.tsx): `apps/web/src/screens/teacher/TeacherTests.tsx`
- [Admin console](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/Admin.tsx): `apps/web/src/screens/Admin.tsx`
- [Admin tests](https://github.com/debguin452/uttarpatra/blob/main/apps/web/src/screens/admin/AdminTests.tsx): `apps/web/src/screens/admin/AdminTests.tsx`

### Worker API

- [API routing](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/index.ts): `workers/api/src/index.ts`
- [Token and role checks](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/middleware/firebaseAuth.ts): `workers/api/src/middleware/firebaseAuth.ts`
- [Batch routes](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/batches.ts): `workers/api/src/routes/batches.ts`
- [Attempt scoring](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/attempts.ts): `workers/api/src/routes/attempts.ts`
- [Teacher routes](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/teacher.ts): `workers/api/src/routes/teacher.ts`
- [Admin routes](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/routes/admin/index.ts): `workers/api/src/routes/admin/index.ts`
- [Rate-limit guard](https://github.com/debguin452/uttarpatra/blob/main/workers/api/src/do/SessionGuard.ts): `workers/api/src/do/SessionGuard.ts`
- **D1 database**

### Shared services

- **Firebase Authentication**
- [Shared schemas](https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/schema.ts): `packages/shared/src/schema.ts`
- [Pricing rules](https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/pricing.ts): `packages/shared/src/pricing.ts`
- [Scoring rules](https://github.com/debguin452/uttarpatra/blob/main/packages/shared/src/scoring.ts): `packages/shared/src/scoring.ts`

### Other components

- **Student**
- **Staff or teacher**

## Connections

- Student → App routing: uses
- Staff or teacher → App routing: uses
- App routing → Identity session: checks profile (evidence: `apps/web/src/app.tsx`)
- App routing → Batch catalogue: routes to (evidence: `apps/web/src/app.tsx`)
- App routing → Batch details: routes to (evidence: `apps/web/src/app.tsx`)
- App routing → Enrollment payment: routes to (evidence: `apps/web/src/app.tsx`)
- App routing → Test taking: routes to (evidence: `apps/web/src/app.tsx`)
- App routing → Test results: routes to (evidence: `apps/web/src/app.tsx`)
- App routing → Teacher console: role selects (evidence: `apps/web/src/app.tsx`)
- App routing → Admin console: role selects (evidence: `apps/web/src/app.tsx`)
- Identity session → API client: loads profile (evidence: `apps/web/src/lib/session.ts`)
- API client → Firebase Authentication: gets token (evidence: `apps/web/src/lib/api.ts`)
- Batch catalogue → API client: requests data
- Enrollment payment → API client: submits payment
- Test taking → API client: submits attempt (evidence: `apps/web/src/screens/TestRunner.tsx`)
- Teacher console → Teacher tests: offers tests (evidence: `apps/web/src/screens/teacher/TeacherShell.tsx`)
- Teacher tests → API client: saves tests (evidence: `apps/web/src/screens/teacher/TeacherTests.tsx`)
- Admin console → Admin tests: offers test admin
- Admin tests → API client: manages tests (evidence: `apps/web/src/screens/admin/AdminTests.tsx`)
- API client → API routing: calls API
- API routing → Token and role checks: checks requests (evidence: `workers/api/src/index.ts`)
- API routing → Batch routes: mounts routes (evidence: `workers/api/src/index.ts`)
- API routing → Attempt scoring: mounts routes (evidence: `workers/api/src/index.ts`)
- API routing → Teacher routes: mounts routes (evidence: `workers/api/src/index.ts`)
- API routing → Admin routes: mounts routes (evidence: `workers/api/src/index.ts`)
- Token and role checks → Firebase Authentication: verifies token (evidence: `workers/api/src/middleware/firebaseAuth.ts`)
- Token and role checks → D1 database: reads account (evidence: `workers/api/src/middleware/firebaseAuth.ts`)
- API routing → Rate-limit guard: rate limits (evidence: `workers/api/src/index.ts`)
- Batch routes → D1 database: serves batches
- Attempt scoring → D1 database: stores attempts
- Attempt scoring → Scoring rules: scores server-side
- Teacher routes → D1 database: serves teacher data
- Admin routes → D1 database: manages records
- Teacher tests → Shared schemas: validates input (evidence: `apps/web/src/screens/teacher/TeacherTests.tsx`)
- Enrollment payment → Pricing rules: quotes coupons
