# md-zihad/multi-tenant-organization-workspace architecture

> Architecture diagram of the GitHub repository md-zihad/multi-tenant-organization-workspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/md-zihad/multi-tenant-organization-workspace
- Repository: https://github.com/md-zihad/multi-tenant-organization-workspace

## Overview

1. **What this repository is**
   - A TypeScript/Node.js REST API built on Express 5 with a PostgreSQL primary datastore.
   - The application is organized as a multi-tenant workspace backend: organizations contain users, projects, and tasks, with authorization scoped by organization.

2. **Runtime and bootstrap path**
   - `src/server.ts` is the process entry point.
   - `src/app.ts` configures the Express application.
   - `src/route.ts` aggregates module routes into the final API surface.
   - `src/config/env.ts` and `src/config/db.ts` centralize runtime configuration and TypeORM database initialization.

3. **Domain/module boundaries**
   - The main business domains are split into feature modules under `src/module/`: `auth`, `organization`, `project`, `task`, and `user`.
   - Each module follows the same layered pattern: controller → service → repository, with DTOs for request/response shaping and entities for persistence.
   - This is a classic application-layer boundary: HTTP concerns stay in controllers, business rules in services, and SQL/ORM access in repositories.

4. **Core data model**
   - The architecture revolves around four main persisted entities:
     - `Organization`
     - `User`
     - `Project`
     - `Task`
   - The key relationship boundary is `organizationId`, which scopes users, projects, and tasks to a tenant.
   - Tasks belong to projects and can be assigned to users; projects belong to organizations; users also belong to an organization.

5. **Multi-tenancy and authorization**
   - Multi-tenancy is implemented at the application layer rather than separate databases.
   - The auth layer issues JWTs that carry user identity, role, and `organizationId`.
   - `src/middleware/auth.middleware.ts` and the custom Express request typing in `src/types/express.d.ts` provide request-context injection so downstream handlers can enforce tenant and role checks consistently.
   - The roles are primarily `ORG_ADMIN` and `MEMBER`, with access decisions enforced in services and middleware.

6. **Request processing pipeline**
   - Incoming requests go through cross-cutting middleware first: security headers, CORS/body parsing as part of app setup, authentication, rate limiting, and centralized error handling.
   - After middleware, the request enters a module controller, then service logic, then repository/database access.
   - This makes the system easy to diagram as a layered pipeline with clear separation between transport, policy, business logic, and persistence.

7. **Security subsystem**
   - Authentication is JWT-based, with password hashing utilities in `src/utils/password.ts` and token helpers in `src/utils/jwt.ts`.
   - `src/middleware/ratelimit.middleware.ts` protects public endpoints and login flows.
   - `src/middleware/errorHandler.middleware.ts` centralizes API error responses and logging.
   - Security boundaries are reinforced by tenant-scoped queries and role checks, not by trusting client-supplied organization identifiers.

8. **Persistence layer**
   - TypeORM is the data-access foundation, with entity files under each domain module and a shared database config in `src/config/db.ts`.
   - The repository layer is explicit per domain, which keeps query logic isolated from controllers and service orchestration.
   - The README indicates migrations are expected, so schema management is part of the persistence boundary rather than implicit sync-only behavior.

9. **Operational endpoints and observability**
   - Health and readiness logic lives in `src/utils/health.ts`.
   - Metrics are exposed via `src/utils/metrics.ts`, with Prometheus as the collection system and Grafana for visualization in the monitoring compose setup.
   - Logging is handled by `src/utils/logger.ts`, likely via Winston as described in the README.
   - These are separate operational subsystems, not part of business logic, and are meant to support deployment health and production debugging.

10. **Infrastructure and deployment shape**
    - The repo includes Docker artifacts for dev and production, plus an Nginx reverse proxy config.
    - `docker/docker-compose*.yml` defines local multi-container deployment, while `docker/Dockerfile*` supports image builds.
    - Terraform under `terraform/` targets AWS ECS-based deployment, with supporting infrastructure for secrets and service configuration.
    - This means the app is designed to run both locally in containers and in cloud-managed containers, with the same API process packaged for both.

11. **Testing boundary**
    - Unit tests are concentrated on pure utility behavior such as password hashing.
    - Integration tests exercise API flows, especially auth, against a real database-backed application stack.
    - `tests/setup.ts` provides shared Jest test configuration, reinforcing the split between fast isolated tests and end-to-end request/database verification.

12. **How to diagram the system**
    - Draw the system as: clients → Nginx / API entrypoint → Express middleware stack → module controllers/services → TypeORM repositories → PostgreSQL.
    - Add side channels for auth/JWT, health and metrics endpoints, and logging.
    - Around the application, show Docker as the packaging/runtime layer, Prometheus/Grafana as observability consumers, and Terraform/ECS as the cloud deployment path.

