# the-builder-s-circle/culturesync-api architecture

> Architecture diagram of the GitHub repository the-builder-s-circle/culturesync-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-builder-s-circle/culturesync-api
- Repository: https://github.com/the-builder-s-circle/culturesync-api

## Overview

#### 1. Purpose and runtime entry point
CultureSync is a .NET backend for multi-tenant HR/workplace management: tenant onboarding, organization setup, authentication, authorization, audit logging, and domain areas including employees, goals, leave, attendance, appraisals, and performance cycles. The HTTP host starts at `src/CultureSync.Api/Program.cs`; container deployment is supported by `src/CultureSync.Api/Dockerfile`.

#### 2. Layered architecture and dependency boundary
The repository follows a Clean Architecture/CQRS shape:
- **API** exposes HTTP controllers and translates requests/results.
- **Application** owns commands, queries, validation, pipeline behavior, and use-case orchestration.
- **Domain** owns entities, contracts, events, and shared business types.
- **Infrastructure** implements persistence, identity, mail, authorization, audit, templates, and external integrations.
Key boundaries are represented by `src/CultureSync.Domain/Contracts/Repositories/IUnitOfWork.cs`, `src/CultureSync.Domain/Contracts/Services/IIdentityService.cs`, and `src/CultureSync.Infrastructure/Extensions/ServiceCollectionExtension.cs`.

#### 3. API request and error flow
Controllers are the public entry points for authentication and tenant lifecycle operations: `src/CultureSync.Api/Controllers/AuthController.cs` and `src/CultureSync.Api/Controllers/TenantController.cs`. Requests enter the ASP.NET Core pipeline configured in `src/CultureSync.Api/Program.cs`, are subject to tenant/header API documentation support in `src/CultureSync.Api/Filters/TenantHeaderOperationFilter.cs`, then dispatch into application commands or queries. Validation and application/infrastructure exceptions are converted to API error responses through `src/CultureSync.Application/Middlewares/ExceptionHandlingMiddleware.cs` and `src/CultureSync.Infrastructure/Middleware/ExceptionMiddleware.cs`.

#### 4. CQRS use-case pipeline
Application operations use command/query abstractions, separating mutations from reads: `src/CultureSync.Application/Abstractions/Messaging/ICommand.cs` and `src/CultureSync.Application/Abstractions/Messaging/IQuery.cs`. Validation is centrally applied by `src/CultureSync.Application/Wrapper/ValidationBehavior.cs`; auditable mutations can flow through `src/CultureSync.Application/Behaviors/AuditLoggingBehavior.cs`. Core implemented use cases include login (`src/CultureSync.Application/Commands/Auth/LoginCommand/LoginCommandHandler.cs`), tenant-admin signup (`src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs`), organization setup, verification, and setup lookup reads.

#### 5. Tenant lifecycle and isolation
Tenant onboarding is a primary business flow: admin registration, verification, and organization-profile setup are represented by the command folders under `src/CultureSync.Application/Commands/Tenant`. Tenant context is initialized at the infrastructure boundary by `src/CultureSync.Infrastructure/Middleware/TenantInitializationMiddleware.cs`, while persistence access is specialized by `src/CultureSync.Infrastructure/Repositories/TenantRepository.cs`. Domain tenant state and lifecycle events reside in `src/CultureSync.Domain/Entities/Tenant.cs` and `src/CultureSync.Domain/Tenants/Events/TenantRegisteredDomainEvent.cs`; application event handling includes tenant registration auditing.

#### 6. Persistence, identity, and authorization
Entity Framework Core persistence centers on `src/CultureSync.Infrastructure/Context/CultureSyncContext.cs`, with schema evolution under `src/CultureSync.Infrastructure/Migrations`. Repositories and transactional coordination are implemented by `src/CultureSync.Infrastructure/Repositories/BaseRepository.cs` and `src/CultureSync.Infrastructure/Repositories/UnitOfWork.cs`. Identity/user operations are abstracted by `src/CultureSync.Domain/Contracts/Services/IIdentityService.cs` and implemented in `src/CultureSync.Infrastructure/Services/IdentityService.cs`. Permission-based authorization is enforced through `src/CultureSync.Infrastructure/Authorization/PermissionAuthorizationHandler.cs` and `src/CultureSync.Infrastructure/Authorization/PermissionPolicyProvider.cs`.

