How tarequzzaman/smart-learning-backend works
1. What this repository is
- A containerized FastAPI service focused on CRUD APIs backed primarily by SQLAlchemy + PostgreSQL 17.4.
- It exposes HTTP endpoints and serves autogenerated API docs at /docs.
2. Top-level runtime shape
- The application entrypoint is app/main.py.
- Dockerfile and docker-compose.yml define the deployment shape, so the system is intended to run as containers rather than as a bare local process.
3. Request path through the app
- Incoming requests hit the FastAPI app, then flow into app/api/routes.py and app/api/views.py.
- Those layers are the public HTTP boundary: routing, request/response handling, and endpoint orchestration.
4. Business logic boundary
- app/services/ contains the non-HTTP logic used by the API.
- The service modules suggest distinct concerns:
- auth.py for authentication/authorization
- password_helper.py for password hashing/verification
- email_helper.py for outbound email-related work
- cred_generation.py for credential/token/account creation logic
- ai_helper.py for AI-related operations
- This indicates the API layer delegates meaningful work into services rather than embedding it in routes.
5. Persistence layer
- app/db/ is the data-access boundary.
- database.py likely holds the SQLAlchemy engine/session setup.
- crud.py contains the query/update primitives used by the services or views.
- models.py defines ORM entities.
- schemas.py defines request/response validation and serialization models.
- app/db/mongo_db.py exists as a separate DB helper, but the README and project name make PostgreSQL/SQLAlchemy the primary persistence path.
6. Data flow between layers
- Typical flow is: HTTP request → route/view → service → CRUD/ORM → PostgreSQL → response schema → HTTP response.
- Validation and serialization happen at the schema layer, while persistence is isolated behind CRUD/models.
7. Background processing
- app/celery/ contains a Celery application and task definitions.
- This implies some operations can be offloaded from request handling into asynchronous/background jobs.
- The exact broker/backend is not visible here, so those dependencies are likely configured externally via environment/configuration.
8. Cross-cutting support
- config.py centralizes environment-driven configuration.
- app/services/auth.py and password_helper.py indicate security-sensitive logic is separated from generic CRUD code.
- app/services/email_helper.py suggests integration with an external mail provider or SMTP endpoint.
9. External dependencies and infrastructure
- The only explicitly documented external data store is PostgreSQL 17.4.
- Container orchestration is handled by Docker Compose, which likely wires the API container to the database and any task infrastructure.
- FastAPI’s OpenAPI generation provides the interactive docs surface.
10. How to diagram this repo
- Draw four main boundaries: API layer, service layer, database/data-access layer, and background jobs.
- Show PostgreSQL as the primary state store.
- Show Celery as an async side-channel from services for deferred work.
- Keep Mongo as optional/secondary unless a deeper code review shows it is actively used.
Main entry points: views.py Views · crud.py CRUD · main.py App entry · tasks.py Tasks
Components 19
Runtime
Application entrypoint and containerized deployment shape
- App entry · Creates and runs the FastAPI application
app/main.py - Dockerfile · Builds the API container
Dockerfile - Compose · Wires app and supporting services
docker-compose.yml - Config · Centralized environment-driven settings
config.py
API Layer
FastAPI routing and request handling
Services
Business logic and cross-cutting helpers
- Auth · Authentication and authorization logic
app/services/auth.py - Passwords · Password hashing and verification
app/services/password_helper.py - Email · Email-related integration logic
app/services/email_helper.py - Credentials · Credential, token, and account generation
app/services/cred_generation.py - AI helper · AI-related operations used by the app
app/services/ai_helper.py
Data Layer
ORM models, CRUD, schemas, and database setup
- DB setup · Engine and session configuration
app/db/database.py - CRUD · Database query and update primitives
app/db/crud.py - Models · SQLAlchemy entity definitions
app/db/models.py - Schemas · Request and response models
app/db/schemas.py - PostgreSQL · Primary persistent state store
- Mongo helper · Optional MongoDB integration boundary
app/db/mongo_db.py
Background Jobs
Celery app and asynchronous task execution
- Celery app · Async job application and task registration
app/celery/celery_app.py - Tasks · Deferred work executed outside request handling
app/celery/tasks.py
Connections 22
- Dockerfile → App entry: builds · Packages the application entrypoint into a container
- Compose → App entry: runs · Starts the API container alongside dependencies
- Compose → PostgreSQL: provisions · Connects the service to PostgreSQL
- App entry → Routes: mounts · Registers HTTP routes on the FastAPI app
- Routes → Views: dispatches · Routes hand off request handling to views
- App entry → Config: loads · Reads runtime configuration at startup
- Views → Auth: uses · Delegates security-sensitive logic to services
- Views → Passwords: uses · Hashes and verifies credentials
- Views → Email: uses · Triggers outbound email work
- Views → Credentials: uses · Creates tokens and account-related artifacts
- Views → AI helper: uses · Invokes AI-related operations
- Views → Schemas: validates · Shapes request input and response output
- Auth → CRUD: reads/writes · Uses data access primitives for identity flows
- CRUD → DB setup: queries · Executes database operations through SQLAlchemy
- DB setup → Models: maps · Binds ORM models into the session/engine setup
- CRUD → Models: operates on · Persists and loads ORM entities
- CRUD → PostgreSQL: stores in · Primary persistence target
- Views → Celery app: offloads · Sends deferred work to background processing
- Celery app → Tasks: executes · Registers and runs asynchronous tasks
- Tasks → Email: calls · Background jobs can reuse email integration logic
- Tasks → CRUD: uses · Jobs may read or update persistent state
- Mongo helper → CRUD: optional · Secondary database helper boundary, if enabled