# mahmudswe/result-processing-backend architecture

> Architecture diagram of the GitHub repository mahmudswe/result-processing-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/mahmudswe/result-processing-backend
- Repository: https://github.com/mahmudswe/result-processing-backend

## Overview

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: [`src/app.module.ts`](https://github.com/mahmudswe/result-processing-backend/blob/main/src/app.module.ts) (App module), [`database/migrations/001_initial_schema.sql`](https://github.com/mahmudswe/result-processing-backend/blob/main/database/migrations/001_initial_schema.sql) (PostgreSQL), [`src/common`](https://github.com/mahmudswe/result-processing-backend/tree/main/src/common) (Common), [`src/auth`](https://github.com/mahmudswe/result-processing-backend/tree/main/src/auth) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("main<br/>bootstrap<br/>[main.ts]"))
  node_app_module["App module<br/>composition<br/>[app.module.ts]"]
end

subgraph group_domains["Domain modules"]
  node_auth["Auth<br/>security module"]
  node_student["Student<br/>master-data module"]
  node_teacher["Teacher<br/>master-data module"]
  node_department["Department<br/>master-data module"]
  node_course["Course<br/>master-data module"]
  node_takes["Takes<br/>enrollment module"]
  node_teach["Teach<br/>assignment module"]
  node_prereq["Prerequisite<br/>relationship module"]
  node_result["Result<br/>grading module"]
  node_analytics["Analytics<br/>reporting module"]
end

subgraph group_platform["Platform"]
  node_common["Common<br/>shared platform"]
end

subgraph group_infrastructure["Infrastructure"]
  node_db[("PostgreSQL<br/>relational database")]
  node_redis[("Redis<br/>cache/store<br/>[redis.config.ts]")]
  node_bull["Bull<br/>job queue<br/>[bull.config.ts]"]
  node_config["Config"]
end

node_main -->|"boots"| node_app_module
node_app_module -->|"loads"| node_auth
node_app_module -->|"loads"| node_student
node_app_module -->|"loads"| node_teacher
node_app_module -->|"loads"| node_department
node_app_module -->|"loads"| node_course
node_app_module -->|"loads"| node_takes
node_app_module -->|"loads"| node_teach
node_app_module -->|"loads"| node_prereq
node_app_module -->|"loads"| node_result
node_app_module -->|"loads"| node_analytics
node_auth -->|"uses"| node_common
node_student -->|"uses"| node_common
node_teacher -->|"uses"| node_common
node_department -->|"uses"| node_common
node_course -->|"uses"| node_common
node_takes -->|"uses"| node_common
node_teach -->|"uses"| node_common
node_result -->|"uses"| node_common
node_analytics -->|"reads"| node_db
node_auth -->|"persists"| node_db
node_student -->|"persists"| node_db
node_teacher -->|"persists"| node_db
node_department -->|"persists"| node_db
node_course -->|"persists"| node_db
node_takes -->|"persists"| node_db
node_teach -->|"persists"| node_db
node_prereq -->|"persists"| node_db
node_result -->|"persists"| node_db
node_auth -.->|"supports"| node_redis
node_auth -.->|"supports"| node_bull
node_config -->|"configures"| node_db
node_config -->|"configures"| node_redis
node_config -->|"configures"| node_bull

click node_main "https://github.com/mahmudswe/result-processing-backend/blob/main/src/main.ts"
click node_app_module "https://github.com/mahmudswe/result-processing-backend/blob/main/src/app.module.ts"
click node_auth "https://github.com/mahmudswe/result-processing-backend/tree/main/src/auth"
click node_student "https://github.com/mahmudswe/result-processing-backend/tree/main/src/student"
click node_teacher "https://github.com/mahmudswe/result-processing-backend/tree/main/src/teacher"
click node_department "https://github.com/mahmudswe/result-processing-backend/tree/main/src/department"
click node_course "https://github.com/mahmudswe/result-processing-backend/tree/main/src/course"
click node_takes "https://github.com/mahmudswe/result-processing-backend/tree/main/src/takes"
click node_teach "https://github.com/mahmudswe/result-processing-backend/tree/main/src/teach"
click node_prereq "https://github.com/mahmudswe/result-processing-backend/tree/main/src/course-prerequisite"
click node_result "https://github.com/mahmudswe/result-processing-backend/tree/main/src/result"
click node_analytics "https://github.com/mahmudswe/result-processing-backend/tree/main/src/analytics"
click node_common "https://github.com/mahmudswe/result-processing-backend/tree/main/src/common"
click node_db "https://github.com/mahmudswe/result-processing-backend/blob/main/database/migrations/001_initial_schema.sql"
click node_redis "https://github.com/mahmudswe/result-processing-backend/blob/main/src/config/redis.config.ts"
click node_bull "https://github.com/mahmudswe/result-processing-backend/blob/main/src/config/bull.config.ts"
click node_config "https://github.com/mahmudswe/result-processing-backend/tree/main/src/config"

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_app_module toneBlue
class node_auth,node_student,node_teacher,node_department,node_course,node_takes,node_teach,node_prereq,node_result,node_analytics toneAmber
class node_common toneMint
class node_db,node_redis,node_bull,node_config toneRose
```

## Components

### Runtime

Application entrypoint and Nest composition

- [main](https://github.com/mahmudswe/result-processing-backend/blob/main/src/main.ts): bootstrap · Starts the NestJS API · `src/main.ts`
- [App module](https://github.com/mahmudswe/result-processing-backend/blob/main/src/app.module.ts): composition · Wires feature modules together · `src/app.module.ts`

### Domain modules

Academic business capabilities

- [Auth](https://github.com/mahmudswe/result-processing-backend/tree/main/src/auth): security module · Login, registration, JWT, refresh tokens · `src/auth`
- [Student](https://github.com/mahmudswe/result-processing-backend/tree/main/src/student): master-data module · Student profile and CRUD operations · `src/student`
- [Teacher](https://github.com/mahmudswe/result-processing-backend/tree/main/src/teacher): master-data module · Teacher profile and CRUD operations · `src/teacher`
- [Department](https://github.com/mahmudswe/result-processing-backend/tree/main/src/department): master-data module · Department management · `src/department`
- [Course](https://github.com/mahmudswe/result-processing-backend/tree/main/src/course): master-data module · Course management · `src/course`
- [Takes](https://github.com/mahmudswe/result-processing-backend/tree/main/src/takes): enrollment module · Student-course enrollment boundary · `src/takes`
- [Teach](https://github.com/mahmudswe/result-processing-backend/tree/main/src/teach): assignment module · Teacher-course assignment boundary · `src/teach`
- [Prerequisite](https://github.com/mahmudswe/result-processing-backend/tree/main/src/course-prerequisite): relationship module · Course dependency relationships · `src/course-prerequisite`
- [Result](https://github.com/mahmudswe/result-processing-backend/tree/main/src/result): grading module · Theory, lab, and overall result workflows · `src/result`
- [Analytics](https://github.com/mahmudswe/result-processing-backend/tree/main/src/analytics): reporting module · Cross-domain aggregation and reporting · `src/analytics`

### Platform

Shared guards, decorators, entities, and repositories

- [Common](https://github.com/mahmudswe/result-processing-backend/tree/main/src/common): shared platform · Roles, guards, decorators, filters, pagination, user model · `src/common`

### Infrastructure

Database, cache, jobs, and config

- [PostgreSQL](https://github.com/mahmudswe/result-processing-backend/blob/main/database/migrations/001_initial_schema.sql): relational database · Primary persistence store via TypeORM · `database/migrations/001_initial_schema.sql`
- [Redis](https://github.com/mahmudswe/result-processing-backend/blob/main/src/config/redis.config.ts): cache/store · Shared runtime state and caching · `src/config/redis.config.ts`
- [Bull](https://github.com/mahmudswe/result-processing-backend/blob/main/src/config/bull.config.ts): job queue · Background job processing support · `src/config/bull.config.ts`
- [Config](https://github.com/mahmudswe/result-processing-backend/tree/main/src/config): runtime config · Database, logging, rate limit, and storage configuration · `src/config`

## Connections

- 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