Software Architecture Document (SAD) - andrefelizardo/kamana GitHub Wiki

Software Architecture Document (SAD)

1. Introduction This document outlines the architecture of the Project & Task Management Backend System, detailing structural decisions, modules, interactions, and selected technologies. The system is designed to support a collaborative task workflow using a RESTful API, secure authentication, and a modular, scalable architecture.

2. Architectural Overview

  • Style: Modular monolith (designed with modular boundaries, but deployed as a single service)
  • Backend Framework: NestJS (Node.js + TypeScript)
  • API Type: RESTful
  • ORM: MikroORM
  • Authentication: JWT (stateless)
  • Database: PostgreSQL
  • Validation: class-validator + class-transformer

3. System Context The backend exposes APIs to be consumed by a frontend (e.g., web app, mobile app). External systems include:

  • End-user client (frontend)
  • Optional: External email or notification service (for future alerts)

4. Containers and Modules

  • App Module: Root application module
  • Auth Module: Handles JWT login, token generation, guards
  • Users Module: Handles user registration, profile, roles, password hashing
  • Projects Module: Manages project creation, membership, permissions
  • Tasks Module: Manages tasks within projects, assignment, status
  • Comments Module: Adds, retrieves, edits, deletes task comments

Each module will contain:

  • Controller: Handles routing and input
  • Service: Contains business logic
  • Repository (via MikroORM): Handles DB access
  • DTOs: Input/output schema with validation rules

5. Key Use Case Flows

  • Login Flow: User logs in → AuthService validates → JWT issued → used in subsequent requests
  • Task Creation: Authenticated user (project member) creates a task → Validated → TaskService stores it → response with created task
  • Role-Based Access: Guards check if user is project member/owner/admin before allowing actions

6. Technologies Chosen and Rationale

  • NestJS: Provides modular structure, DI, testing, and decorators consistent with Angular
  • MikroORM: Supports SQL databases, entities as classes, unit-of-work, migrations, and deep integration with NestJS
  • JWT: Stateless auth compatible with scalable APIs
  • PostgreSQL: Relational schema fits well with tasks, projects, users, relationships
  • class-validator/transformer: Enforces clean inputs and proper DTO typing

7. Diagrams

  • (To be added later):

    • System Context Diagram (C4 Level 1)
    • Container Diagram (C4 Level 2)
    • Sample Sequence Diagram (e.g., Create Task)

8. Code Structure & Naming

src/
├── auth/
├── users/
├── projects/
├── tasks/
├── comments/
├── common/
│   ├── guards/
│   ├── interceptors/
│   ├── decorators/
│   └── pipes/
├── database/
├── main.ts

9. Constraints

  • Project must use TypeScript and follow NestJS module conventions
  • Environment configs must be injected via ConfigModule
  • All endpoints must be authenticated unless explicitly marked as public

10. Future Considerations

  • Switch to microservices (if needed) with messaging (e.g., Redis pub/sub)
  • Add email/notification service
  • Add file upload support (e.g., for task attachments)

11. References