# starringdaggers/boltab architecture

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

- Interactive diagram: https://gitdiagram.com/starringdaggers/boltab
- Repository: https://github.com/starringdaggers/boltab

## Overview

#### Purpose and entry points
Boltab Brilliant Schools is a role-based school portal for administrators, teachers, and students. It is a Next.js App Router application that combines dashboards and HTTP APIs in one deployment. Public access begins at `src/app/page.tsx` and `src/app/login/page.tsx`; authenticated users are routed into role areas under `src/app/admin`, `src/app/teacher`, or `src/app/student`.

#### Authentication and authorization boundary
JWT authentication is issued and cleared through `src/app/api/auth/login/route.ts` and `src/app/api/auth/logout/route.ts`, using httpOnly cookies. Session, JWT, password hashing, and role checks are centralized in `src/lib/session.ts`, `src/lib/jwt.ts`, `src/lib/password.ts`, and `src/middleware.ts`. Middleware protects role-prefixed dashboard routes; API handlers must enforce their corresponding role/access rules, including admin delegation and controlled result visibility.

#### Role-specific application surfaces
Each role has its own layout and server/UI route tree: `src/app/admin/layout.tsx`, `src/app/teacher/layout.tsx`, and `src/app/student/layout.tsx`. Shared dashboard navigation and presentation live in `src/components/shared/DashboardShell.tsx`. Admin is the operational control plane; teacher routes support assigned teaching work; student routes expose personal academic, attendance, fee, and timetable data.

#### Admin school-management control plane
Admin pages and APIs manage the school’s core reference and account data: students, teachers, classes, subjects, terms, accounts/delegations, and school fee setup. Representative boundaries are `src/app/admin/students/page.tsx`, `src/app/api/admin/students/route.ts`, `src/app/api/admin/teachers/route.ts`, `src/app/api/admin/classes/route.ts`, and `src/app/api/admin/terms/route.ts`. Admin-specific authorization support is in `src/lib/adminAccess.ts`. CSV student ingestion is a dedicated mutation endpoint at `src/app/api/admin/students/import/route.ts`.

#### Academic workflows: assignments, results, and report cards
Teachers obtain their authorized classes, subjects, terms, and assignments through endpoints such as `src/app/api/teacher/assignments/route.ts` and `src/app/api/teacher/results/route.ts`, then submit academic results and report-card data. Admin manages report-card records and release/settings via `src/app/api/admin/report-cards/route.ts` and `src/app/api/admin/report-cards/settings/route.ts`. Student results are exposed through `src/app/api/student/results/route.ts`; visibility policy is isolated in `src/lib/resultsAccess.ts`. Grade computation/presentation logic is supported by `src/lib/grading.ts`, `src/lib/reportCardFields.ts`, and `src/components/report-card/ReportCardView.tsx`.

#### Operations: attendance, fees, timetables, and presence
Attendance has separate teacher recording, student viewing, and admin oversight paths: `src/app/api/teacher/attendance/route.ts`, `src/app/api/student/attendance/route.ts`, and `src/app/api/admin/attendance/route.ts`. Fees use admin-managed class fees and payments with student-facing balances/history: `src/app/api/admin/class-fees/route.ts`, `src/app/api/admin/fee-payments/route.ts`, and `src/app/api/student/fees/route.ts`. Timetables are constructed by admins using `src/components/timetable/TimetableBuilder.tsx`, persisted via `src/app/api/admin/timetables/route.ts`, and consumed through `src/app/api/timetables/route.ts`. Presence heartbeat/status endpoints support active-user tracking at `src/app/api/presence/heartbeat/route.ts` and `src/app/api/presence/status/route.ts`.

#### Data, runtime, and infrastructure
The runtime is Next.js 14 with React/TypeScript and route handlers; styling is Tailwind-based. Prisma is the persistence boundary: schema and seed data are in `prisma/schema.prisma` and `prisma/seed.ts`, accessed through `src/lib/db.ts`. The intended database is PostgreSQL, with Neon named in setup guidance. Manual SQL migrations under `prisma/` indicate schema evolution for attendance, report cards, fees, timetables, profile pictures, and school settings. Deployment targets are Next.js-capable hosting such as Vercel or Netlify, configured with `DATABASE_URL`, `JWT_SECRET`, and token-expiry environment variables.

