# shubratha/organization_management architecture

> Architecture diagram of the GitHub repository shubratha/organization_management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubratha/organization_management
- Repository: https://github.com/shubratha/organization_management

## Overview

##### Project type and purpose
- This is a single microservice (“Organization Management Service”) built with FastAPI.
- It manages multi‐tenant organizations by creating and isolating per‐tenant PostgreSQL databases, handles authentication/authorization (JWT + role‐based access), and exposes RESTful endpoints.

##### File structure
- Top-level:
- Dockerfile, docker-compose.yml → containerized deployment
- alembic/ + alembic.ini → database migrations
- app/ → FastAPI application code
- tests/ → Pytest suite
- Under app/:
- core/ → application config, middleware, health checks, logging, security
- database/ → SQLAlchemy base, session management, DAO utilities
- auth/ → authentication router, schemas, services, DAO, models
- organization/ → organization router, schemas, services, DAO, models
- main.py → application entrypoint
- Configuration:
- requirements.txt/in → Python dependencies
- .env (via README instructions) → runtime configuration

##### README for additional insights
- Tech stack: FastAPI, PostgreSQL + SQLAlchemy, JWT, Docker, Pytest, OpenAPI
- Features: dynamic database provisioning, role‐based access, async REST API

##### Main components & their relationships
a. External Clients
- Super Admin UI/CLI
- Organization Admin UI/CLI
- (Could also be other services consuming the API)
b. API Layer (FastAPI container)
- Routers: /org/*, /admin/*, /auth/*
- Middleware & security: JWT validation, CORS, logging
- Health Endpoint: /health
c. Business Logic Layer
- auth.services → user lookup, token generation
- organization.services → org creation, dynamic DB provisioning
d. Data Access Layer
- dao.py modules → low-level CRUD against SQLAlchemy models
- SQLAlchemy session management (session.py)
e. Persistence
- Central PostgreSQL database (“central_org”) for superadmins & org metadata
- Dynamically created tenant PostgreSQL databases for each org
- Alembic migrations for schema versioning
f. Infrastructure
- Docker container for the service
- Docker Compose orchestrating service and PostgreSQL
- Logging & configuration via core modules

##### Architectural patterns & design principles
- Layered (Router → Service → DAO → Database)
- Dependency Injection via FastAPI’s dependencies (app/auth/dependencies.py)
- Single‐responsibility & modular structure (auth vs organization)
- Dynamic provisioning: service triggers separate DB creation API/CLI
- Async I/O for high throughput

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        C1["Super Admin UI/CLI"]:::external
        C2["Organization Admin UI/CLI"]:::external
        C3["Other Services"]:::external
    end

    subgraph "API Layer"
        Entrypoint["main.py"]:::fastapi
        Middleware["core/middleware.py"]:::fastapi
        Security["core/security.py"]:::fastapi
        Logging["core/logging.py"]:::fastapi
        Config["core/config.py"]:::fastapi
        Health["core/health.py"]:::fastapi
        AuthRouter["auth/router.py"]:::fastapi
        OrgRouter["organization/router.py"]:::fastapi
    end

    subgraph "Business Logic"
        AuthService["auth/services.py"]:::fastapi
        OrgService["organization/services.py"]:::fastapi
    end

    subgraph "Data Access Layer"
        AuthDAO["auth/dao.py"]:::fastapi
        OrgDAO["organization/dao.py"]:::fastapi
        SharedDAO["database/dao.py"]:::fastapi
        Session["database/session.py"]:::fastapi
        Base["database/base.py"]:::fastapi
    end

    subgraph "Databases"
        CentralDB["Central PostgreSQL"]:::db
        TenantDB["Tenant DB (per org)"]:::db
    end

    subgraph "Migrations"
        AlembicIni["alembic.ini"]:::infra
        AlembicEnv["alembic/env.py"]:::infra
        V1["versions/2025_08_02_1227-455ec55f6bb8_added_org_table.py"]:::infra
        V2["versions/2025_08_02_1508-6b521aaa0a94_added_superadmin_table.py"]:::infra
    end

    subgraph "Infrastructure"
        Dockerfile["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
    end

    C1-->|"HTTP"|Entrypoint
    C2-->|"HTTP"|Entrypoint
    C3-->|"HTTP"|Entrypoint

    Entrypoint-->Middleware
    Middleware-->Security
    Middleware-->Logging
    Entrypoint-->Config
    Entrypoint-->AuthRouter
    Entrypoint-->OrgRouter
    Entrypoint-->Health

    AuthRouter-->AuthService
    OrgRouter-->OrgService

    AuthService-->AuthDAO
    OrgService-->OrgDAO
    OrgService-->|"provision"|TenantDB

    AuthDAO-->SharedDAO
    OrgDAO-->SharedDAO
    SharedDAO-->Session
    Session-->Base
    Base-->CentralDB

    AlembicIni-->AlembicEnv
    AlembicEnv-->V1
    AlembicEnv-->V2
    V1-->CentralDB
    V2-->CentralDB

    Compose-->Dockerfile
    Compose-->Entrypoint
    Compose-->CentralDB
    Compose-->TenantDB

    click Entrypoint "https://github.com/shubratha/organization_management/blob/main/app/main.py"
    click Middleware "https://github.com/shubratha/organization_management/blob/main/app/core/middleware.py"
    click Security "https://github.com/shubratha/organization_management/blob/main/app/core/security.py"
    click Logging "https://github.com/shubratha/organization_management/blob/main/app/core/logging.py"
    click Config "https://github.com/shubratha/organization_management/blob/main/app/core/config.py"
    click Health "https://github.com/shubratha/organization_management/blob/main/app/core/health.py"
    click AuthRouter "https://github.com/shubratha/organization_management/blob/main/app/auth/router.py"
    click OrgRouter "https://github.com/shubratha/organization_management/blob/main/app/organization/router.py"
    click AuthService "https://github.com/shubratha/organization_management/blob/main/app/auth/services.py"
    click OrgService "https://github.com/shubratha/organization_management/blob/main/app/organization/services.py"
    click AuthDAO "https://github.com/shubratha/organization_management/blob/main/app/auth/dao.py"
    click OrgDAO "https://github.com/shubratha/organization_management/blob/main/app/organization/dao.py"
    click SharedDAO "https://github.com/shubratha/organization_management/blob/main/app/database/dao.py"
    click Session "https://github.com/shubratha/organization_management/blob/main/app/database/session.py"
    click Base "https://github.com/shubratha/organization_management/blob/main/app/database/base.py"
    click AlembicIni "https://github.com/shubratha/organization_management/blob/main/alembic.ini"
    click AlembicEnv "https://github.com/shubratha/organization_management/blob/main/alembic/env.py"
    click V1 "https://github.com/shubratha/organization_management/blob/main/alembic/versions/2025_08_02_1227-455ec55f6bb8_added_org_table.py"
    click V2 "https://github.com/shubratha/organization_management/blob/main/alembic/versions/2025_08_02_1508-6b521aaa0a94_added_superadmin_table.py"
    click Dockerfile "https://github.com/shubratha/organization_management/tree/main/Dockerfile"
    click Compose "https://github.com/shubratha/organization_management/blob/main/docker-compose.yml"

    classDef fastapi fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infra fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
