How kamesh12k/facredit works
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: services Business services · academic_calendar_service.py Calendar engine · pages Role pages · schema.sql Schema
Components 24
Backend
FastAPI application with layered API, service, model, and security boundaries.
- FastAPI app · Creates the FastAPI application and wires routers and app-wide setup.
backend/app/main.py - API routes · Thin HTTP endpoints grouped by domain.
backend/app/routes - Business services · Domain workflows and cross-entity rules.
backend/app/services - Calendar engine · Academic calendar and day-order control point used to gate scheduling and leave mutations.
backend/app/services/academic_calendar_service.py - Auth & RBAC · JWT auth, password hashing, and role guards including bootstrap first-login setup.
backend/app/core/security.py - Dependencies · Shared dependency wiring for DB sessions and authorization checks.
backend/app/core/dependencies.py - DB setup · Central database and session configuration.
backend/app/database.py - ORM models · SQLAlchemy entities for identity, scheduling, leave, substitution, notifications, and audit.
backend/app/models - Schemas · Pydantic request and response contracts plus validation rules.
backend/app/schemas - Notifications · Notification, reporting, summary, dashboard, and substitution ranking workflows.
backend/app/services/notification_service.py - Timetable · Scheduling creation and conflict handling, gated by calendar rules.
backend/app/services/timetable_service.py - Leaves · Leave request and approval flow that coordinates substitutions and credit effects.
backend/app/services/leave_service.py - Substitutions · 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 · Authenticated shell, navigation, search, and notifications.
frontend/src/components/layout/AppShell.jsx - Auth state · Authentication and theme context providers.
frontend/src/context/AuthContext.jsx - API client · Axios client and service wrapper used by pages.
frontend/src/api/services.js - Route guards · Role-based access control for frontend navigation.
frontend/src/routes/Guards.jsx - Role pages · Admin, teacher, auth, and common route-driven screens.
frontend/src/pages
Database
PostgreSQL schema, migrations, and seed data.
- Schema · Base PostgreSQL schema and table definitions.
database/schema.sql - Migrations · Incremental schema changes for RBAC, audit, calendar, and autonomous substitution.
database/migrations - Seed data · Initial data used to bootstrap the database.
database/seed.sql
Ops
Reset, validation, and deployment tooling.
- Factory reset · Recovery/reset workflow for wiping and reseeding data.
backend/scripts/factory_reset.py - Preflight · Validates schema expectations before runtime or deployment.
backend/preflight_check.py - Deploy scripts · Linux and Windows deployment automation.
scripts
Connections 27
- 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.