# shahriar-hossain-alvi/edutrack-backend architecture

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

- Interactive diagram: https://gitdiagram.com/shahriar-hossain-alvi/edutrack-backend
- Repository: https://github.com/shahriar-hossain-alvi/edutrack-backend

## Overview

1. **System purpose and runtime**
   - Edutrack is a FastAPI-based backend for student result management.
   - It runs as a containerized Python service, with PostgreSQL as the primary datastore and SQLAlchemy as the ORM.
   - Alembic manages schema evolution through versioned migrations.

2. **Top-level architecture**
   - The code is organized into a classic layered backend:
     - **routes** expose HTTP endpoints,
     - **services** contain business logic,
     - **schemas** define request/response contracts,
     - **models** map to database tables,
     - **core / utils / middleware / permissions** provide cross-cutting concerns.
   - This separation is important for diagramming the request flow from API entrypoint to persistence and back.

3. **Request entrypoint and API composition**
   - `app/main.py` is the application bootstrap and likely wires the FastAPI app, middleware, and route registration.
   - Route modules are split by domain: users, students, teachers, subjects, semesters, marks, notifications, audit logs, and admin dashboard.
   - There is also a health-check route, which is used operationally for deployment warming and uptime checks.

4. **Domain subsystems**
   - The main business domains are:
     - **Identity and access**: users, login/logout, auth-related helpers.
     - **Academic data**: departments, semesters, students, teachers, subjects, subject offerings, marks.
     - **Operational workflows**: notifications, audit logs, dashboard aggregation.
   - Subject offerings appear to be the bridge between subjects, semesters, departments, and assigned teachers.

5. **Authentication and session handling**
   - Authentication is JWT-based, with tokens stored in HttpOnly cookies.
   - A token-injection middleware reads the cookie and adds an Authorization header so FastAPI dependencies like OAuth2PasswordBearer can work normally.
   - The `core/jwt.py`, `core/authenticated_user.py`, and `services/user_login_logout.py` modules likely form the auth boundary.

6. **Authorization model**
   - Role-based access control is implemented through dependency injection and permission helpers.
   - `permissions/role_checks.py` likely gates endpoints by role: admin, teacher, student.
   - This means the authorization boundary is enforced at the route/dependency layer rather than inside the database layer.

7. **Persistence and database model**
   - `app/models` contains SQLAlchemy entities for the core tables, including audit logs and notifications.
   - `app/db/db.py` and `app/db/base.py` define the database session and declarative base.
   - `app/db/sync_db.py` and `seed_admin.py` indicate support for initialization/seeding alongside normal app startup.

8. **Business logic flow**
   - Routes delegate to services, and services handle validation, checks, and database operations.
   - Utility modules such as `check_existence`, `paginator`, and `integrity_error_parser` support common service-layer concerns.
   - This creates a clear flow: request → schema validation → role check → service logic → model/db operation → response schema.

9. **Auditability and observability**
   - An `audit_log_middleware` intercepts create/update/delete traffic and stores action metadata, including errors, into the database.
   - The audit log model and service form a dedicated subsystem for traceability.
   - Logging configuration and audit-level helpers suggest the app is designed to record operational events consistently.

10. **Notifications and realtime side effects**
   - Notifications are modeled separately and have dedicated routes and services.
   - The README indicates result publication can trigger websocket notifications and email delivery.
   - `core/websocket.py` and `core/mail.py` are the likely integration points for these outbound side effects.

11. **External integrations**
   - `utils/cloudinary.py` indicates an external media/storage integration, likely for file or image assets.
   - Email delivery is handled separately from core request/response logic.
   - These integrations are intentionally isolated from the main CRUD domain so the core academic workflow remains database-centric.

12. **Schema and migration lifecycle**
   - Alembic migration history is extensive, showing active schema evolution for marks, logs, subjects, semesters, and notifications.
   - The repository supports both local and Docker-based migration execution.
   - This means the data model is treated as a first-class architectural boundary, not an implementation detail.

13. **Deployment and environment**
   - Docker and Docker Compose are central to how the backend is run in both development and production-like setups.
   - Separate compose files and Dockerfiles indicate distinct dev/prod container behavior.
   - Environment configuration is externalized via `.env`, with PostgreSQL connectivity and app settings injected at runtime.

