02 — System Context & Container View

This document describes the system context and container architecture of crewsforge-back, a microservices backend monorepo for a freelancing/project management platform. The focus is on the addition of the Admin Service feature.

---

1. C4 Context Diagram

The context diagram shows the crewsforge-back system as a single black box, its actors, and the external systems it depends on.

graph LR
    Admin["Admin\n(Corporate email user)"]
    Customer["Customer\n(Project owner)"]
    Employee["Employee\n(Freelancer)"]

    System["crewsforge-back\n(Backend Platform)"]

    PostgreSQL[("PostgreSQL\n(Primary Database)")]
    Redis[("Redis\n(Cache / Code Store)")]
    SMTP["SMTP Server\n(Email Delivery)"]

    Admin -- "HTTPS/REST\n/api/v1/admin/*" --> System
    Customer -- "HTTPS/REST\n/api/v1/*" --> System
    Employee -- "HTTPS/REST\n/api/v1/*" --> System

    System -- "TCP/5432\nPrisma ORM" --> PostgreSQL
    System -- "TCP/6379\nioredis" --> Redis
    System -- "SMTP/TLS\nNodemailer" --> SMTP

Actor Descriptions

Actor	Description
Admin	Authenticated via corporate email domain + verification code (passwordless). Manages all projects and users.
Customer	Registers with email/password. Creates and manages own projects.
Employee	Registers with email/password. Works on assigned projects.

External System Descriptions

System	Purpose
PostgreSQL	Primary relational database. All persistent data (users, projects, roles, sessions, tokens).
Redis	Caching layer and ephemeral storage. Verification codes with TTL, session data.
SMTP	Outbound email delivery. Verification codes for admin passwordless auth, and other transactional emails.
RabbitMQ	Message queue for async processing. Not used by the admin service.

---

2. C4 Container Diagram

The container diagram expands the crewsforge-back system boundary to show the individual NestJS applications and their interactions with each other and external systems.

graph LR
    Admin["Admin"]
    Customer["Customer"]
    Employee["Employee"]

    subgraph crewsforge-back ["crewsforge-back (NX Monorepo)"]
        auth_api["auth-api\n(NestJS)\nAuthentication Service"]
        user_api["user-api\n(NestJS)\nUser Service"]
        project_api["project-api\n(NestJS)\nProject Service"]
        core_api["core-api\n(NestJS)\nDB Owner / Migrations"]
        ai_agent["ai-agent-service\n(NestJS)\nAI Chat Agent"]
    end

    PostgreSQL[("PostgreSQL")]
    Redis[("Redis")]
    SMTP["SMTP Server"]

    Admin -- "REST /api/v1/admin/auth/*\nRegister, Login, Refresh" --> auth_api
    Admin -- "REST /api/v1/admin/projects/*\nCRUD all projects" --> auth_api
    Admin -- "REST /api/v1/admin/users/*\nList, Block, Unblock" --> auth_api
    Customer -- "REST /api/v1/customer/auth/*" --> auth_api
    Employee -- "REST /api/v1/employee/auth/*" --> auth_api
    Customer -- "REST /api/v1/projects/*" --> project_api
    Customer -- "REST /api/v1/users/*" --> user_api
    Employee -- "REST /api/v1/users/*" --> user_api

    auth_api -- "Prisma ORM" --> PostgreSQL
    user_api -- "Prisma ORM" --> PostgreSQL
    project_api -- "Prisma ORM" --> PostgreSQL
    core_api -- "Prisma Migrate\n(schema owner)" --> PostgreSQL
    ai_agent -- "Prisma ORM" --> PostgreSQL

    auth_api -- "ioredis\nVerification codes (TTL)" --> Redis
    auth_api -- "Nodemailer\nSMTP/TLS" --> SMTP

Notes on Admin Service Placement

The admin auth endpoints (/admin/auth/*) and admin CRUD endpoints (/admin/projects/*, /admin/users/*) are hosted within the auth-api application. This follows the existing pattern where authentication concerns and their related controllers are co-located. A separate admin-api application may be introduced later if the admin surface grows significantly.

Admin endpoints are protected by AdminAccessTokenGuard, which validates JWTs signed with a dedicated secret (JWT_ADMIN_ACCESS_SECRET_KEY), ensuring complete isolation from Customer and Employee tokens.

---

3. Container Descriptions

Container	Technology	Responsibility
auth-api	NestJS 11, Passport, JWT	Authentication for all actor types (Customer, Employee, Admin). Admin passwordless auth via email code. Admin CRUD endpoints for projects and users. Token management (access + refresh). Session handling.
user-api	NestJS 11, Prisma	User, Customer, and Employee CRUD. Profile management.
project-api	NestJS 11, Prisma	Project CRUD for customers. Project status transitions.
core-api	NestJS 11, Prisma	Database schema owner. Prisma schema definitions and migrations. Shared database models.
ai-agent-service	NestJS 11	AI-powered chat agent for platform interactions.
PostgreSQL	PostgreSQL	Primary relational database. Stores users, roles, sessions, tokens, projects, customers, employees.
Redis	Redis 5.9	Ephemeral key-value store. Verification code storage with TTL (900s), resend cooldown enforcement (120s), session caching.
SMTP Server	External SMTP	Outbound email delivery via Nodemailer / @nestjs-modules/mailer. Sends verification codes and transactional emails.

---

4. Communication Protocols

From	To	Protocol / Library	Purpose
Admin	auth-api	HTTPS / REST	Admin authentication (register, login, refresh) and admin CRUD (projects, users)
Customer	auth-api	HTTPS / REST	Customer authentication (register, login, refresh)
Employee	auth-api	HTTPS / REST	Employee authentication (register, login, refresh)
Customer	project-api	HTTPS / REST	Project CRUD (create, read, update own projects)
Customer	user-api	HTTPS / REST	User profile management
Employee	user-api	HTTPS / REST	User profile management
auth-api	PostgreSQL	TCP/5432 / Prisma ORM	Read/write users, roles, sessions, tokens. Admin user creation with ADMIN role.
user-api	PostgreSQL	TCP/5432 / Prisma ORM	Read/write user and profile data
project-api	PostgreSQL	TCP/5432 / Prisma ORM	Read/write project data
core-api	PostgreSQL	TCP/5432 / Prisma Migrate	Schema migrations, database structure ownership
ai-agent-service	PostgreSQL	TCP/5432 / Prisma ORM	Read data for AI agent context
auth-api	Redis	TCP/6379 / ioredis	Store/retrieve verification codes (TTL 900s), enforce resend cooldown (TTL 120s)
auth-api	SMTP	SMTP/TLS / Nodemailer	Send verification code emails for admin passwordless auth, and other transactional emails

---

5. Key Architectural Decisions for Admin Service

1. Passwordless authentication — Admin users authenticate exclusively via corporate email domain verification + one-time code. No passwords are stored (passwordHash/passwordSalt are nullable).

2. Separate JWT secret — Admin tokens are signed with JWT_ADMIN_ACCESS_SECRET_KEY, completely isolated from Customer/Employee token chains. This ensures a Customer or Employee token can never grant admin access.

3. Shared infrastructure — The admin service reuses existing mechanisms: Redis-based verification codes, EmailSenderService, Prisma ORM, pagination helpers, and the Passport strategy pattern.

4. Domain-restricted registration — Only email addresses matching domains in ADMIN_ALLOWED_DOMAINS (env variable) can register as admin users.

5. No RabbitMQ dependency — The admin service communicates synchronously via REST and direct database access. RabbitMQ is not involved.