How darkasfu/nestjs-task-management-backend works
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: app.module.ts App module · auth.module.ts Auth module · tasks.service.ts Tasks service · tasks.module.ts Tasks module
Components 20
Runtime
NestJS app bootstrapping and composition
- main · Starts the NestJS HTTP server
src/main.ts - App module · Wires the application modules together
src/app.module.ts
Features
Domain modules and API surfaces
- Auth module · Login, JWT, and role-based access
src/auth/auth.module.ts - Auth API · Exposes authentication endpoints
src/auth/auth.controller.ts - Auth service · Validates credentials and issues tokens
src/auth/auth.service.ts - Users module · Admin-facing user management
src/users/users.module.ts - Users API · Handles user administration routes
src/users/users.controller.ts - Users service · Reads and manages user records
src/users/users.service.ts - Tasks module · Task CRUD, assignment, and status updates
src/tasks/tasks.module.ts - Tasks API · Exposes task management routes
src/tasks/tasks.controller.ts - Tasks service · Implements task business rules and audit writes
src/tasks/tasks.service.ts - Audit module · Stores and serves task event history
src/audit-logs/audit-logs.module.ts - Audit API · Exposes admin audit-log queries
src/audit-logs/audit-logs.controller.ts - Audit service · Persists and queries audit log records
src/audit-logs/audit-logs.service.ts
Data
Persistence entities and seed flow
- User entity · Persisted user model and auth identity
src/users/entities/user.entity.ts - Task entity · Persisted task model and workflow state
src/tasks/entities/task.entity.ts - Audit entity · Persisted audit event record
src/audit-logs/entities/audit-log.entity.ts - Seed script · Populates demo users and tasks
src/seed.ts
Shared
Cross-cutting enums and auth policy
- JWT strategy · Authenticates requests with JWTs
src/auth/jwt.strategy.ts - Enums · Role and task-status enums shared across modules
src/common/enums
Connections 27
- 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