# darkasfu/nestjs-task-management-backend architecture

> Architecture diagram of the GitHub repository darkasfu/nestjs-task-management-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/darkasfu/nestjs-task-management-backend
- Repository: https://github.com/darkasfu/nestjs-task-management-backend

## Overview

1. **High-level shape**
   - This repository is a **NestJS backend monolith** for task management.
   - The application is split into feature modules: **auth**, **users**, **tasks**, and **audit-logs**, with a small **common** layer for shared enums.
   - Persistence is handled through **TypeORM** against **PostgreSQL**. Authentication uses **JWT + Passport**.

2. **Request entrypoint and bootstrap**
   - `src/main.ts` is the runtime entrypoint that starts the NestJS HTTP API.
   - `src/app.module.ts` is the composition root that wires the feature modules together.
   - The app is designed to be consumed by a separate frontend, and the README indicates Docker is used to run frontend, backend, and Postgres together.

3. **API layering pattern**
   - Each feature follows the NestJS controller/service/module pattern:
     - **controllers** expose HTTP routes,
     - **services** contain business logic,
     - **modules** register dependencies and exports.
   - This keeps routing, business rules, and persistence concerns separated per domain.

4. **Authentication subsystem**
   - The `auth` module owns login and authentication flow.
   - `auth.controller.ts` exposes `POST /auth/login`.
   - `auth.service.ts` handles credential validation and token issuance.
   - `jwt.strategy.ts` plus `guards/jwt-auth.guard.ts` enforce JWT-based access to protected routes.
   - DTOs under `auth/dto` define login and registration payloads, though the visible API emphasis is login.

5. **Authorization and roles**
   - Role-based authorization is built around `common/enums/role.enum.ts` and the `roles.decorator.ts` / `roles.guard.ts` pair.
   - The backend distinguishes at least **ADMIN** and **USER**.
   - Authorization is not global; it is applied per route, enabling different access rules for users, task owners/assignees, and administrators.

6. **User management subsystem**
   - The `users` module provides administrative access to user data.
   - README exposes `GET /users` for admins, suggesting users are primarily managed/read through backend API rather than a separate user workflow.
   - `users/entities/user.entity.ts` is the persisted user model and is likely linked to tasks, roles, and authentication identity.

7. **Task management subsystem**
   - The `tasks` module is the main business domain.
   - It includes task CRUD, assignment, and status updates.
   - DTOs separate create/update/status-change payloads, indicating distinct command paths:
     - `create-task.dto.ts`
     - `update-task.dto.ts`
     - `update-task-status.dto.ts`
   - `task.entity.ts` is the central persisted model, likely tied to an assignee/owner user and a status enum from `common/enums/task-status.enum.ts`.

8. **Task access model**
   - The README describes route-level permissions:
     - **Admin** can create, list all, update, and delete tasks.
     - **User** can see assigned tasks and update only task status.
     - A single-task lookup is allowed for **admin or owner**.
   - This means the authorization boundary is enforced in the task controllers/guards/services, not only at the database layer.

9. **Audit logging subsystem**
   - `audit-logs` is a separate feature module for recording important task events.
   - It exposes admin-only read access:
     - `GET /audit-logs`
     - `GET /audit-logs/task/:taskId`
   - `audit-log.entity.ts` indicates logs are persisted records, likely written by task lifecycle operations such as create/update/status change/delete.
   - This creates a write path from task operations into audit storage, and a read path for admins.

10. **Persistence model**
    - TypeORM entities define the database schema boundary:
      - `user.entity.ts`
      - `task.entity.ts`
      - `audit-log.entity.ts`
    - The services likely interact with TypeORM repositories to read/write Postgres records.
    - The `DATABASE_URL` environment variable in the README shows PostgreSQL is treated as an external infrastructure dependency.

11. **Cross-cutting shared types**
    - `src/common/enums` centralizes domain constants used across modules.
    - This reduces coupling between features and keeps status/role values consistent across auth, tasks, and authorization logic.

12. **Seed and demo data flow**
    - `src/seed.ts` is a separate bootstrap script for populating demo data.
    - The README says it creates an admin user, a regular user, and sample tasks.
    - This is a distinct operational path from the HTTP API: it initializes the database for local/dev use and supports the role-based demo scenario.

13. **Testing and validation boundary**
    - There is an app controller unit spec and an end-to-end test setup under `test/`.
    - This implies the project validates both lightweight controller behavior and full HTTP-level behavior against the NestJS app.
    - For an architecture diagram, tests should be shown as an external quality/verification layer, not part of the runtime path.

