How md-zihad/multi-tenant-organization-workspace works
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: app.ts App · route.ts Routes · auth.middleware.ts Auth MW · user.controller.ts User
Components 24
Runtime
Process bootstrap and HTTP pipeline
- Server · Process entrypoint
src/server.ts - App · Express application setup
src/app.ts - Routes · Mounts module routes
src/route.ts - Config Env · Environment and settings
src/config/env.ts - TypeORM DB · Database initialization
src/config/db.ts - Auth MW · JWT auth and tenant context
src/middleware/auth.middleware.ts - Rate Limit · Public endpoint protection
src/middleware/ratelimit.middleware.ts - Error Handler · Central API error responses
src/middleware/errorHandler.middleware.ts
Domain
Feature modules and persistence
- Auth · Login and token issuance
src/module/auth/auth.controller.ts - Organization · Tenant and membership management
src/module/organization/organization.controller.ts - Project · Organization-scoped projects
src/module/project/project.controller.ts - Task · Project tasks and assignment
src/module/task/task.controller.ts - User · Organization users and profiles
src/module/user/user.controller.ts - Organization Entity · Tenant persistence model
src/module/organization/Organization.entity.ts - User Entity · User persistence model
src/module/user/User.entity.ts - Project Entity · Project persistence model
src/module/project/Project.entity.ts - Task Entity · Task persistence model
src/module/task/Task.entity.ts
Operations
Health, metrics, and logging
- Health · Readiness and liveness checks
src/utils/health.ts - Metrics · Prometheus metrics exposure
src/utils/metrics.ts - Logger · Application logging
src/utils/logger.ts - Prometheus/Grafana · Metrics collection and visualization
monitoring/docker-compose.monitoring.yml
Connections 33
- 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