Main entry points: [`src/lib/db.ts`](https://github.com/starringdaggers/boltab/blob/main/src/lib/db.ts) (Prisma data layer), [`src/app/admin/layout.tsx`](https://github.com/starringdaggers/boltab/blob/main/src/app/admin/layout.tsx) (Admin portal), [`src/app/student/layout.tsx`](https://github.com/starringdaggers/boltab/blob/main/src/app/student/layout.tsx) (Student portal), [`src/app/api/teacher/results/route.ts`](https://github.com/starringdaggers/boltab/blob/main/src/app/api/teacher/results/route.ts) (Assignments & results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Role portals"]
  node_shell["Dashboard shell<br/>shared component<br/>[DashboardShell.tsx]"]
  node_admin["Admin portal<br/>App Router area<br/>[layout.tsx]"]
  node_teacher["Teacher portal<br/>App Router area<br/>[layout.tsx]"]
  node_student["Student portal<br/>App Router area<br/>[layout.tsx]"]
end

subgraph group_api["HTTP API domains"]
  node_auth["Auth endpoints<br/>route handlers<br/>[route.ts]"]
  node_admincore["Admin school management<br/>admin APIs<br/>[route.ts]"]
  node_import["Student CSV import<br/>mutation endpoint<br/>[route.ts]"]
  node_academic["Assignments &amp; results<br/>academic APIs<br/>[route.ts]"]
  node_attendance["Attendance workflows<br/>role-scoped APIs<br/>[route.ts]"]
  node_fees["Fees &amp; payments<br/>role-scoped APIs<br/>[route.ts]"]
  node_timetables["Timetable management<br/>schedule APIs<br/>[route.ts]"]
  node_presence["Presence tracking<br/>status APIs<br/>[route.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma[("Prisma data layer<br/>ORM<br/>[db.ts]")]
  node_schema["School data schema<br/>Prisma schema &amp; seed<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL / Neon<br/>database")]
end

node_public["Public entry &amp; login<br/>Next.js pages<br/>[page.tsx]"]
node_access{{"Session &amp; access control<br/>security layer<br/>[middleware.ts]"}}
node_grading["Report-card rendering<br/>grading UI<br/>[ReportCardView.tsx]"]
node_runtime["Next.js deployment<br/>runtime"]

node_public -->|"sign in"| node_auth
node_auth -->|"JWT cookies"| node_access
node_access -->|"admin route guard"| node_admin
node_access -->|"teacher route guard"| node_teacher
node_access -->|"student route guard"| node_student
node_shell -->|"shared navigation"| node_admin
node_shell -->|"shared navigation"| node_teacher
node_shell -->|"shared navigation"| node_student
node_admin -->|"manages school data"| node_admincore
node_admincore -->|"bulk ingestion"| node_import
node_admin -->|"report-card control"| node_academic
node_teacher -->|"assignments and results"| node_academic
node_student -->|"view released results"| node_academic
node_academic -->|"grades and report cards"| node_grading
node_teacher -->|"record attendance"| node_attendance
node_admin -->|"oversight"| node_attendance
node_student -->|"view history"| node_attendance
node_admin -->|"manage payments"| node_fees
node_student -->|"balances and history"| node_fees
node_admin -->|"build schedules"| node_timetables
node_student -->|"consume schedules"| node_timetables
node_admincore -->|"persist"| node_prisma
node_academic -->|"persist"| node_prisma
node_attendance -->|"persist"| node_prisma
node_fees -->|"persist"| node_prisma
node_timetables -->|"persist"| node_prisma
node_presence -->|"track status"| node_prisma
node_prisma -->|"models"| node_schema
node_prisma -->|"DATABASE_URL"| node_postgres
node_runtime -->|"serves pages"| node_public
node_runtime -->|"serves APIs"| node_auth

click node_public "https://github.com/starringdaggers/boltab/blob/main/src/app/login/page.tsx"
click node_auth "https://github.com/starringdaggers/boltab/blob/main/src/app/api/auth/login/route.ts"
click node_access "https://github.com/starringdaggers/boltab/blob/main/src/middleware.ts"
click node_shell "https://github.com/starringdaggers/boltab/blob/main/src/components/shared/DashboardShell.tsx"
click node_admin "https://github.com/starringdaggers/boltab/blob/main/src/app/admin/layout.tsx"
click node_teacher "https://github.com/starringdaggers/boltab/blob/main/src/app/teacher/layout.tsx"
click node_student "https://github.com/starringdaggers/boltab/blob/main/src/app/student/layout.tsx"
click node_admincore "https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/students/route.ts"
click node_import "https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/students/import/route.ts"
click node_academic "https://github.com/starringdaggers/boltab/blob/main/src/app/api/teacher/results/route.ts"
click node_grading "https://github.com/starringdaggers/boltab/blob/main/src/components/report-card/ReportCardView.tsx"
click node_attendance "https://github.com/starringdaggers/boltab/blob/main/src/app/api/teacher/attendance/route.ts"
click node_fees "https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/fee-payments/route.ts"
click node_timetables "https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/timetables/route.ts"
click node_presence "https://github.com/starringdaggers/boltab/blob/main/src/app/api/presence/heartbeat/route.ts"
click node_prisma "https://github.com/starringdaggers/boltab/blob/main/src/lib/db.ts"
click node_schema "https://github.com/starringdaggers/boltab/blob/main/prisma/schema.prisma"

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_shell,node_admin,node_teacher,node_student toneBlue
class node_auth,node_admincore,node_import,node_academic,node_attendance,node_fees,node_timetables,node_presence toneAmber
class node_prisma,node_schema,node_postgres toneMint
class node_public,node_access,node_grading,node_runtime toneNeutral
```

## Components

### Role portals

- [Dashboard shell](https://github.com/starringdaggers/boltab/blob/main/src/components/shared/DashboardShell.tsx): shared component · `src/components/shared/DashboardShell.tsx`
- [Admin portal](https://github.com/starringdaggers/boltab/blob/main/src/app/admin/layout.tsx): App Router area · Operational school-management control plane. · `src/app/admin/layout.tsx`
- [Teacher portal](https://github.com/starringdaggers/boltab/blob/main/src/app/teacher/layout.tsx): App Router area · Assigned teaching and recording workflows. · `src/app/teacher/layout.tsx`
- [Student portal](https://github.com/starringdaggers/boltab/blob/main/src/app/student/layout.tsx): App Router area · Personal academic and operational data. · `src/app/student/layout.tsx`

### HTTP API domains

- [Auth endpoints](https://github.com/starringdaggers/boltab/blob/main/src/app/api/auth/login/route.ts): route handlers · Issues and clears JWT cookies. · `src/app/api/auth/login/route.ts`
- [Admin school management](https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/students/route.ts): admin APIs · Manages accounts, students, teachers, classes, subjects, terms, and fee setup. · `src/app/api/admin/students/route.ts`
- [Student CSV import](https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/students/import/route.ts): mutation endpoint · `src/app/api/admin/students/import/route.ts`
- [Assignments & results](https://github.com/starringdaggers/boltab/blob/main/src/app/api/teacher/results/route.ts): academic APIs · Teacher submission, admin report-card release, and student result delivery. · `src/app/api/teacher/results/route.ts`
- [Attendance workflows](https://github.com/starringdaggers/boltab/blob/main/src/app/api/teacher/attendance/route.ts): role-scoped APIs · Teacher recording, student viewing, and admin oversight. · `src/app/api/teacher/attendance/route.ts`
- [Fees & payments](https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/fee-payments/route.ts): role-scoped APIs · Admin payment management and student balances. · `src/app/api/admin/fee-payments/route.ts`
- [Timetable management](https://github.com/starringdaggers/boltab/blob/main/src/app/api/admin/timetables/route.ts): schedule APIs · Admin-built schedules consumed by users. · `src/app/api/admin/timetables/route.ts`
- [Presence tracking](https://github.com/starringdaggers/boltab/blob/main/src/app/api/presence/heartbeat/route.ts): status APIs · Heartbeat and active-user status. · `src/app/api/presence/heartbeat/route.ts`

### Persistence

- [Prisma data layer](https://github.com/starringdaggers/boltab/blob/main/src/lib/db.ts): ORM · Application persistence boundary. · `src/lib/db.ts`
- [School data schema](https://github.com/starringdaggers/boltab/blob/main/prisma/schema.prisma): Prisma schema & seed · Models school data and initial records. · `prisma/schema.prisma`
- **PostgreSQL / Neon**: database · Production database configured by DATABASE_URL.

### Other components

- [Public entry & login](https://github.com/starringdaggers/boltab/blob/main/src/app/login/page.tsx): Next.js pages · Public landing and sign-in entry points. · `src/app/login/page.tsx`
- [Session & access control](https://github.com/starringdaggers/boltab/blob/main/src/middleware.ts): security layer · JWT, passwords, role checks, and route protection. · `src/middleware.ts`
- [Report-card rendering](https://github.com/starringdaggers/boltab/blob/main/src/components/report-card/ReportCardView.tsx): grading UI · Computes and presents report-card fields. · `src/components/report-card/ReportCardView.tsx`
- **Next.js deployment**: runtime · Single deployment serving App Router pages and route handlers.

## Connections

- Public entry & login → Auth endpoints: sign in
- Auth endpoints → Session & access control: JWT cookies
- Session & access control → Admin portal: admin route guard
- Session & access control → Teacher portal: teacher route guard
- Session & access control → Student portal: student route guard
- Dashboard shell → Admin portal: shared navigation
- Dashboard shell → Teacher portal: shared navigation
- Dashboard shell → Student portal: shared navigation
- Admin portal → Admin school management: manages school data
- Admin school management → Student CSV import: bulk ingestion
- Admin portal → Assignments & results: report-card control
- Teacher portal → Assignments & results: assignments and results
- Student portal → Assignments & results: view released results
- Assignments & results → Report-card rendering: grades and report cards
- Teacher portal → Attendance workflows: record attendance
- Admin portal → Attendance workflows: oversight
- Student portal → Attendance workflows: view history
- Admin portal → Fees & payments: manage payments
- Student portal → Fees & payments: balances and history
- Admin portal → Timetable management: build schedules
- Student portal → Timetable management: consume schedules
- Admin school management → Prisma data layer: persist
- Assignments & results → Prisma data layer: persist
- Attendance workflows → Prisma data layer: persist
- Fees & payments → Prisma data layer: persist
- Timetable management → Prisma data layer: persist
- Presence tracking → Prisma data layer: track status
- Prisma data layer → School data schema: models
- Prisma data layer → PostgreSQL / Neon: DATABASE_URL
- Next.js deployment → Public entry & login: serves pages
- Next.js deployment → Auth endpoints: serves APIs