# zaggi-225/kendra-project architecture

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

- Interactive diagram: https://gitdiagram.com/zaggi-225/kendra-project
- Repository: https://github.com/zaggi-225/kendra-project

## Overview

#### Purpose and entry points
This repository is a student academic-management system with a static browser UI, a Python API backend, and Supabase/PostgreSQL persistence. The frontend begins at `index.html`; feature pages are under `pages/`. The API application entry point is `backend/app/main.py`. Database lifecycle is defined through ordered Supabase migrations in `supabase/migrations/`.

#### Frontend feature modules
The browser client is plain HTML/CSS/JavaScript rather than a bundled framework application. `js/app.js` is the shared client bootstrap, while feature-specific scripts drive student, attendance, DLT, and exam workflows:
- `pages/student-master.html`, `js/studentMaster.js`
- `pages/attendance.html`, `js/attendance.js`
- `pages/dlt.html`, `js/dlt.js`
- `pages/exam.html`, `js/exam.js`

Shared presentation structure is centralized in `css/base.css`, `css/layout.css`, and `css/components.css`. `js/mockData.js` indicates the UI can operate against local/mock data during development or before API integration.

#### API composition and request boundary
The backend is structured as a FastAPI-style layered service. `backend/app/main.py` assembles the application and routes; domain HTTP endpoints are separated into routers:
- `backend/app/routers/students.py`
- `backend/app/routers/attendance.py`
- `backend/app/routers/assessments.py`
- `backend/app/routers/dlt.py`
- `backend/app/routers/enrollments.py`

Routers form the external API boundary and should handle HTTP concerns, validation invocation, and dependency wiring rather than persistence logic.

#### Domain service layer
Business operations are organized per educational domain behind service modules:
- `backend/app/services/student_service.py`
- `backend/app/services/enrollment_service.py`
- `backend/app/services/attendance_service.py`
- `backend/app/services/assessment_service.py`
- `backend/app/services/dlt_service.py`

The primary control flow is frontend feature action → API router → domain service → database dependency/connection → Supabase PostgreSQL. Services are the key place to coordinate cross-entity rules, such as enrollment context for attendance and assessment records.

#### Data contracts and persistence access
Backend models and schemas distinguish stored/domain data from API request/response contracts. Relevant parallel structures include:
- `backend/app/models/student.py`, `backend/app/schemas/students.py`
- `backend/app/models/attendance.py`, `backend/app/schemas/attendance.py`
- `backend/app/models/assessment.py`, `backend/app/schemas/assessment.py`
- `backend/app/models/dlt.py`, `backend/app/schemas/dlt.py`

Database connectivity and injected request-scoped access are isolated in `backend/app/db/connection.py` and `backend/app/db/dependencies.py`. Configuration and security boundaries are in `backend/app/core/config.py` and `backend/app/core/security.py`.

#### Supabase relational model and governance
Supabase provides PostgreSQL infrastructure, schema evolution, seeds, and row-level security. The data model progresses from identity/reference entities to school operations:
- Profiles and academic/class structure: `001_create_profiles.sql`, `002_create_academic_years.sql`, `003_create_classes.sql`
- Student and enrollment relationships: `004_create_students.sql`, `008_create_student_enrollments.sql`
- Operational records: `010_create_attendance.sql`, `011_create_dlt.sql`, `012_create_assessments.sql`

Indexes and RLS are explicit architectural stages in `supabase/migrations/013_create_indexes.sql` and `supabase/migrations/014_create_rls.sql`. Therefore, API authorization must remain compatible with Supabase’s database-level access policies rather than treating the database as an unrestricted internal store.

