🏗️ API Architecture

Core architectural patterns and design principles

🎯 Architectural Overview

AIUsagePlatform API Architecture ═══════════════════════════════════════════════════════════════════════════════ ┌─────────────────────────────────────────────────────────────────────────────┐ │ CONTROLLER LAYER │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ API Controllers (25+) │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ • BaseApiController (abstract - subscription/auth helpers) │ │ │ │ • SuperAdminDashboardController • AdminDashboardController │ │ │ │ • AdminOrganizationController • UsersManagementController │ │ │ │ • AnalyticsController • ReportingController │ │ │ │ • DataExportController • ExportJobsController │ │ │ │ • TimeAggregationController • PerformanceMetricsController │ │ │ │ • AuditLoggingController • BillingController │ │ │ │ • AuthController • RoleManagementController │ │ │ │ • SystemObservabilityController • AgentHealthMonitoring │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ Patterns: │ │ • [Authorize] + [EnableRateLimiting] on all controllers │ │ • [Authorize(Roles="...")] for role-restricted endpoints │ │ • [RequiresPlanFeature] for subscription-gated features │ │ • JWT claims extraction via BaseApiController helpers │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ SERVICE LAYER │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ Application Services │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ • IOrganizationService • IUserService • IAnalyticsService │ │ │ │ • IReportingService • IExportService • IAuditService │ │ │ │ • IBillingService • IAuthService • IRoleService │ │ │ │ • ISessionService • IDeviceService • IPerformanceService │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ Design: Repository Pattern + Dependency Injection │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ REPOSITORY LAYER │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ EF Core Repositories │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ • OrganizationRepository • UserRepository • SessionRepository │ │ │ │ • DeviceRepository • AuditRepository • BillingRepository │ │ │ │ • AnalyticsRepository • ExportRepository • PlanRepository │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ Features: │ │ • Generic IRepository for CRUD operations │ │ • Specification pattern for complex queries │ │ • Unit of Work pattern for transactions │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATABASE LAYER │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ SQL Server with EF Core │ │ • Migrations managed in Infrastructure project │ │ • Connection string: Organization-scoped via middleware │ │ • Read replicas: Recommended for reporting (future) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

🎨 Design Patterns

Layered Architecture
  • ✓ Controllers (HTTP handling)
  • ✓ Services (Business logic)
  • ✓ Repositories (Data access)
  • ✓ Domain (Entities, DTOs)
Dependency Injection
  • ✓ Scoped: DbContext, Services
  • ✓ Singleton: Caching (planned)
  • ✓ Transient: Repositories
  • ✓ Constructor injection
Repository Pattern
  • ✓ IRepository interface
  • ✓ Generic CRUD operations
  • ✓ Specification pattern
  • ⚠ Some direct DbContext use
CQRS (Partial)
  • ✓ Separate read/write models
  • ✓ Query objects for reports
  • ⚠ Not fully implemented
  • → Opportunity for v2

🔐 Security Architecture

✓
JWT Authentication
Stateless tokens with claims (UserId, OrgId, Role, Permissions)
✓
RBAC Authorization
Role-based access via [Authorize(Roles=...)] attributes
✓
Permission-Based
Fine-grained permissions via [HasPermission] attributes
✓
Multi-Tenant Isolation
Middleware enforces OrganizationId filtering on all queries

📊 API Inventory by Category

CategoryControllersEndpointsPrimary Role
Administration535+SuperAdmin, Admin
Analytics425+All roles (scoped)
Reporting315+Admin, Manager
User Management320+Admin
Billing215+Admin, SuperAdmin
Security320+All roles
System325+SuperAdmin, System

🔗 Cross-Cutting Concerns

Cross-Cutting Concerns Implementation ═══════════════════════════════════════════════════════════════════════════════ ┌─────────────────────────────────────────────────────────────────────────────┐ │ MIDDLEWARE PIPELINE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Request → ExceptionHandler → HSTS → HTTPS → CORS → Authentication │ │ │ │ ↓ MultiTenantIsolationMiddleware (Custom) │ │ ↓ RateLimitingMiddleware │ │ ↓ RequestLoggingMiddleware │ │ │ │ → Routing → Endpoints │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ CROSS-CUTTING SERVICES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Logging: ILogger (structured logging to Seq/Splunk) │ │ │ │ │ Monitoring: IPerformanceMetricsService (endpoint timing, health checks) │ │ │ │ │ Caching: IDistributedCache (Redis planned for v2) │ │ │ │ │ Validation: FluentValidation (DTO validation) │ │ │ │ │ Audit: IAuditLoggingService (all CRUD operations logged) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