# kamesh12k/facredit architecture

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

- Interactive diagram: https://gitdiagram.com/kamesh12k/facredit
- Repository: https://github.com/kamesh12k/facredit

## Overview

1. This repository is a two-tier application: a FastAPI backend in `backend/` and a React/Vite frontend in `frontend/`, backed by PostgreSQL schema and migration scripts in `database/`. The backend exposes the business APIs; the frontend is a route-driven UI that consumes them through a small Axios client layer.

2. The backend follows a clear layered structure:
   - `app/main.py` wires the FastAPI app and mounts routers.
   - `app/routes/` contains HTTP endpoints grouped by domain.
   - `app/services/` holds the business rules and cross-entity workflows.
   - `app/models/` contains SQLAlchemy entities.
   - `app/schemas/` contains Pydantic request/response contracts.
   - `app/core/` contains shared concerns like security and dependency injection.
   - `app/database.py` centralizes DB/session setup and `app/config.py` reads environment configuration.

3. The main architectural boundary is between HTTP/API concerns and business logic. Routes are thin entry points; services perform the actual work and operate over ORM models and schema validation. This separation is used consistently across auth, admin, teachers, timetable, leaves, credits, notifications, and calendar management.

4. The domain is centered on academic scheduling and workload management. The most important subsystem is the Academic Calendar / Day Order engine, with models such as `academic_calendar`, `day_order_calendar`, and related services/routes. It acts as the source of truth for whether a date is usable and what Day Order it belongs to, and downstream features depend on that decision.

5. Several workflows are explicitly calendar-gated. Timetable creation, leave requests, substitute assignment, and credit transactions all rely on the calendar/day-order service to reject non-working dates. That means the calendar subsystem is not just a reporting feature; it is a control point that other subsystems call before mutating data.

6. Authorization is another major boundary. The app uses JWT-based auth with bcrypt password hashing, and dependency-level guards enforce role-based access control for Super Admin, Secondary Admin, and Teacher. There is also a first-login setup flow: accounts can be forced to change bootstrap credentials before they can access the rest of the system.

7. The data model is organized around educational resources and operations:
   - identity and access: `user`
   - academic structure: `department`, `subject`, `class_`, `room`, `credit`
   - scheduling: `timetable`, `day_order_calendar`, `academic_calendar`
   - leave and substitution: `leave`, `substitution_preference`, `teacher_substitution`
   - operational traceability: `notification`, `audit_log`, `system_setting`
   These are the core entities that the service layer coordinates.

8. The scheduling and leave flows are intentionally constrained by database rules, not just application logic. The schema/migrations in `database/` add uniqueness and check constraints so that teacher/class/room double-booking and invalid calendar-day orders are structurally blocked. This is reinforced by API-level validation in the service layer.

9. The frontend is structured by user role and feature area. Shared shell components live under `src/components/layout`, shared UI primitives under `src/components/ui`, and route guards under `src/routes/Guards.jsx`. Pages are split into `admin/`, `teacher/`, `auth/`, and `common/`, reflecting the same RBAC boundaries used on the backend.

10. Frontend data flow is straightforward: page components call functions from `src/api/services.js`, which wraps the Axios client in `src/api/client.js`. Authentication state is held in `AuthContext`, while theme state is in `ThemeContext`. The app shell and navigation components render different experiences based on the authenticated role.

11. Notifications and reporting are separate subsystems but share the same domain data. The backend has services for notifications, reports, summary, dashboards, and substitution ranking/assignment. On the UI side, there are dedicated admin dashboards for calendar reports, resource availability, credits, and substitutions.

12. Operationally, the repo includes deployment and maintenance tooling alongside the app code:
   - `database/schema.sql`, `database/migrations/`, and `database/seed.sql` define the persistent model and upgrade path.
   - `backend/preflight_check.py` validates schema expectations.
   - `backend/scripts/factory_reset.py` and `scripts/` provide recovery/reset workflows.
   - `DEPLOYMENT.md` documents production setup, and `scripts/deploy_linux.sh` / `scripts/deploy_windows.bat` automate deployment steps.

13. Test coverage is broad and maps closely to the service and route boundaries. `backend/tests/` includes unit/integration tests for auth, core security, dependencies, calendar, timetable, leave, notifications, admin workflows, and route behavior. This suggests the repository treats service logic as the primary correctness layer and validates it independently from the UI.

14. For an architecture diagram, the most important end-to-end flows are:
   - Browser → React page/component → Axios API client → FastAPI route → service → SQLAlchemy model → PostgreSQL
   - Login/bootstrap setup → JWT issuance and RBAC guard → role-specific dashboards
   - Calendar mutation → calendar service → affected timetable/leave/substitution/reporting logic
   - Leave approval → substitution/credit/notification services → persistent audit trail
   - Factory reset → backup/reset script → full data wipe/reseed path

