the-builder-s-circle/culturesync-api

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.