# rasikjain/multi-tenant-org-team-roles-app architecture

> Architecture diagram of the GitHub repository rasikjain/multi-tenant-org-team-roles-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rasikjain/multi-tenant-org-team-roles-app
- Repository: https://github.com/rasikjain/multi-tenant-org-team-roles-app

## Overview

##### Project type and purpose
- This is a backend API service (Node.js + TypeScript + Express) that provides a multi-tenant foundation for organizations, teams, role-based access control (RBAC), invites, and auditing. It exposes REST endpoints, stores data in Postgres via Drizzle ORM, and ships with OpenAPI/Swagger UI and a Postman collection for integration.

##### File structure
- Top-level:
- src/ – main application code
- scripts/ – DB seeding scripts
- drizzle/ – raw SQL migrations & metadata
- config files: .env.sample, drizzle.config.ts, tsconfig.json, vitest.config.ts
- src/ layers:
- src/server.ts – Express app setup and route mounting
- src/middleware/ – audit and auth middleware with tests
- src/auth/ – RBAC logic and tests
- src/routes/ – route handlers for orgs, teams, members, invites
- src/db/ – Drizzle client initialization and schema definitions
- src/utils/ and src/types/ – shared utilities and error types

##### README insights
- Multi-tenant boundary enforcement (org scope derived from route param and x-user-id header)
- Core domain: Orgs, Teams, Users, Memberships, Invites, Roles, Audit events
- Deployment/migration steps: drizzle:generate, drizzle:push, seed
- Testing with Vitest and coverage

a. Main components to include
- API Layer (Express server)
- Middleware Pipeline (Authentication → RBAC → Auditing)
- Route/Controller Modules (Orgs, Teams, Invites, Members)
- Service/Domain Layer (business logic, permission checks)
- Data Access Layer (Drizzle ORM client)
- Postgres Database (tables for orgs, teams, users, memberships, invites, audit logs)
- External Email Service (SMTP or 3rd-party) for invite delivery
- Documentation UI (Swagger UI serving docs/openapi.yaml)
- Clients/Consumers (CLI, Postman, frontend apps)

b. Relationships and interactions
- Client → HTTP → Express API
- API → middleware for auth & audit
- Route handlers invoke service methods → Drizzle client → Postgres
- On POST /invites: generate token → persist invite → email service call
- On invite acceptance: validate token → upsert user/memberships
- Swagger UI endpoint reads docs/openapi.yaml

c. Architectural patterns & principles
- Layered architecture: Presentation (Express/routes) → Middleware → Business logic → Data access
- Separation of concerns: auth, RBAC, auditing in middleware; domain logic in route modules
- Multi-tenant isolation: orgId scoping at middleware layer
- Idempotency and audit logging for mutating endpoints
- Migration-driven schema definition (Drizzle)

d. Key technologies/frameworks
- Node.js, TypeScript, Express
- Drizzle ORM + Postgres
- Vitest for testing
- Swagger/OpenAPI, Postman

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients/Consumers"
        Clients["Clients (CLI, Postman, Frontend)"]:::external
    end

    subgraph "API Layer"
        API["Express Server"]:::api
    end

    subgraph "Middleware Pipeline"
        AuthMid["Auth Middleware"]:::middleware
        RBAC["RBAC Logic"]:::middleware
        Audit["Audit Middleware"]:::middleware
    end

    subgraph "Route Handlers"
        OrgsR["Organizations Route Handler"]:::api
        TeamsR["Teams Route Handler"]:::api
        MemR["Members Route Handler"]:::api
        InvR["Invites Route Handler"]:::api
    end

    subgraph "Data Access Layer"
        DrizzleC["Drizzle Client"]:::data
        Schema["Schema Definitions"]:::data
    end

    subgraph "Database"
        Postgres[(Postgres DB)]:::db
    end

    subgraph "External Services"
        Email["Email Service"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    subgraph "Documentation & Tools"
        OpenAPI["OpenAPI Spec"]:::docs
        Postman["Postman Collection"]:::docs
        ERD["ER Diagram"]:::docs
    end

    subgraph "Infrastructure & Scripts"
        Migrations["Migrations & Metadata"]:::infra
        DrizzleCfg["Migration Config"]:::infra
        Seed["Seed Scripts"]:::infra
    end

    Clients -->|HTTP Requests| API
    API -->|uses| AuthMid
    AuthMid -->|enforces scope| RBAC
    RBAC -->|auditable actions| Audit
    Audit -->|routes request| OrgsR
    Audit -->|routes request| TeamsR
    Audit -->|routes request| MemR
    Audit -->|routes request| InvR

    OrgsR -->|queries/inserts| DrizzleC
    TeamsR -->|queries/inserts| DrizzleC
    MemR -->|queries/inserts| DrizzleC
    InvR -->|queries/inserts| DrizzleC
    InvR -->|send invite| Email

    DrizzleC -->|loads schema| Schema
    DrizzleC -->|executes SQL| Postgres

    API -->|serves| SwaggerUI
    SwaggerUI -->|reads| OpenAPI

    Migrations -->|define schema| Postgres
    DrizzleCfg -->|configures| Migrations
    Seed -->|populates| Postgres

    classDef api fill:#cce5ff,stroke:#004085,color:#004085;
    classDef middleware fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404;
    classDef db fill:#ffe5b4,stroke:#e69500,color:#e69500;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef docs fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef infra fill:#f0f0f0,stroke:#999,color:#666;

    click API "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/server.ts"
    click AuthMid "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/middleware/auth.ts"
    click Audit "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/middleware/audit.ts"
    click RBAC "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/auth/rbac.ts"
    click OrgsR "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/routes/orgs.ts"
    click TeamsR "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/routes/teams.ts"
    click MemR "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/routes/members.ts"
    click InvR "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/routes/invites.ts"
    click DrizzleC "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/db/client.ts"
    click Schema "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/db/schema.ts"
    click Migrations "https://github.com/rasikjain/multi-tenant-org-team-roles-app/tree/master/drizzle/"
    click DrizzleCfg "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/drizzle.config.ts"
    click Seed "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/scripts/seed.ts"
    click OpenAPI "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/docs/openapi.yaml"
    click Postman "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/docs/postman_collection.json"
    click ERD "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/docs/erd.mmd"
    click Errors "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/types/errors.ts"
    click DBErrUtil "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/utils/dbErrors.ts"
    click AuthTest "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/middleware/auth.test.ts"
    click RBACTest "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/auth/rbac.test.ts"
    click DBErrTest "https://github.com/rasikjain/multi-tenant-org-team-roles-app/blob/master/src/utils/dbErrors.test.ts"
```