Main entry points: [`backend/app/services`](https://github.com/kamesh12k/facredit/tree/main/backend/app/services) (Business services), [`backend/app/services/academic_calendar_service.py`](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/academic_calendar_service.py) (Calendar engine), [`frontend/src/pages`](https://github.com/kamesh12k/facredit/tree/main/frontend/src/pages) (Role pages), [`database/schema.sql`](https://github.com/kamesh12k/facredit/blob/main/database/schema.sql) (Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>entrypoint<br/>[main.py]"]
  node_backend_routes["API routes<br/>http layer"]
  node_backend_services["Business services<br/>service layer"]
  node_backend_calendar{{"Calendar engine<br/>domain service"}}
  node_backend_auth{{"Auth & RBAC<br/>security<br/>[security.py]"}}
  node_backend_dependencies["Dependencies<br/>injection<br/>[dependencies.py]"]
  node_backend_db[("DB setup<br/>infrastructure<br/>[database.py]")]
  node_backend_models[("ORM models<br/>data model")]
  node_backend_schemas["Schemas<br/>contracts"]
  node_backend_notifications(("Notifications<br/>workflow"))
  node_backend_timetable(("Timetable<br/>workflow"))
  node_backend_leaves(("Leaves<br/>workflow<br/>[leave_service.py]"))
  node_backend_substitutions(("Substitutions<br/>workflow"))
end

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>layout<br/>[AppShell.jsx]"]
  node_frontend_auth["Auth state<br/>[AuthContext.jsx]"]
  node_frontend_api["API client<br/>[services.js]"]
  node_frontend_guards{{"Route guards<br/>routing<br/>[Guards.jsx]"}}
  node_frontend_pages["Role pages<br/>ui pages"]
end

subgraph group_database["Database"]
  node_db_schema[("Schema<br/>postgres ddl<br/>[schema.sql]")]
  node_db_migrations["Migrations<br/>postgres ddl"]
  node_db_seed["Seed data<br/>postgres seed<br/>[seed.sql]"]
end

subgraph group_ops["Ops"]
  node_ops_reset["Factory reset<br/>maintenance<br/>[factory_reset.py]"]
  node_ops_check["Preflight<br/>validation<br/>[preflight_check.py]"]
  node_ops_deploy["Deploy scripts<br/>deployment"]
end

node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"calls"| node_backend_services
node_backend_services -->|"gates by"| node_backend_calendar
node_backend_services -->|"protects"| node_backend_auth
node_backend_services -->|"uses"| node_backend_dependencies
node_backend_services -->|"persists via"| node_backend_db
node_backend_services -->|"mutates"| node_backend_models
node_backend_services -->|"validates with"| node_backend_schemas
node_backend_calendar -->|"controls"| node_backend_timetable
node_backend_calendar -->|"controls"| node_backend_leaves
node_backend_calendar -->|"controls"| node_backend_substitutions
node_backend_leaves -->|"triggers"| node_backend_substitutions
node_backend_leaves -->|"emits"| node_backend_notifications
node_backend_substitutions -->|"emits"| node_backend_notifications
node_backend_timetable -->|"reports to"| node_backend_notifications
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_api -->|"consumes"| node_backend_routes
node_frontend_pages -->|"restricted by"| node_frontend_guards
node_frontend_pages -->|"reads"| node_frontend_auth
node_frontend_shell -->|"hosts"| node_frontend_pages
node_db_schema -->|"matches"| node_backend_models
node_db_migrations -->|"evolves"| node_db_schema
node_db_seed -->|"bootstraps"| node_db_schema
node_ops_check -->|"verifies"| node_db_schema
node_ops_reset -->|"rebuilds"| node_db_seed
node_ops_deploy -->|"starts"| node_backend_main
node_ops_deploy -->|"builds"| node_frontend_shell

click node_backend_main "https://github.com/kamesh12k/facredit/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/kamesh12k/facredit/tree/main/backend/app/routes"
click node_backend_services "https://github.com/kamesh12k/facredit/tree/main/backend/app/services"
click node_backend_calendar "https://github.com/kamesh12k/facredit/blob/main/backend/app/services/academic_calendar_service.py"
click node_backend_auth "https://github.com/kamesh12k/facredit/blob/main/backend/app/core/security.py"
click node_backend_dependencies "https://github.com/kamesh12k/facredit/blob/main/backend/app/core/dependencies.py"
click node_backend_db "https://github.com/kamesh12k/facredit/blob/main/backend/app/database.py"
click node_backend_models "https://github.com/kamesh12k/facredit/tree/main/backend/app/models"
click node_backend_schemas "https://github.com/kamesh12k/facredit/tree/main/backend/app/schemas"
click node_backend_notifications "https://github.com/kamesh12k/facredit/blob/main/backend/app/services/notification_service.py"
click node_backend_timetable "https://github.com/kamesh12k/facredit/blob/main/backend/app/services/timetable_service.py"
click node_backend_leaves "https://github.com/kamesh12k/facredit/blob/main/backend/app/services/leave_service.py"
click node_backend_substitutions "https://github.com/kamesh12k/facredit/blob/main/backend/app/services/substitution_service.py"
click node_frontend_shell "https://github.com/kamesh12k/facredit/blob/main/frontend/src/components/layout/AppShell.jsx"
click node_frontend_auth "https://github.com/kamesh12k/facredit/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_api "https://github.com/kamesh12k/facredit/blob/main/frontend/src/api/services.js"
click node_frontend_guards "https://github.com/kamesh12k/facredit/blob/main/frontend/src/routes/Guards.jsx"
click node_frontend_pages "https://github.com/kamesh12k/facredit/tree/main/frontend/src/pages"
click node_db_schema "https://github.com/kamesh12k/facredit/blob/main/database/schema.sql"
click node_db_migrations "https://github.com/kamesh12k/facredit/tree/main/database/migrations"
click node_db_seed "https://github.com/kamesh12k/facredit/blob/main/database/seed.sql"
click node_ops_reset "https://github.com/kamesh12k/facredit/blob/main/backend/scripts/factory_reset.py"
click node_ops_check "https://github.com/kamesh12k/facredit/blob/main/backend/preflight_check.py"
click node_ops_deploy "https://github.com/kamesh12k/facredit/tree/main/scripts"

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_backend_main,node_backend_routes,node_backend_services,node_backend_calendar,node_backend_auth,node_backend_dependencies,node_backend_db,node_backend_models,node_backend_schemas,node_backend_notifications,node_backend_timetable,node_backend_leaves,node_backend_substitutions toneBlue
class node_frontend_shell,node_frontend_auth,node_frontend_api,node_frontend_guards,node_frontend_pages toneAmber
class node_db_schema,node_db_migrations,node_db_seed toneMint
class node_ops_reset,node_ops_check,node_ops_deploy toneRose
```

## Components

### Backend

FastAPI application with layered API, service, model, and security boundaries.

- [FastAPI app](https://github.com/kamesh12k/facredit/blob/main/backend/app/main.py): entrypoint · Creates the FastAPI application and wires routers and app-wide setup. · `backend/app/main.py`
- [API routes](https://github.com/kamesh12k/facredit/tree/main/backend/app/routes): http layer · Thin HTTP endpoints grouped by domain. · `backend/app/routes`
- [Business services](https://github.com/kamesh12k/facredit/tree/main/backend/app/services): service layer · Domain workflows and cross-entity rules. · `backend/app/services`
- [Calendar engine](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/academic_calendar_service.py): domain service · Academic calendar and day-order control point used to gate scheduling and leave mutations. · `backend/app/services/academic_calendar_service.py`
- [Auth & RBAC](https://github.com/kamesh12k/facredit/blob/main/backend/app/core/security.py): security · JWT auth, password hashing, and role guards including bootstrap first-login setup. · `backend/app/core/security.py`
- [Dependencies](https://github.com/kamesh12k/facredit/blob/main/backend/app/core/dependencies.py): injection · Shared dependency wiring for DB sessions and authorization checks. · `backend/app/core/dependencies.py`
- [DB setup](https://github.com/kamesh12k/facredit/blob/main/backend/app/database.py): infrastructure · Central database and session configuration. · `backend/app/database.py`
- [ORM models](https://github.com/kamesh12k/facredit/tree/main/backend/app/models): data model · SQLAlchemy entities for identity, scheduling, leave, substitution, notifications, and audit. · `backend/app/models`
- [Schemas](https://github.com/kamesh12k/facredit/tree/main/backend/app/schemas): contracts · Pydantic request and response contracts plus validation rules. · `backend/app/schemas`
- [Notifications](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/notification_service.py): workflow · Notification, reporting, summary, dashboard, and substitution ranking workflows. · `backend/app/services/notification_service.py`
- [Timetable](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/timetable_service.py): workflow · Scheduling creation and conflict handling, gated by calendar rules. · `backend/app/services/timetable_service.py`
- [Leaves](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/leave_service.py): workflow · Leave request and approval flow that coordinates substitutions and credit effects. · `backend/app/services/leave_service.py`
- [Substitutions](https://github.com/kamesh12k/facredit/blob/main/backend/app/services/substitution_service.py): workflow · Substitution assignment, preferences, dashboarding, and teacher substitution handling. · `backend/app/services/substitution_service.py`

### Frontend

React/Vite client organized by role-based pages and shared shell components.

- [App shell](https://github.com/kamesh12k/facredit/blob/main/frontend/src/components/layout/AppShell.jsx): layout · Authenticated shell, navigation, search, and notifications. · `frontend/src/components/layout/AppShell.jsx`
- [Auth state](https://github.com/kamesh12k/facredit/blob/main/frontend/src/context/AuthContext.jsx): state · Authentication and theme context providers. · `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/kamesh12k/facredit/blob/main/frontend/src/api/services.js): client · Axios client and service wrapper used by pages. · `frontend/src/api/services.js`
- [Route guards](https://github.com/kamesh12k/facredit/blob/main/frontend/src/routes/Guards.jsx): routing · Role-based access control for frontend navigation. · `frontend/src/routes/Guards.jsx`
- [Role pages](https://github.com/kamesh12k/facredit/tree/main/frontend/src/pages): ui pages · Admin, teacher, auth, and common route-driven screens. · `frontend/src/pages`

### Database

PostgreSQL schema, migrations, and seed data.

- [Schema](https://github.com/kamesh12k/facredit/blob/main/database/schema.sql): postgres ddl · Base PostgreSQL schema and table definitions. · `database/schema.sql`
- [Migrations](https://github.com/kamesh12k/facredit/tree/main/database/migrations): postgres ddl · Incremental schema changes for RBAC, audit, calendar, and autonomous substitution. · `database/migrations`
- [Seed data](https://github.com/kamesh12k/facredit/blob/main/database/seed.sql): postgres seed · Initial data used to bootstrap the database. · `database/seed.sql`

### Ops

Reset, validation, and deployment tooling.

- [Factory reset](https://github.com/kamesh12k/facredit/blob/main/backend/scripts/factory_reset.py): maintenance · Recovery/reset workflow for wiping and reseeding data. · `backend/scripts/factory_reset.py`
- [Preflight](https://github.com/kamesh12k/facredit/blob/main/backend/preflight_check.py): validation · Validates schema expectations before runtime or deployment. · `backend/preflight_check.py`
- [Deploy scripts](https://github.com/kamesh12k/facredit/tree/main/scripts): deployment · Linux and Windows deployment automation. · `scripts`

## Connections

- FastAPI app → API routes: mounts · App startup registers HTTP routers.
- API routes → Business services: calls · Endpoints delegate business logic to services.
- Business services → Calendar engine: gates by · Scheduling and leave workflows consult calendar/day-order state.
- Business services → Auth & RBAC: protects · Authentication and role guards protect sensitive workflows.
- Business services → Dependencies: uses · Services and routes rely on injected sessions and guards.
- Business services → DB setup: persists via · Services use the central database/session setup.
- Business services → ORM models: mutates · Business workflows operate on ORM entities.
- Business services → Schemas: validates with · Schemas define request and response contracts.
- Calendar engine → Timetable: controls · Calendar decisions affect timetable writes.
- Calendar engine → Leaves: controls · Leave requests are rejected on non-working dates.
- Calendar engine → Substitutions: controls · Substitution workflows respect calendar availability.
- Leaves → Substitutions: triggers · Approved leaves can create substitution work.
- Leaves → Notifications: emits · Leave lifecycle updates drive notifications and summaries.
- Substitutions → Notifications: emits · Assignments and ranking changes notify stakeholders.
- Timetable → Notifications: reports to · Scheduling activity feeds dashboards and reporting.
- Role pages → API client: calls · Pages fetch and mutate data through the API layer.
- API client → API routes: consumes · Client talks to FastAPI endpoints.
- Role pages → Route guards: restricted by · Routes are protected by role-based guards.
- Role pages → Auth state: reads · UI adapts to auth and theme state.
- App shell → Role pages: hosts · Shell renders the active role-specific route content.
- Schema → ORM models: matches · Schema tables correspond to ORM entities.
- Migrations → Schema: evolves · Migrations extend and constrain the base schema.
- Seed data → Schema: bootstraps · Seed data populates the schema.
- Preflight → Schema: verifies · Preflight checks expected schema shape.
- Factory reset → Seed data: rebuilds · Reset workflow wipes and reseeds data.
- Deploy scripts → FastAPI app: starts · Deployment scripts launch the backend service.
- Deploy scripts → App shell: builds · Deployment scripts support frontend delivery.