Main entry points: [`src/app.ts`](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/app.ts) (App), [`src/route.ts`](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/route.ts) (Routes), [`src/middleware/auth.middleware.ts`](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/auth.middleware.ts) (Auth MW), [`src/module/user/user.controller.ts`](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/user/user.controller.ts) (User)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server(("Server<br/>entrypoint<br/>[server.ts]"))
  node_app["App<br/>[app.ts]"]
  node_routes["Routes<br/>route aggregator<br/>[route.ts]"]
  node_env["Config Env<br/>runtime config<br/>[env.ts]"]
  node_db[("TypeORM DB<br/>database config<br/>[db.ts]")]
  node_authmw["Auth MW<br/>middleware<br/>[auth.middleware.ts]"]
  node_ratelimit["Rate Limit<br/>middleware"]
  node_errorhandler["Error Handler<br/>middleware"]
end

subgraph group_domain["Domain"]
  node_authmod["Auth<br/>feature module<br/>[auth.controller.ts]"]
  node_orgmod["Organization<br/>feature module"]
  node_projectmod["Project<br/>feature module"]
  node_taskmod["Task<br/>feature module<br/>[task.controller.ts]"]
  node_usermod["User<br/>feature module<br/>[user.controller.ts]"]
  node_orgentity[("Organization Entity<br/>typeorm entity")]
  node_userentity[("User Entity<br/>typeorm entity<br/>[User.entity.ts]")]
  node_projectentity[("Project Entity<br/>typeorm entity<br/>[Project.entity.ts]")]
  node_taskentity[("Task Entity<br/>typeorm entity<br/>[Task.entity.ts]")]
end

subgraph group_ops["Operations"]
  node_health(("Health<br/>ops util<br/>[health.ts]"))
  node_metrics(("Metrics<br/>ops util<br/>[metrics.ts]"))
  node_logger(("Logger<br/>ops util<br/>[logger.ts]"))
  node_promgraf["Prometheus/Grafana<br/>monitoring stack"]
end

subgraph group_deploy["Deploy"]
  node_docker{{"Docker<br/>runtime packaging<br/>[docker-compose.yml]"}}
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_terraform["Terraform<br/>infra code<br/>[main.tf]"]
end

node_server -->|"starts"| node_app
node_app -->|"loads"| node_env
node_app -->|"initializes"| node_db
node_app -->|"mounts"| node_routes
node_app -->|"uses"| node_authmw
node_app -->|"uses"| node_ratelimit
node_app -->|"uses"| node_errorhandler
node_routes -->|"includes"| node_authmod
node_routes -->|"includes"| node_orgmod
node_routes -->|"includes"| node_projectmod
node_routes -->|"includes"| node_taskmod
node_routes -->|"includes"| node_usermod
node_authmod -->|"issues context"| node_authmw
node_authmod -->|"authenticates"| node_usermod
node_orgmod -->|"persists"| node_orgentity
node_usermod -->|"persists"| node_userentity
node_projectmod -->|"persists"| node_projectentity
node_taskmod -->|"persists"| node_taskentity
node_taskmod -->|"belongs to"| node_projectmod
node_taskmod -->|"assigns to"| node_usermod
node_projectmod -->|"scoped by"| node_orgmod
node_usermod -->|"scoped by"| node_orgmod
node_authmw -->|"enforces"| node_orgmod
node_authmw -->|"enforces"| node_projectmod
node_authmw -->|"enforces"| node_taskmod
node_authmw -->|"enforces"| node_usermod
node_health -->|"served by"| node_app
node_metrics -->|"served by"| node_app
node_logger -->|"feeds"| node_errorhandler
node_docker -->|"packages"| node_app
node_nginx -->|"proxies to"| node_app
node_terraform -->|"deploys"| node_docker
node_promgraf -->|"scrapes"| node_metrics