#### 7. External services and extensibility
Email delivery and Razor-based email rendering cross infrastructure adapters: `src/CultureSync.Infrastructure/Messaging/MailSender.cs`, `src/CultureSync.Infrastructure/Services/MailService.cs`, and `src/CultureSync.Infrastructure/TemplateEngine/RazorEngine.cs`; the API includes the OTP mail view at `src/CultureSync.Api/Views/SendOTPVerificationMail.cshtml`. Media storage is abstracted through `src/CultureSync.Domain/Contracts/Services/ICloudinaryService.cs` and implemented by `src/CultureSync.Infrastructure/Services/CloudinaryService.cs`. Domain entities and enum state models in `src/CultureSync.Domain/Entities` provide the expansion surface for the broader HR modules.

Main entry points: [`src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs`](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs) (Tenant onboarding), [`src/CultureSync.Application/Wrapper/ValidationBehavior.cs`](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Wrapper/ValidationBehavior.cs) (Validation & audit pipeline), [`src/CultureSync.Api/Controllers/AuthController.cs`](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Controllers/AuthController.cs) (Auth & tenant controllers), [`src/CultureSync.Api/Program.cs`](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Program.cs) (ASP.NET Core host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Host"]
  node_host["ASP.NET Core host<br/>runtime entry point<br/>[Program.cs]"]
  node_controllers["Auth &amp; tenant controllers<br/>HTTP endpoints<br/>[AuthController.cs]"]
  node_tenant_docs["Tenant header support<br/>API filter"]
end

subgraph group_application["Application / CQRS"]
  node_commands["Commands<br/>CQRS mutation contract<br/>[ICommand.cs]"]
  node_queries["Queries<br/>CQRS read contract<br/>[IQuery.cs]"]
  node_pipeline["Validation &amp; audit pipeline<br/>CQRS behaviors"]
  node_auth_usecase["Login use case<br/>command handler"]
  node_onboarding["Tenant onboarding<br/>command handler"]
  node_app_errors["Application error handling<br/>exception middleware"]
end

subgraph group_domain["Domain"]
  node_tenant{{"Tenant aggregate<br/>domain entity<br/>[Tenant.cs]"}}
  node_tenant_event["Tenant registered event<br/>domain event"]
  node_unit_of_work_contract["Unit of work contract<br/>repository contract<br/>[IUnitOfWork.cs]"]
  node_identity_contract["Identity contract<br/>service contract"]
end

subgraph group_infrastructure["Infrastructure"]
  node_tenant_context["Tenant initialization<br/>request middleware"]
  node_persistence[("EF Core context<br/>persistence context")]
  node_repositories["Repositories &amp; unit of work<br/>persistence implementation<br/>[UnitOfWork.cs]"]
  node_identity["Identity service<br/>identity adapter<br/>[IdentityService.cs]"]
  node_authorization["Permission authorization<br/>authorization handler"]
  node_mail["Email delivery<br/>messaging adapter<br/>[MailService.cs]"]
  node_cloud_media["Cloud media storage<br/>storage adapter"]
  node_infra_errors["Infrastructure error handling<br/>exception middleware"]
  node_service_registration["Infrastructure registration<br/>DI composition"]
end

node_host -->|"registers adapters"| node_service_registration
node_host -->|"HTTP pipeline"| node_tenant_context
node_host -->|"handles errors"| node_infra_errors
node_host -->|"routes requests"| node_controllers
node_tenant_docs -.->|"documents tenant header"| node_controllers
node_tenant_context -->|"tenant-scoped request"| node_controllers
node_controllers -->|"dispatches mutations"| node_commands
node_controllers -->|"dispatches reads"| node_queries
node_commands -->|"passes through"| node_pipeline
node_queries -->|"passes through"| node_pipeline
node_pipeline -->|"login"| node_auth_usecase
node_pipeline -->|"tenant signup"| node_onboarding
node_pipeline -.->|"maps application failures"| node_app_errors
node_auth_usecase -->|"authenticates via"| node_identity_contract
node_onboarding -->|"creates"| node_tenant
node_tenant -->|"raises"| node_tenant_event
node_onboarding -->|"persists through"| node_unit_of_work_contract
node_onboarding -->|"provisions admin"| node_identity_contract
node_onboarding -->|"sends verification"| node_mail
node_repositories -.->|"implements"| node_unit_of_work_contract
node_repositories -->|"uses"| node_persistence
node_identity -.->|"implements"| node_identity_contract
node_authorization -->|"checks permissions"| node_identity
node_cloud_media -.->|"stores media references"| node_persistence

click node_host "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Program.cs"
click node_controllers "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Controllers/AuthController.cs"
click node_tenant_docs "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Filters/TenantHeaderOperationFilter.cs"
click node_commands "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Abstractions/Messaging/ICommand.cs"
click node_queries "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Abstractions/Messaging/IQuery.cs"
click node_pipeline "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Wrapper/ValidationBehavior.cs"
click node_auth_usecase "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Commands/Auth/LoginCommand/LoginCommandHandler.cs"
click node_onboarding "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs"
click node_app_errors "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Middlewares/ExceptionHandlingMiddleware.cs"
click node_tenant "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Entities/Tenant.cs"
click node_tenant_event "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Tenants/Events/TenantRegisteredDomainEvent.cs"
click node_unit_of_work_contract "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Contracts/Repositories/IUnitOfWork.cs"
click node_identity_contract "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Contracts/Services/IIdentityService.cs"
click node_tenant_context "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Middleware/TenantInitializationMiddleware.cs"
click node_persistence "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Context/CultureSyncContext.cs"
click node_repositories "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Repositories/UnitOfWork.cs"
click node_identity "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/IdentityService.cs"
click node_authorization "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Authorization/PermissionAuthorizationHandler.cs"
click node_mail "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/MailService.cs"
click node_cloud_media "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/CloudinaryService.cs"
click node_infra_errors "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Middleware/ExceptionMiddleware.cs"
click node_service_registration "https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Extensions/ServiceCollectionExtension.cs"

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_host,node_controllers,node_tenant_docs toneBlue
class node_commands,node_queries,node_pipeline,node_auth_usecase,node_onboarding,node_app_errors toneAmber
class node_tenant,node_tenant_event,node_unit_of_work_contract,node_identity_contract toneMint
class node_tenant_context,node_persistence,node_repositories,node_identity,node_authorization,node_mail,node_cloud_media,node_infra_errors,node_service_registration toneRose
```

## Components

### API Host

- [ASP.NET Core host](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Program.cs): runtime entry point · Configures HTTP pipeline and dependency injection. · `src/CultureSync.Api/Program.cs`
- [Auth & tenant controllers](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Controllers/AuthController.cs): HTTP endpoints · `src/CultureSync.Api/Controllers/AuthController.cs`
- [Tenant header support](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Api/Filters/TenantHeaderOperationFilter.cs): API filter · `src/CultureSync.Api/Filters/TenantHeaderOperationFilter.cs`

### Application / CQRS

- [Commands](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Abstractions/Messaging/ICommand.cs): CQRS mutation contract · `src/CultureSync.Application/Abstractions/Messaging/ICommand.cs`
- [Queries](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Abstractions/Messaging/IQuery.cs): CQRS read contract · `src/CultureSync.Application/Abstractions/Messaging/IQuery.cs`
- [Validation & audit pipeline](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Wrapper/ValidationBehavior.cs): CQRS behaviors · Validates requests and audits applicable mutations. · `src/CultureSync.Application/Wrapper/ValidationBehavior.cs`
- [Login use case](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Commands/Auth/LoginCommand/LoginCommandHandler.cs): command handler · `src/CultureSync.Application/Commands/Auth/LoginCommand/LoginCommandHandler.cs`
- [Tenant onboarding](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs): command handler · Registers the organization administrator and begins tenant setup. · `src/CultureSync.Application/Commands/Tenant/SignUpOrganizationAdminCommand/SignUpOrganizationAdminCommandHandler.cs`
- [Application error handling](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Application/Middlewares/ExceptionHandlingMiddleware.cs): exception middleware · `src/CultureSync.Application/Middlewares/ExceptionHandlingMiddleware.cs`

### Domain

- [Tenant aggregate](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Entities/Tenant.cs): domain entity · Owns tenant lifecycle state. · `src/CultureSync.Domain/Entities/Tenant.cs`
- [Tenant registered event](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Tenants/Events/TenantRegisteredDomainEvent.cs): domain event · `src/CultureSync.Domain/Tenants/Events/TenantRegisteredDomainEvent.cs`
- [Unit of work contract](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Contracts/Repositories/IUnitOfWork.cs): repository contract · `src/CultureSync.Domain/Contracts/Repositories/IUnitOfWork.cs`
- [Identity contract](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Domain/Contracts/Services/IIdentityService.cs): service contract · `src/CultureSync.Domain/Contracts/Services/IIdentityService.cs`

### Infrastructure

- [Tenant initialization](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Middleware/TenantInitializationMiddleware.cs): request middleware · Establishes tenant context at the infrastructure boundary. · `src/CultureSync.Infrastructure/Middleware/TenantInitializationMiddleware.cs`
- [EF Core context](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Context/CultureSyncContext.cs): persistence context · Central database access and schema mapping. · `src/CultureSync.Infrastructure/Context/CultureSyncContext.cs`
- [Repositories & unit of work](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Repositories/UnitOfWork.cs): persistence implementation · `src/CultureSync.Infrastructure/Repositories/UnitOfWork.cs`
- [Identity service](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/IdentityService.cs): identity adapter · `src/CultureSync.Infrastructure/Services/IdentityService.cs`
- [Permission authorization](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Authorization/PermissionAuthorizationHandler.cs): authorization handler · `src/CultureSync.Infrastructure/Authorization/PermissionAuthorizationHandler.cs`
- [Email delivery](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/MailService.cs): messaging adapter · Renders and sends verification mail. · `src/CultureSync.Infrastructure/Services/MailService.cs`
- [Cloud media storage](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Services/CloudinaryService.cs): storage adapter · `src/CultureSync.Infrastructure/Services/CloudinaryService.cs`
- [Infrastructure error handling](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Middleware/ExceptionMiddleware.cs): exception middleware · `src/CultureSync.Infrastructure/Middleware/ExceptionMiddleware.cs`
- [Infrastructure registration](https://github.com/the-builder-s-circle/culturesync-api/blob/main/src/CultureSync.Infrastructure/Extensions/ServiceCollectionExtension.cs): DI composition · `src/CultureSync.Infrastructure/Extensions/ServiceCollectionExtension.cs`

## Connections

- ASP.NET Core host → Infrastructure registration: registers adapters
- ASP.NET Core host → Tenant initialization: HTTP pipeline
- ASP.NET Core host → Infrastructure error handling: handles errors
- ASP.NET Core host → Auth & tenant controllers: routes requests
- Tenant header support → Auth & tenant controllers: documents tenant header
- Tenant initialization → Auth & tenant controllers: tenant-scoped request
- Auth & tenant controllers → Commands: dispatches mutations
- Auth & tenant controllers → Queries: dispatches reads
- Commands → Validation & audit pipeline: passes through
- Queries → Validation & audit pipeline: passes through
- Validation & audit pipeline → Login use case: login
- Validation & audit pipeline → Tenant onboarding: tenant signup
- Validation & audit pipeline → Application error handling: maps application failures
- Login use case → Identity contract: authenticates via
- Tenant onboarding → Tenant aggregate: creates
- Tenant aggregate → Tenant registered event: raises
- Tenant onboarding → Unit of work contract: persists through
- Tenant onboarding → Identity contract: provisions admin
- Tenant onboarding → Email delivery: sends verification
- Repositories & unit of work → Unit of work contract: implements
- Repositories & unit of work → EF Core context: uses
- Identity service → Identity contract: implements
- Permission authorization → Identity service: checks permissions
- Cloud media storage → EF Core context: stores media references