14. **What to reflect in an architecture diagram**
   - Show FastAPI as the central API layer.
   - Surround it with middleware for token injection and audit logging.
   - Split the application into domain route/service/schema/model stacks.
   - Place PostgreSQL behind the ORM and migrations layer.
   - Add outbound integrations for websocket notifications, email, and cloudinary.
   - Include role-based authorization as a cross-cutting dependency between routes and services.

Main entry points: [`app/main.py`](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/main.py) (App bootstrap), [`app/models/__init__.py`](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/models/__init__.py) (Models), [`app/permissions/role_checks.py`](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/permissions/role_checks.py) (Role checks), [`app/services/subject_offering_service.py`](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/subject_offering_service.py) (Academic services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["App bootstrap<br/>FastAPI entrypoint<br/>[main.py]"]
  node_inject_token["Token inject<br/>middleware<br/>[inject_token.py]"]
  node_audit_mw["Audit middleware"]
  node_auth_core["Auth core<br/>jwt/session<br/>[jwt.py]"]
  node_rbac["Role checks<br/>permissions<br/>[role_checks.py]"]
  node_login_routes["Login routes<br/>auth routes<br/>[login_logout.py]"]
  node_user_routes["Users<br/>user routes<br/>[user_routes.py]"]
  node_student_routes["Students<br/>student routes<br/>[student_routes.py]"]
  node_academic_routes["Academics<br/>domain routes"]
  node_notification_routes["Notifications<br/>notification routes"]
  node_audit_routes["Audit logs<br/>audit routes"]
  node_dashboard_routes["Dashboard<br/>admin routes"]
  node_schemas["Schemas<br/>Pydantic contracts<br/>[user_schema.py]"]
  node_user_service["User service<br/>business logic<br/>[user_service.py]"]
  node_student_service["Student service<br/>business logic<br/>[student_service.py]"]
  node_academic_service["Academic services<br/>business logic"]
  node_notification_service["Notification service<br/>business logic"]
  node_audit_service["Audit service<br/>audit logic"]
  node_dashboard_service["Dashboard service<br/>aggregation"]
  node_integrations["Outbounds<br/>external integrations<br/>[mail.py]"]
end

subgraph group_data["Data Layer"]
  node_models[("Models<br/>SQLAlchemy entities<br/>[__init__.py]")]
  node_db_core["DB core<br/>session/base<br/>[db.py]"]
  node_migrations["Migrations<br/>Alembic<br/>[env.py]"]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_ops["Deployment"]
  node_container["Container runtime<br/>docker"]
end

node_main -->|"loads"| node_inject_token
node_main -->|"loads"| node_audit_mw
node_main -->|"registers"| node_login_routes
node_main -->|"registers"| node_user_routes
node_main -->|"registers"| node_student_routes
node_main -->|"registers"| node_academic_routes
node_main -->|"registers"| node_notification_routes
node_main -->|"registers"| node_audit_routes
node_main -->|"registers"| node_dashboard_routes
node_login_routes -->|"uses"| node_auth_core
node_user_routes -->|"guards"| node_rbac
node_student_routes -->|"guards"| node_rbac
node_academic_routes -->|"guards"| node_rbac
node_notification_routes -->|"guards"| node_rbac
node_audit_routes -->|"guards"| node_rbac
node_dashboard_routes -->|"guards"| node_rbac
node_login_routes -->|"calls"| node_user_service
node_user_routes -->|"calls"| node_user_service
node_student_routes -->|"calls"| node_student_service
node_academic_routes -->|"calls"| node_academic_service
node_notification_routes -->|"calls"| node_notification_service
node_audit_routes -->|"calls"| node_audit_service
node_dashboard_routes -->|"calls"| node_dashboard_service
node_user_service -->|"validates"| node_schemas
node_student_service -->|"validates"| node_schemas
node_academic_service -->|"validates"| node_schemas
node_notification_service -->|"validates"| node_schemas
node_audit_service -->|"persists"| node_models
node_user_service -->|"persists"| node_models
node_student_service -->|"persists"| node_models
node_academic_service -->|"persists"| node_models
node_notification_service -->|"persists"| node_models
node_dashboard_service -->|"reads"| node_models
node_models -->|"uses"| node_db_core
node_db_core -->|"connects"| node_postgres
node_migrations -->|"evolves"| node_postgres
node_inject_token -->|"feeds"| node_auth_core
node_audit_mw -->|"feeds"| node_audit_service
node_notification_service -->|"sends"| node_integrations
node_academic_service -->|"sends"| node_integrations
node_main -->|"runs in"| node_container
node_container -->|"configures"| node_db_core

click node_main "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/main.py"
click node_inject_token "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/middleware/inject_token.py"
click node_audit_mw "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/middleware/audit_log_middleware.py"
click node_auth_core "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/core/jwt.py"
click node_rbac "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/permissions/role_checks.py"
click node_login_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/login_logout.py"
click node_user_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/user_routes.py"
click node_student_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/student_routes.py"
click node_academic_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/department_routes.py"
click node_notification_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/notification_routes.py"
click node_audit_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/audit_log_routes.py"
click node_dashboard_routes "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/admin_dashboard_routes.py"
click node_schemas "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/schemas/user_schema.py"
click node_user_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/user_service.py"
click node_student_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/student_service.py"
click node_academic_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/subject_offering_service.py"
click node_notification_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/notification_service.py"
click node_audit_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/audit_logs_service.py"
click node_dashboard_service "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/admin_dashboard_service.py"
click node_models "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/models/__init__.py"
click node_db_core "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/db/db.py"
click node_migrations "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/alembic/env.py"
click node_integrations "https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/core/mail.py"
click node_container "https://github.com/shahriar-hossain-alvi/edutrack-backend/tree/main/Dockerfile"

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_main,node_inject_token,node_audit_mw,node_auth_core,node_rbac,node_login_routes,node_user_routes,node_student_routes,node_academic_routes,node_notification_routes,node_audit_routes,node_dashboard_routes,node_schemas,node_user_service,node_student_service,node_academic_service,node_notification_service,node_audit_service,node_dashboard_service,node_integrations toneBlue
class node_models,node_db_core,node_migrations,node_postgres toneAmber
class node_container toneMint
```

## Components

### Application

FastAPI app, middleware, routes, services, schemas, models, and cross-cutting core logic.

- [App bootstrap](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/main.py): FastAPI entrypoint · Creates the FastAPI app and wires middleware, routes, and app startup behavior. · `app/main.py`
- [Token inject](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/middleware/inject_token.py): middleware · Reads auth cookies and injects an Authorization header for downstream auth dependencies. · `app/middleware/inject_token.py`
- [Audit middleware](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/middleware/audit_log_middleware.py): middleware · Intercepts write actions and records audit metadata and errors. · `app/middleware/audit_log_middleware.py`
- [Auth core](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/core/jwt.py): jwt/session · JWT helpers, authenticated user resolution, password hashing, and cached user context. · `app/core/jwt.py`
- [Role checks](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/permissions/role_checks.py): permissions · Dependency-based role authorization for admin, teacher, and student access control. · `app/permissions/role_checks.py`
- [Login routes](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/login_logout.py): auth routes · Login/logout HTTP endpoints for session lifecycle. · `app/routes/login_logout.py`
- [Users](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/user_routes.py): user routes · User management endpoints. · `app/routes/user_routes.py`
- [Students](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/student_routes.py): student routes · Student CRUD and related academic record endpoints. · `app/routes/student_routes.py`
- [Academics](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/department_routes.py): domain routes · Department, semester, teacher, subject, subject offering, and marks endpoints. · `app/routes/department_routes.py`
- [Notifications](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/notification_routes.py): notification routes · Notification endpoints for academic events and result publication. · `app/routes/notification_routes.py`
- [Audit logs](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/audit_log_routes.py): audit routes · Audit log access endpoints for traceability and review. · `app/routes/audit_log_routes.py`
- [Dashboard](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/routes/admin_dashboard_routes.py): admin routes · Aggregated admin dashboard endpoints. · `app/routes/admin_dashboard_routes.py`
- [Schemas](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/schemas/user_schema.py): Pydantic contracts · Request and response models for users, students, academics, notifications, dashboard, and pagination. · `app/schemas/user_schema.py`
- [User service](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/user_service.py): business logic · User management plus login/logout workflows. · `app/services/user_service.py`
- [Student service](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/student_service.py): business logic · Student domain operations and validation. · `app/services/student_service.py`
- [Academic services](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/subject_offering_service.py): business logic · Department, semester, teacher, subject, subject offering, and marks coordination. · `app/services/subject_offering_service.py`
- [Notification service](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/notification_service.py): business logic · Notification creation and delivery orchestration. · `app/services/notification_service.py`
- [Audit service](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/audit_logs_service.py): audit logic · Persists and queries audit log entries. · `app/services/audit_logs_service.py`
- [Dashboard service](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/services/admin_dashboard_service.py): aggregation · Builds admin dashboard summaries from core academic data. · `app/services/admin_dashboard_service.py`
- [Outbounds](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/core/mail.py): external integrations · Email, websocket, Cloudinary, and logging side-effect integrations. · `app/core/mail.py`

### Data Layer

SQLAlchemy models, database session/base, seed/init, and Alembic migrations.

- [Models](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/models/__init__.py): SQLAlchemy entities · Core database entities for users, students, teachers, subjects, offerings, marks, notifications, and audit logs. · `app/models/__init__.py`
- [DB core](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/app/db/db.py): session/base · Database session management, declarative base, and startup seeding/sync helpers. · `app/db/db.py`
- [Migrations](https://github.com/shahriar-hossain-alvi/edutrack-backend/blob/main/alembic/env.py): Alembic · Versioned schema evolution for the PostgreSQL data model. · `alembic/env.py`
- **PostgreSQL**: database · Primary persistent datastore behind SQLAlchemy and Alembic.

### Deployment

Containerization and runtime configuration for local and production-style execution.

- [Container runtime](https://github.com/shahriar-hossain-alvi/edutrack-backend/tree/main/Dockerfile): docker · Dockerfiles, compose files, and environment-driven deployment configuration. · `Dockerfile`

## Connections

- App bootstrap → Token inject: loads · App startup installs request token injection middleware.
- App bootstrap → Audit middleware: loads · App startup installs audit logging middleware.
- App bootstrap → Login routes: registers · Main app registers auth routes.
- App bootstrap → Users: registers · Main app registers user routes.
- App bootstrap → Students: registers · Main app registers student routes.
- App bootstrap → Academics: registers · Main app registers core academic routes.
- App bootstrap → Notifications: registers · Main app registers notification routes.
- App bootstrap → Audit logs: registers · Main app registers audit log routes.
- App bootstrap → Dashboard: registers · Main app registers admin dashboard routes.
- Login routes → Auth core: uses · Login/logout depends on JWT and user identity helpers.
- Users → Role checks: guards · Routes are protected by role-based dependencies.
- Students → Role checks: guards · Routes are protected by role-based dependencies.
- Academics → Role checks: guards · Academic endpoints enforce role-based access.
- Notifications → Role checks: guards · Notification endpoints enforce role-based access.
- Audit logs → Role checks: guards · Audit access is role restricted.
- Dashboard → Role checks: guards · Dashboard access is role restricted.
- Login routes → User service: calls · Auth endpoints delegate to user login/logout service.
- Users → User service: calls · User endpoints delegate to user management service.
- Students → Student service: calls · Student endpoints delegate to student service.
- Academics → Academic services: calls · Academic endpoints delegate to domain services.
- Notifications → Notification service: calls · Notification endpoints delegate to notification service.
- Audit logs → Audit service: calls · Audit endpoints delegate to audit service.
- Dashboard → Dashboard service: calls · Dashboard endpoints delegate to aggregation service.
- User service → Schemas: validates · Services consume and produce typed request/response schemas.
- Student service → Schemas: validates · Services consume and produce typed request/response schemas.
- Academic services → Schemas: validates · Services consume and produce typed request/response schemas.
- Notification service → Schemas: validates · Services consume and produce typed request/response schemas.
- Audit service → Models: persists · Audit service stores and queries audit log rows.
- User service → Models: persists · User workflows operate on SQLAlchemy entities.
- Student service → Models: persists · Student workflows operate on SQLAlchemy entities.
- Academic services → Models: persists · Academic workflows operate on SQLAlchemy entities.
- Notification service → Models: persists · Notifications are stored as database entities.
- Dashboard service → Models: reads · Dashboard aggregates core domain data.
- Models → DB core: uses · Models are bound to the session/base configuration.
- DB core → PostgreSQL: connects · Application sessions and sync helpers talk to PostgreSQL.
- Migrations → PostgreSQL: evolves · Alembic applies versioned schema changes to PostgreSQL.
- Token inject → Auth core: feeds · Injected auth header enables downstream JWT user resolution.
- Audit middleware → Audit service: feeds · Middleware writes request outcome metadata through audit logic.
- Notification service → Outbounds: sends · Notification workflows can trigger websocket and email side effects.
- Academic services → Outbounds: sends · Result publication and related workflows trigger external side effects.
- App bootstrap → Container runtime: runs in · The app is intended to run in containerized environments.
- Container runtime → DB core: configures · Runtime environment injects database and app settings.