# harshilmaks/tenancy-service architecture

> Architecture diagram of the GitHub repository harshilmaks/tenancy-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshilmaks/tenancy-service
- Repository: https://github.com/harshilmaks/tenancy-service

## Overview

Tenancy Service is a FastAPI multi-tenant organization management API. The principal workflow accepts a tenant request, validates and maps it at the API boundary, invokes a use case, applies domain rules, persists through the repository, and returns a response. Separate capabilities cover lifecycle and policy operations, onboarding and compliance, edition-based features, billing, and operational observability. The README documents the overall architecture; sampled routes and the source index confirm selected calls. Other unsampled subsystem links are omitted where their wiring is not shown.

Main entry points: [`infrastructure/persistence/tenant_repository.py`](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/persistence/tenant_repository.py) (Tenant repository), [`app/business/use_cases`](https://github.com/harshilmaks/tenancy-service/tree/main/app/business/use_cases) (Tenant use cases), [`app/main.py`](https://github.com/harshilmaks/tenancy-service/blob/main/app/main.py) (FastAPI application), [`app/api/tenants/routes.py`](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/tenants/routes.py) (Tenant routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["FastAPI application<br/>[main.py]"]
  node_tenant_api["Tenant routes<br/>[routes.py]"]
  node_schemas["Request schemas"]
  node_providers["Dependency providers<br/>[providers.py]"]
end

subgraph group_business["Tenant business"]
  node_usecases["Tenant use cases"]
  node_lifecycle["Lifecycle rules<br/>[lifecycle.py]"]
  node_policies["Policy rules<br/>[policies.py]"]
  node_events["Domain events<br/>[tenant_events.py]"]
  node_domain["Organization model<br/>[domain_models.py]"]
end

subgraph group_platform["Tenant capabilities"]
  node_feature_api["Feature gating API<br/>[routes.py]"]
  node_onboarding["Onboarding workflow<br/>[routes.py]"]
  node_compliance["Compliance API<br/>[routes.py]"]
  node_retention["Retention API<br/>[routes.py]"]
  node_cancellations["Cancellation workflow<br/>[routes.py]"]
  node_billing["Billing integration<br/>[billing_service.py]"]
end

subgraph group_storage["Persistence"]
  node_repository["Tenant repository"]
  node_database[("Relational database")]
end

subgraph group_operations["Operations"]
  node_health["Health monitoring<br/>[health.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_metrics["Metrics collection<br/>[metrics.py]"]
  node_tracing["Distributed tracing<br/>[tracing.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_tenant_api
node_tenant_api -->|"validates requests"| node_schemas
node_tenant_api -->|"resolves dependencies"| node_providers
node_providers -->|"builds use cases"| node_usecases
node_tenant_api -->|"executes"| node_usecases
node_usecases -->|"checks transitions"| node_lifecycle
node_usecases -->|"publishes events"| node_events
node_usecases -->|"persists tenants"| node_repository
node_repository -->|"maps models"| node_domain
node_repository -->|"reads and writes"| node_database
node_usecases -->|"evaluates policies"| node_policies
node_feature_api -->|"loads tenant"| node_repository
node_onboarding -->|"saves progress"| node_repository
node_compliance -->|"loads tenant"| node_repository
node_retention -->|"updates retention"| node_repository
node_cancellations -->|"updates status"| node_repository
node_app -.->|"exposes checks"| node_health
node_app -->|"configures logging"| node_logging
node_app -->|"configures metrics"| node_metrics
node_app -->|"configures tracing"| node_tracing
node_usecases -.->|"billing integration"| node_billing

click node_app "https://github.com/harshilmaks/tenancy-service/blob/main/app/main.py"
click node_tenant_api "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/tenants/routes.py"
click node_schemas "https://github.com/harshilmaks/tenancy-service/blob/main/app/schemas/v1/requests_responses.py"
click node_providers "https://github.com/harshilmaks/tenancy-service/blob/main/app/dependencies/providers.py"
click node_usecases "https://github.com/harshilmaks/tenancy-service/tree/main/app/business/use_cases"
click node_lifecycle "https://github.com/harshilmaks/tenancy-service/blob/main/app/business/domain/entities/lifecycle.py"
click node_policies "https://github.com/harshilmaks/tenancy-service/blob/main/app/business/domain/entities/policies.py"
click node_events "https://github.com/harshilmaks/tenancy-service/blob/main/app/business/events/tenant_events.py"
click node_domain "https://github.com/harshilmaks/tenancy-service/blob/main/app/db/models/domain_models.py"
click node_feature_api "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/features/routes.py"
click node_onboarding "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/onboarding/routes.py"
click node_compliance "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/compliance/routes.py"
click node_retention "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/retention/routes.py"
click node_cancellations "https://github.com/harshilmaks/tenancy-service/blob/main/app/api/cancellations/routes.py"
click node_billing "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/billing/billing_service.py"
click node_repository "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/persistence/tenant_repository.py"
click node_health "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/health.py"
click node_logging "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/logging.py"
click node_metrics "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/metrics.py"
click node_tracing "https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/tracing.py"

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_app,node_tenant_api,node_schemas,node_providers,node_client toneBlue
class node_usecases,node_lifecycle,node_policies,node_events,node_domain toneAmber
class node_feature_api,node_onboarding,node_compliance,node_retention,node_cancellations,node_billing toneMint
class node_repository,node_database toneRose
class node_health,node_logging,node_metrics,node_tracing toneIndigo
```

## Components

### API entry

- [FastAPI application](https://github.com/harshilmaks/tenancy-service/blob/main/app/main.py): `app/main.py`
- [Tenant routes](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/tenants/routes.py): `app/api/tenants/routes.py`
- [Request schemas](https://github.com/harshilmaks/tenancy-service/blob/main/app/schemas/v1/requests_responses.py): `app/schemas/v1/requests_responses.py`
- [Dependency providers](https://github.com/harshilmaks/tenancy-service/blob/main/app/dependencies/providers.py): `app/dependencies/providers.py`

### Tenant business

- [Tenant use cases](https://github.com/harshilmaks/tenancy-service/tree/main/app/business/use_cases): `app/business/use_cases`
- [Lifecycle rules](https://github.com/harshilmaks/tenancy-service/blob/main/app/business/domain/entities/lifecycle.py): `app/business/domain/entities/lifecycle.py`
- [Policy rules](https://github.com/harshilmaks/tenancy-service/blob/main/app/business/domain/entities/policies.py): `app/business/domain/entities/policies.py`
- [Domain events](https://github.com/harshilmaks/tenancy-service/blob/main/app/business/events/tenant_events.py): `app/business/events/tenant_events.py`
- [Organization model](https://github.com/harshilmaks/tenancy-service/blob/main/app/db/models/domain_models.py): `app/db/models/domain_models.py`

### Tenant capabilities

- [Feature gating API](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/features/routes.py): `app/api/features/routes.py`
- [Onboarding workflow](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/onboarding/routes.py): `app/api/onboarding/routes.py`
- [Compliance API](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/compliance/routes.py): `app/api/compliance/routes.py`
- [Retention API](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/retention/routes.py): `app/api/retention/routes.py`
- [Cancellation workflow](https://github.com/harshilmaks/tenancy-service/blob/main/app/api/cancellations/routes.py): `app/api/cancellations/routes.py`
- [Billing integration](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/billing/billing_service.py): `infrastructure/billing/billing_service.py`

### Persistence

- [Tenant repository](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/persistence/tenant_repository.py): `infrastructure/persistence/tenant_repository.py`
- **Relational database**

### Operations

- [Health monitoring](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/health.py): `infrastructure/observability/health.py`
- [Structured logging](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/logging.py): `infrastructure/observability/logging.py`
- [Metrics collection](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/metrics.py): `infrastructure/observability/metrics.py`
- [Distributed tracing](https://github.com/harshilmaks/tenancy-service/blob/main/infrastructure/observability/tracing.py): `infrastructure/observability/tracing.py`

### Other components

- **API client**

## Connections

- API client → FastAPI application: sends requests
- FastAPI application → Tenant routes: registers routes (evidence: `app/main.py`)
- Tenant routes → Request schemas: validates requests (evidence: `app/api/tenants/routes.py`)
- Tenant routes → Dependency providers: resolves dependencies (evidence: `app/api/tenants/routes.py`)
- Dependency providers → Tenant use cases: builds use cases (evidence: `app/dependencies/providers.py`)
- Tenant routes → Tenant use cases: executes (evidence: `app/api/tenants/routes.py`)
- Tenant use cases → Lifecycle rules: checks transitions (evidence: `app/business/use_cases/create_tenant.py`)
- Tenant use cases → Domain events: publishes events (evidence: `app/business/use_cases/create_tenant.py`)
- Tenant use cases → Tenant repository: persists tenants
- Tenant repository → Organization model: maps models
- Tenant repository → Relational database: reads and writes
- Tenant use cases → Policy rules: evaluates policies (evidence: `app/business/use_cases/enforce_policy.py`)
- Feature gating API → Tenant repository: loads tenant (evidence: `app/api/features/routes.py`)
- Onboarding workflow → Tenant repository: saves progress (evidence: `app/api/onboarding/routes.py`)
- Compliance API → Tenant repository: loads tenant (evidence: `app/api/compliance/routes.py`)
- Retention API → Tenant repository: updates retention (evidence: `app/api/retention/routes.py`)
- Cancellation workflow → Tenant repository: updates status (evidence: `app/api/cancellations/routes.py`)
- FastAPI application → Health monitoring: exposes checks
- FastAPI application → Structured logging: configures logging
- FastAPI application → Metrics collection: configures metrics
- FastAPI application → Distributed tracing: configures tracing
- Tenant use cases → Billing integration: billing integration
