How mahmudswe/result-processing-backend works
1. Overall shape
- This is a NestJS backend API organized as a modular monolith.
- The application entrypoint is src/main.ts, with src/app.module.ts composing the feature modules.
- The core runtime path is HTTP REST requests flowing through Nest controllers, services, and repositories into PostgreSQL via TypeORM.
2. Domain modules
- The repo is split into business modules: auth, student, teacher, department, course, result, analytics, takes, teach, and course-prerequisite.
- Each feature module typically contains a controller, service, DTOs, entity definitions, and a repository layer.
- This makes the system easy to diagram as bounded academic domains rather than one large CRUD app.
3. Authentication and access control
- src/auth implements JWT-based login, registration, token refresh, and logout.
- It uses Passport strategies (local and jwt), a local auth guard for credential validation, and JWT auth guards for protected routes.
- Refresh token persistence is modeled explicitly through refresh-token.entity.ts and refresh-token.repository.ts, which indicates server-side token revocation/state in addition to stateless access tokens.
- Authorization is role-based via decorators and guards in src/common (roles.decorator.ts, roles.guard.ts), with roles such as student, teacher, and admin.
4. Request processing pipeline
- Controllers define the HTTP surface for each domain.
- Services contain business rules and orchestration.
- Repositories encapsulate persistence and query logic.
- Cross-cutting concerns like exception formatting, current-user extraction, and pagination live in src/common, which acts as the shared platform layer across modules.
5. Data model and persistence
- Persistence is centered on PostgreSQL, with the schema defined in database/migrations/001_initial_schema.sql.
- The schema includes academic entities such as users, departments, students, teachers, courses, enrollments (takes), teaching assignments (teach), results, theory/lab result splits, course prerequisites, and refresh tokens.
- The entities folders mirror these tables, while repositories wrap TypeORM access patterns.
- database/seed-data.sql and database/setup-all.sh show this repo supports local bootstrapping and test-data loading.
6. Academic subdomains
- student, teacher, department, and course are the core master-data modules.
- takes models student-course enrollment.
- teach models teacher-course assignment.
- course-prerequisite is a separate boundary for course dependency relationships, even if the README notes it as not fully implemented.
- result is the most complex domain, split into overall results plus theory and lab result entities/repositories, suggesting specialized grading workflows.
7. Analytics and aggregation
- analytics is isolated from the CRUD modules and appears to serve reporting/aggregation use cases.
- Its repository likely contains heavier SQL or multi-table joins for rankings and department-level summaries.
- This boundary is important architecturally because analytics reads across multiple domains without being part of transactional CRUD flows.
8. Infrastructure and cross-cutting services
- Redis configuration exists in src/config/redis.config.ts, indicating caching or shared runtime state.
- Bull configuration in src/config/bull.config.ts indicates background-job support for asynchronous tasks.
- Rate limiting, logging, database, and storage each have dedicated config files, so these concerns are centralized rather than scattered through feature modules.
9. API security and consistency
- Input validation is DTO-driven, using separate create/update/query DTOs per module.
- Security is reinforced by guards, exception filters, and a common user model.
- The presence of all-exceptions.filter.ts and jwt-auth.guard.ts suggests the API standardizes error output and protection across all endpoints.
10. Operational/runtime packaging
- The repo includes a Dockerfile and docker-compose.yml, so the system is designed to run as a containerized API with external PostgreSQL and Redis services.
- nest-cli.json, tsconfig.json, and the package files confirm a standard NestJS/TypeScript build pipeline.
- database/performance-tests.sql reflects an emphasis on query performance and tuning, especially for the analytics-heavy and join-heavy academic data model.
11. How to draw the main architecture
- A good diagram would show clients calling a NestJS API gateway layer, then branching into feature modules.
- Most modules read/write PostgreSQL through repositories; auth additionally reads/writes refresh tokens and applies JWT/role guards.
- Analytics should be shown as a read-heavy consumer of the same database, while Redis and Bull sit beside the API as supporting infrastructure rather than primary business stores.
Main entry points: app.module.ts App module · 001_initial_schema.sql PostgreSQL · common Common · auth Auth
Components 17
Runtime
Application entrypoint and Nest composition
- main · Starts the NestJS API
src/main.ts - App module · Wires feature modules together
src/app.module.ts
Domain modules
Academic business capabilities
- Auth · Login, registration, JWT, refresh tokens
src/auth - Student · Student profile and CRUD operations
src/student - Teacher · Teacher profile and CRUD operations
src/teacher - Department · Department management
src/department - Course · Course management
src/course - Takes · Student-course enrollment boundary
src/takes - Teach · Teacher-course assignment boundary
src/teach - Prerequisite · Course dependency relationships
src/course-prerequisite - Result · Theory, lab, and overall result workflows
src/result - Analytics · Cross-domain aggregation and reporting
src/analytics
Platform
Shared guards, decorators, entities, and repositories
- Common · Roles, guards, decorators, filters, pagination, user model
src/common
Infrastructure
Database, cache, jobs, and config
- PostgreSQL · Primary persistence store via TypeORM
database/migrations/001_initial_schema.sql - Redis · Shared runtime state and caching
src/config/redis.config.ts - Bull · Background job processing support
src/config/bull.config.ts - Config · Database, logging, rate limit, and storage configuration
src/config
Connections 34
- main → App module: boots · Nest starts from the main bootstrap file
- App module → Auth: loads · Feature modules are composed in the application module
- App module → Student: loads · Feature modules are composed in the application module
- App module → Teacher: loads · Feature modules are composed in the application module
- App module → Department: loads · Feature modules are composed in the application module
- App module → Course: loads · Feature modules are composed in the application module
- App module → Takes: loads · Feature modules are composed in the application module
- App module → Teach: loads · Feature modules are composed in the application module
- App module → Prerequisite: loads · Feature modules are composed in the application module
- App module → Result: loads · Feature modules are composed in the application module
- App module → Analytics: loads · Feature modules are composed in the application module
- Auth → Common: uses · Authentication relies on shared guards, decorators, and user model
- Student → Common: uses · CRUD modules share common platform concerns
- Teacher → Common: uses · CRUD modules share common platform concerns
- Department → Common: uses · CRUD modules share common platform concerns
- Course → Common: uses · CRUD modules share common platform concerns
- Takes → Common: uses · Relationship modules share common platform concerns
- Teach → Common: uses · Relationship modules share common platform concerns
- Result → Common: uses · Result workflows use shared platform concerns
- Analytics → PostgreSQL: reads · Reporting queries read across the relational model
- Auth → PostgreSQL: persists · Refresh tokens and users are stored in PostgreSQL
- Student → PostgreSQL: persists · Domain state is stored in PostgreSQL
- Teacher → PostgreSQL: persists · Domain state is stored in PostgreSQL
- Department → PostgreSQL: persists · Domain state is stored in PostgreSQL
- Course → PostgreSQL: persists · Domain state is stored in PostgreSQL
- Takes → PostgreSQL: persists · Enrollment records are stored in PostgreSQL
- Teach → PostgreSQL: persists · Teaching assignments are stored in PostgreSQL
- Prerequisite → PostgreSQL: persists · Prerequisite relationships are stored in PostgreSQL
- Result → PostgreSQL: persists · Result records and splits are stored in PostgreSQL
- Auth → Redis: supports · Redis is available for shared runtime state and cache
- Auth → Bull: supports · Background jobs can be used by the API
- Config → PostgreSQL: configures · Centralized database/runtime configuration
- Config → Redis: configures · Centralized cache/runtime configuration
- Config → Bull: configures · Centralized queue/runtime configuration