Main entry points: [`backend/app/db/dependencies.py`](https://github.com/zaggi-225/kendra-project/blob/main/backend/app/db/dependencies.py) (Database dependency), [`backend/app/core/security.py`](https://github.com/zaggi-225/kendra-project/blob/main/backend/app/core/security.py) (Security boundary), [`js/app.js`](https://github.com/zaggi-225/kendra-project/blob/main/js/app.js) (Client bootstrap), [`js/studentMaster.js`](https://github.com/zaggi-225/kendra-project/blob/main/js/studentMaster.js) (Student workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_ui["Feature pages<br/>static HTML"]
  node_client["Client bootstrap<br/>JavaScript<br/>[app.js]"]
  node_student_ui["Student workflow<br/>feature script<br/>[studentMaster.js]"]
  node_attendance_ui["Attendance workflow<br/>feature script<br/>[attendance.js]"]
  node_dlt_ui["DLT workflow<br/>feature script<br/>[dlt.js]"]
  node_exam_ui["Exam workflow<br/>feature script<br/>[exam.js]"]
  node_mock_data["Mock data<br/>development data<br/>[mockData.js]"]
end

subgraph group_api["FastAPI backend"]
  node_api_app{{"API application<br/>FastAPI entry<br/>[main.py]"}}
  node_routers["Domain routers<br/>HTTP boundary"]
  node_services["Domain services<br/>business layer"]
  node_contracts["API schemas<br/>request/response contracts"]
  node_models["Domain models<br/>stored data models"]
  node_db_access["Database dependency<br/>request-scoped access<br/>[dependencies.py]"]
  node_security["Security boundary<br/>configuration and security<br/>[security.py]"]
end

subgraph group_data["Supabase data platform"]
  node_migrations["Schema migrations<br/>ordered SQL lifecycle"]
  node_indexes_rls["Indexes and RLS<br/>database governance<br/>[014_create_rls.sql]"]
  node_postgres[("Supabase PostgreSQL<br/>relational database")]
end

node_ui -->|"loads shared behavior"| node_client
node_student_ui -->|"student requests"| node_routers
node_attendance_ui -->|"attendance requests"| node_routers
node_dlt_ui -->|"DLT requests"| node_routers
node_exam_ui -->|"assessment requests"| node_routers
node_mock_data -.->|"development fallback"| node_ui
node_client -->|"supports"| node_student_ui
node_api_app -->|"registers"| node_routers
node_routers -->|"validates requests"| node_contracts
node_routers -->|"dispatches"| node_services
node_services -->|"uses domain data"| node_models
node_services -->|"uses injected access"| node_db_access
node_db_access -->|"connects"| node_postgres
node_security -.->|"governs access"| node_db_access
node_migrations -->|"evolves schema"| node_postgres
node_indexes_rls -->|"enforces policies"| node_postgres
node_security -.->|"must remain compatible"| node_indexes_rls

click node_client "https://github.com/zaggi-225/kendra-project/blob/main/js/app.js"
click node_student_ui "https://github.com/zaggi-225/kendra-project/blob/main/js/studentMaster.js"
click node_attendance_ui "https://github.com/zaggi-225/kendra-project/blob/main/js/attendance.js"
click node_dlt_ui "https://github.com/zaggi-225/kendra-project/blob/main/js/dlt.js"
click node_exam_ui "https://github.com/zaggi-225/kendra-project/blob/main/js/exam.js"
click node_mock_data "https://github.com/zaggi-225/kendra-project/blob/main/js/mockData.js"
click node_api_app "https://github.com/zaggi-225/kendra-project/blob/main/backend/app/main.py"
click node_db_access "https://github.com/zaggi-225/kendra-project/blob/main/backend/app/db/dependencies.py"
click node_security "https://github.com/zaggi-225/kendra-project/blob/main/backend/app/core/security.py"
click node_indexes_rls "https://github.com/zaggi-225/kendra-project/blob/main/supabase/migrations/014_create_rls.sql"

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_ui,node_client,node_student_ui,node_attendance_ui,node_dlt_ui,node_exam_ui,node_mock_data toneBlue
class node_api_app,node_routers,node_services,node_contracts,node_models,node_db_access,node_security toneAmber
class node_migrations,node_indexes_rls,node_postgres toneMint
```

## Components

### Browser client

- **Feature pages**: static HTML · Student, attendance, DLT, and exam workflows.
- [Client bootstrap](https://github.com/zaggi-225/kendra-project/blob/main/js/app.js): JavaScript · `js/app.js`
- [Student workflow](https://github.com/zaggi-225/kendra-project/blob/main/js/studentMaster.js): feature script · `js/studentMaster.js`
- [Attendance workflow](https://github.com/zaggi-225/kendra-project/blob/main/js/attendance.js): feature script · `js/attendance.js`
- [DLT workflow](https://github.com/zaggi-225/kendra-project/blob/main/js/dlt.js): feature script · `js/dlt.js`
- [Exam workflow](https://github.com/zaggi-225/kendra-project/blob/main/js/exam.js): feature script · `js/exam.js`
- [Mock data](https://github.com/zaggi-225/kendra-project/blob/main/js/mockData.js): development data · Allows UI operation before API integration. · `js/mockData.js`

### FastAPI backend

- [API application](https://github.com/zaggi-225/kendra-project/blob/main/backend/app/main.py): FastAPI entry · Assembles the application and route registration. · `backend/app/main.py`
- **Domain routers**: HTTP boundary · Students, attendance, assessments, DLT, and enrollment endpoints.
- **Domain services**: business layer · Coordinates cross-entity academic rules.
- **API schemas**: request/response contracts · Student, attendance, assessment, and DLT validation contracts.
- **Domain models**: stored data models · Student, attendance, assessment, and DLT representations.
- [Database dependency](https://github.com/zaggi-225/kendra-project/blob/main/backend/app/db/dependencies.py): request-scoped access · Connection and injected database access. · `backend/app/db/dependencies.py`
- [Security boundary](https://github.com/zaggi-225/kendra-project/blob/main/backend/app/core/security.py): configuration and security · Must align API authorization with database RLS. · `backend/app/core/security.py`

### Supabase data platform

- **Schema migrations**: ordered SQL lifecycle · Identity, academic structure, enrollment, and operational records.
- [Indexes and RLS](https://github.com/zaggi-225/kendra-project/blob/main/supabase/migrations/014_create_rls.sql): database governance · Indexes and row-level access policies. · `supabase/migrations/014_create_rls.sql`
- **Supabase PostgreSQL**: relational database · Persistent academic-management data.

## Connections

- Feature pages → Client bootstrap: loads shared behavior
- Student workflow → Domain routers: student requests
- Attendance workflow → Domain routers: attendance requests
- DLT workflow → Domain routers: DLT requests
- Exam workflow → Domain routers: assessment requests
- Mock data → Feature pages: development fallback
- Client bootstrap → Student workflow: supports
- API application → Domain routers: registers
- Domain routers → API schemas: validates requests
- Domain routers → Domain services: dispatches
- Domain services → Domain models: uses domain data
- Domain services → Database dependency: uses injected access
- Database dependency → Supabase PostgreSQL: connects
- Security boundary → Database dependency: governs access
- Schema migrations → Supabase PostgreSQL: evolves schema
- Indexes and RLS → Supabase PostgreSQL: enforces policies
- Security boundary → Indexes and RLS: must remain compatible