How shahriar-hossain-alvi/edutrack-backend works
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: main.py App bootstrap · __init__.py Models · role_checks.py Role checks · subject_offering_service.py Academic services
Components 25
Application
FastAPI app, middleware, routes, services, schemas, models, and cross-cutting core logic.
- App bootstrap · Creates the FastAPI app and wires middleware, routes, and app startup behavior.
app/main.py - Token inject · Reads auth cookies and injects an Authorization header for downstream auth dependencies.
app/middleware/inject_token.py - Audit middleware · Intercepts write actions and records audit metadata and errors.
app/middleware/audit_log_middleware.py - Auth core · JWT helpers, authenticated user resolution, password hashing, and cached user context.
app/core/jwt.py - Role checks · Dependency-based role authorization for admin, teacher, and student access control.
app/permissions/role_checks.py - Login routes · Login/logout HTTP endpoints for session lifecycle.
app/routes/login_logout.py - Users · User management endpoints.
app/routes/user_routes.py - Students · Student CRUD and related academic record endpoints.
app/routes/student_routes.py - Academics · Department, semester, teacher, subject, subject offering, and marks endpoints.
app/routes/department_routes.py - Notifications · Notification endpoints for academic events and result publication.
app/routes/notification_routes.py - Audit logs · Audit log access endpoints for traceability and review.
app/routes/audit_log_routes.py - Dashboard · Aggregated admin dashboard endpoints.
app/routes/admin_dashboard_routes.py - Schemas · Request and response models for users, students, academics, notifications, dashboard, and pagination.
app/schemas/user_schema.py - User service · User management plus login/logout workflows.
app/services/user_service.py - Student service · Student domain operations and validation.
app/services/student_service.py - Academic services · Department, semester, teacher, subject, subject offering, and marks coordination.
app/services/subject_offering_service.py - Notification service · Notification creation and delivery orchestration.
app/services/notification_service.py - Audit service · Persists and queries audit log entries.
app/services/audit_logs_service.py - Dashboard service · Builds admin dashboard summaries from core academic data.
app/services/admin_dashboard_service.py - Outbounds · 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 · Core database entities for users, students, teachers, subjects, offerings, marks, notifications, and audit logs.
app/models/__init__.py - DB core · Database session management, declarative base, and startup seeding/sync helpers.
app/db/db.py - Migrations · Versioned schema evolution for the PostgreSQL data model.
alembic/env.py - PostgreSQL · Primary persistent datastore behind SQLAlchemy and Alembic.
Deployment
Containerization and runtime configuration for local and production-style execution.
- Container runtime · Dockerfiles, compose files, and environment-driven deployment configuration.
Dockerfile
Connections 42
- 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.