14. **Deployment/runtime concerns**
    - The repo includes a `Dockerfile` and mentions Docker Compose for full-stack local deployment.
    - The backend listens on the configured `PORT` and depends on environment configuration for frontend origin, database connection, and JWT secret.
    - Operationally, the backend is a stateless API process with state stored in PostgreSQL and security anchored by the JWT secret.

Main entry points: [`src/app.module.ts`](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/app.module.ts) (App module), [`src/auth/auth.module.ts`](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.module.ts) (Auth module), [`src/tasks/tasks.service.ts`](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.service.ts) (Tasks service), [`src/tasks/tasks.module.ts`](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.module.ts) (Tasks module)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_features["Features"]
  node_auth_module["Auth module<br/>feature module<br/>[auth.module.ts]"]
  node_auth_controller["Auth API<br/>controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_users_module["Users module<br/>feature module<br/>[users.module.ts]"]
  node_users_controller["Users API<br/>controller"]
  node_users_service["Users service<br/>[users.service.ts]"]
  node_tasks_module["Tasks module<br/>feature module<br/>[tasks.module.ts]"]
  node_tasks_controller["Tasks API<br/>controller"]
  node_tasks_service["Tasks service<br/>[tasks.service.ts]"]
  node_audit_module["Audit module<br/>feature module"]
  node_audit_controller["Audit API<br/>controller"]
  node_audit_service["Audit service"]
end

subgraph group_data["Data"]
  node_user_entity[("User entity<br/>typeorm entity<br/>[user.entity.ts]")]
  node_task_entity[("Task entity<br/>typeorm entity<br/>[task.entity.ts]")]
  node_audit_entity[("Audit entity<br/>typeorm entity")]
  node_seed(("Seed script<br/>bootstrap script<br/>[seed.ts]"))
end

subgraph group_shared["Shared"]
  node_jwt_strategy["JWT strategy<br/>passport strategy<br/>[jwt.strategy.ts]"]
  node_common_enums["Enums<br/>shared constants"]
end

node_main -->|"boots"| node_app_module
node_app_module -->|"imports"| node_auth_module
node_app_module -->|"imports"| node_users_module
node_app_module -->|"imports"| node_tasks_module
node_app_module -->|"imports"| node_audit_module
node_auth_module -->|"exposes"| node_auth_controller
node_auth_module -->|"provides"| node_auth_service
node_auth_module -->|"configures"| node_jwt_strategy
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"reads users"| node_user_entity
node_users_module -->|"exposes"| node_users_controller
node_users_module -->|"provides"| node_users_service
node_users_service -->|"persists"| node_user_entity
node_tasks_module -->|"exposes"| node_tasks_controller
node_tasks_module -->|"provides"| node_tasks_service
node_tasks_controller -->|"calls"| node_tasks_service
node_tasks_service -->|"persists"| node_task_entity
node_tasks_service -->|"writes audit"| node_audit_service
node_audit_module -->|"exposes"| node_audit_controller
node_audit_module -->|"provides"| node_audit_service
node_audit_service -->|"persists"| node_audit_entity
node_common_enums -.->|"role policy"| node_auth_module
node_common_enums -.->|"status model"| node_tasks_module
node_tasks_service -.->|"uses"| node_common_enums
node_seed -->|"creates"| node_user_entity
node_seed -->|"creates"| node_task_entity
node_seed -.->|"uses"| node_common_enums

click node_main "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/main.ts"
click node_app_module "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/app.module.ts"
click node_auth_module "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.module.ts"
click node_auth_controller "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.service.ts"
click node_jwt_strategy "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/jwt.strategy.ts"
click node_users_module "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.module.ts"
click node_users_controller "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.controller.ts"
click node_users_service "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.service.ts"
click node_tasks_module "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.module.ts"
click node_tasks_controller "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.controller.ts"
click node_tasks_service "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.service.ts"
click node_audit_module "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.module.ts"
click node_audit_controller "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.controller.ts"
click node_audit_service "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.service.ts"
click node_user_entity "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/entities/user.entity.ts"
click node_task_entity "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/entities/task.entity.ts"
click node_audit_entity "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/entities/audit-log.entity.ts"
click node_common_enums "https://github.com/darkasfu/nestjs-task-management-backend/tree/main/src/common/enums"
click node_seed "https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/seed.ts"

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_module,node_auth_controller,node_auth_service,node_users_module,node_users_controller,node_users_service,node_tasks_module,node_tasks_controller,node_tasks_service,node_audit_module,node_audit_controller,node_audit_service toneAmber
class node_user_entity,node_task_entity,node_audit_entity,node_seed toneMint
class node_jwt_strategy,node_common_enums toneRose
```

## Components

### Runtime

NestJS app bootstrapping and composition

- [main](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/main.ts): bootstrap · Starts the NestJS HTTP server · `src/main.ts`
- [App module](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/app.module.ts): composition root · Wires the application modules together · `src/app.module.ts`

### Features

Domain modules and API surfaces

- [Auth module](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.module.ts): feature module · Login, JWT, and role-based access · `src/auth/auth.module.ts`
- [Auth API](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.controller.ts): controller · Exposes authentication endpoints · `src/auth/auth.controller.ts`
- [Auth service](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/auth.service.ts): service · Validates credentials and issues tokens · `src/auth/auth.service.ts`
- [Users module](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.module.ts): feature module · Admin-facing user management · `src/users/users.module.ts`
- [Users API](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.controller.ts): controller · Handles user administration routes · `src/users/users.controller.ts`
- [Users service](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/users.service.ts): service · Reads and manages user records · `src/users/users.service.ts`
- [Tasks module](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.module.ts): feature module · Task CRUD, assignment, and status updates · `src/tasks/tasks.module.ts`
- [Tasks API](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.controller.ts): controller · Exposes task management routes · `src/tasks/tasks.controller.ts`
- [Tasks service](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/tasks.service.ts): service · Implements task business rules and audit writes · `src/tasks/tasks.service.ts`
- [Audit module](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.module.ts): feature module · Stores and serves task event history · `src/audit-logs/audit-logs.module.ts`
- [Audit API](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.controller.ts): controller · Exposes admin audit-log queries · `src/audit-logs/audit-logs.controller.ts`
- [Audit service](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/audit-logs.service.ts): service · Persists and queries audit log records · `src/audit-logs/audit-logs.service.ts`

### Data

Persistence entities and seed flow

- [User entity](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/users/entities/user.entity.ts): typeorm entity · Persisted user model and auth identity · `src/users/entities/user.entity.ts`
- [Task entity](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/tasks/entities/task.entity.ts): typeorm entity · Persisted task model and workflow state · `src/tasks/entities/task.entity.ts`
- [Audit entity](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/audit-logs/entities/audit-log.entity.ts): typeorm entity · Persisted audit event record · `src/audit-logs/entities/audit-log.entity.ts`
- [Seed script](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/seed.ts): bootstrap script · Populates demo users and tasks · `src/seed.ts`

### Shared

Cross-cutting enums and auth policy

- [JWT strategy](https://github.com/darkasfu/nestjs-task-management-backend/blob/main/src/auth/jwt.strategy.ts): passport strategy · Authenticates requests with JWTs · `src/auth/jwt.strategy.ts`
- [Enums](https://github.com/darkasfu/nestjs-task-management-backend/tree/main/src/common/enums): shared constants · Role and task-status enums shared across modules · `src/common/enums`

## Connections

- main → App module: boots · HTTP runtime starts from the Nest application root
- App module → Auth module: imports · Composition root registers auth features
- App module → Users module: imports · Composition root registers user features
- App module → Tasks module: imports · Composition root registers task features
- App module → Audit module: imports · Composition root registers audit features
- Auth module → Auth API: exposes · Auth routes are surfaced through the controller
- Auth module → Auth service: provides · Business logic is implemented in the service
- Auth module → JWT strategy: configures · JWT passport strategy is registered for guards
- Auth API → Auth service: calls · Login requests delegate to auth logic
- Auth service → User entity: reads users · Credential validation and identity lookup rely on user records
- Users module → Users API: exposes · User administration routes are surfaced through the controller
- Users module → Users service: provides · User operations are implemented in the service
- Users service → User entity: persists · User data is stored through TypeORM
- Tasks module → Tasks API: exposes · Task routes are surfaced through the controller
- Tasks module → Tasks service: provides · Task workflow logic lives in the service
- Tasks API → Tasks service: calls · Task requests delegate to business logic
- Tasks service → Task entity: persists · Task CRUD uses the task repository
- Tasks service → Audit service: writes audit · Task lifecycle changes are recorded as audit events
- Audit module → Audit API: exposes · Audit queries are surfaced through the controller
- Audit module → Audit service: provides · Audit persistence and lookup live in the service
- Audit service → Audit entity: persists · Audit records are stored in PostgreSQL
- Enums → Auth module: role policy · Role values drive authorization rules
- Enums → Tasks module: status model · Task status values are shared in task workflows
- Tasks service → Enums: uses · Task status and role-aware rules depend on shared enums
- Seed script → User entity: creates · Seed bootstrap inserts demo users
- Seed script → Task entity: creates · Seed bootstrap inserts sample tasks
- Seed script → Enums: uses · Seed data uses shared role and status values