click node_server "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/server.ts"
click node_app "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/app.ts"
click node_routes "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/route.ts"
click node_env "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/config/env.ts"
click node_db "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/config/db.ts"
click node_authmw "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/auth.middleware.ts"
click node_ratelimit "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/ratelimit.middleware.ts"
click node_errorhandler "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/errorHandler.middleware.ts"
click node_authmod "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/auth/auth.controller.ts"
click node_orgmod "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/organization/organization.controller.ts"
click node_projectmod "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/project/project.controller.ts"
click node_taskmod "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/task/task.controller.ts"
click node_usermod "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/user/user.controller.ts"
click node_orgentity "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/organization/Organization.entity.ts"
click node_userentity "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/user/User.entity.ts"
click node_projectentity "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/project/Project.entity.ts"
click node_taskentity "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/task/Task.entity.ts"
click node_health "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/health.ts"
click node_metrics "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/metrics.ts"
click node_logger "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/logger.ts"
click node_docker "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/docker/docker-compose.yml"
click node_nginx "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/docker/nginx.conf"
click node_terraform "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/terraform/main.tf"
click node_promgraf "https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/monitoring/docker-compose.monitoring.yml"

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_server,node_app,node_routes,node_env,node_db,node_authmw,node_ratelimit,node_errorhandler toneBlue
class node_authmod,node_orgmod,node_projectmod,node_taskmod,node_usermod,node_orgentity,node_userentity,node_projectentity,node_taskentity toneAmber
class node_health,node_metrics,node_logger,node_promgraf toneMint
class node_docker,node_nginx,node_terraform toneRose
```

## Components

### Runtime

Process bootstrap and HTTP pipeline

- [Server](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/server.ts): entrypoint · Process entrypoint · `src/server.ts`
- [App](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/app.ts): express app · Express application setup · `src/app.ts`
- [Routes](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/route.ts): route aggregator · Mounts module routes · `src/route.ts`
- [Config Env](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/config/env.ts): runtime config · Environment and settings · `src/config/env.ts`
- [TypeORM DB](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/config/db.ts): database config · Database initialization · `src/config/db.ts`
- [Auth MW](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/auth.middleware.ts): middleware · JWT auth and tenant context · `src/middleware/auth.middleware.ts`
- [Rate Limit](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/ratelimit.middleware.ts): middleware · Public endpoint protection · `src/middleware/ratelimit.middleware.ts`
- [Error Handler](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/middleware/errorHandler.middleware.ts): middleware · Central API error responses · `src/middleware/errorHandler.middleware.ts`

### Domain

Feature modules and persistence

- [Auth](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/auth/auth.controller.ts): feature module · Login and token issuance · `src/module/auth/auth.controller.ts`
- [Organization](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/organization/organization.controller.ts): feature module · Tenant and membership management · `src/module/organization/organization.controller.ts`
- [Project](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/project/project.controller.ts): feature module · Organization-scoped projects · `src/module/project/project.controller.ts`
- [Task](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/task/task.controller.ts): feature module · Project tasks and assignment · `src/module/task/task.controller.ts`
- [User](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/user/user.controller.ts): feature module · Organization users and profiles · `src/module/user/user.controller.ts`
- [Organization Entity](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/organization/Organization.entity.ts): typeorm entity · Tenant persistence model · `src/module/organization/Organization.entity.ts`
- [User Entity](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/user/User.entity.ts): typeorm entity · User persistence model · `src/module/user/User.entity.ts`
- [Project Entity](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/project/Project.entity.ts): typeorm entity · Project persistence model · `src/module/project/Project.entity.ts`
- [Task Entity](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/module/task/Task.entity.ts): typeorm entity · Task persistence model · `src/module/task/Task.entity.ts`

### Operations

Health, metrics, and logging

- [Health](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/health.ts): ops util · Readiness and liveness checks · `src/utils/health.ts`
- [Metrics](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/metrics.ts): ops util · Prometheus metrics exposure · `src/utils/metrics.ts`
- [Logger](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/src/utils/logger.ts): ops util · Application logging · `src/utils/logger.ts`
- [Prometheus/Grafana](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/monitoring/docker-compose.monitoring.yml): monitoring stack · Metrics collection and visualization · `monitoring/docker-compose.monitoring.yml`

### Deploy

Container and cloud packaging

- [Docker](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/docker/docker-compose.yml): runtime packaging · Local and production containers · `docker/docker-compose.yml`
- [Nginx](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/docker/nginx.conf): reverse proxy · Front proxy configuration · `docker/nginx.conf`
- [Terraform](https://github.com/md-zihad/multi-tenant-organization-workspace/blob/dev/terraform/main.tf): infra code · AWS ECS deployment · `terraform/main.tf`

## Connections

- Server → App: starts · Bootstraps the Express process
- App → Config Env: loads · Reads runtime configuration
- App → TypeORM DB: initializes · Creates database connectivity
- App → Routes: mounts · Registers API surface
- App → Auth MW: uses · Applies request authentication
- App → Rate Limit: uses · Applies throttling
- App → Error Handler: uses · Handles failures centrally
- Routes → Auth: includes · Exposes auth endpoints
- Routes → Organization: includes · Exposes organization endpoints
- Routes → Project: includes · Exposes project endpoints
- Routes → Task: includes · Exposes task endpoints
- Routes → User: includes · Exposes user endpoints
- Auth → Auth MW: issues context · JWT identity and tenant claims
- Auth → User: authenticates · Login is user-backed
- Organization → Organization Entity: persists · Organization storage
- User → User Entity: persists · User storage
- Project → Project Entity: persists · Project storage
- Task → Task Entity: persists · Task storage
- Task → Project: belongs to · Tasks are scoped to projects
- Task → User: assigns to · Tasks can be assigned to users
- Project → Organization: scoped by · Projects belong to organizations
- User → Organization: scoped by · Users belong to organizations
- Auth MW → Organization: enforces · Tenant and role checks
- Auth MW → Project: enforces · Tenant and role checks
- Auth MW → Task: enforces · Tenant and role checks
- Auth MW → User: enforces · Tenant and role checks
- Health → App: served by · Operational endpoint
- Metrics → App: served by · Metrics endpoint
- Logger → Error Handler: feeds · Structured error logging
- Docker → App: packages · Builds the API runtime
- Nginx → App: proxies to · Routes external traffic to API
- Terraform → Docker: deploys · Cloud deployment uses container images
- Prometheus/Grafana → Metrics: scrapes · Collects and visualizes metrics