# maorte/advusermanagementapi architecture

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

- Interactive diagram: https://gitdiagram.com/maorte/advusermanagementapi
- Repository: https://github.com/maorte/advusermanagementapi

## Overview

##### Project type and purpose
- This is a .NET 9 Minimal API backend called **UserManagementApi**.
- Its purpose: expose RESTful CRUD endpoints for **Users** and **Cars**, backed by EF Core and a relational database.
- It follows Clean Architecture: clearly separated layers for Data, Models, Services, Endpoints, Middleware, and Infrastructure.

##### File structure
Top-level directories:
- **Data** – EF Core DbContext, migrations, any repository code
- **Models** – domain entities (User, Car) and DTOs (LoginDto, etc.)
- **Services** – business‐logic interfaces and implementations (UserService, CarService, IdempotencyService, ReportsService, SftpFileTransferService, DataMigrationService)
- **Endpoints** – Minimal API route-definition classes grouping related HTTP handlers
- **Middleware** – cross-cutting concerns (ExceptionHandler)
- **Infrastructure** – hosting extensions (authentication, TLS), certificate.pfx, Dockerfile
- **Migrations** – EF Core migration snapshot and scripts
- **Program.cs** – configures DI, middleware pipeline, endpoint registration
- **appsettings*.json** – configuration for connection strings, environment settings

##### README for additional insights
- Layers flow: Endpoints → Services → Data (AppDbContext) → Database
- Uses dependency injection for loose coupling
- Key technologies: .NET 9, C# 12, EF Core, SQL Server, Minimal APIs, custom middleware

a. Main components
- **Clients** (e.g., Web/Mobile frontend or API consumers)
- **API Gateway / ASP.NET Core Host**
- **Middleware Pipeline** (TLS, AuthenticationExtensions, ExceptionHandler)
- **Endpoints Layer** (AuthEndpoints, UserEndpoints, CarEndpoints, ReportEndpoints, DataMigrationEndpoints)
- **Services Layer**
- UserService, CarService, ReportsService, DataMigrationService, IdempotencyService, SftpFileTransferService
- **Data Layer**
- AppDbContext (EF Core) & Migrations
- **External Systems**
- **Relational Database** (SQL Server)
- **SFTP Server** (for data migrations)

b. Relationships and interactions
1. **HTTP Request** from Client → TLS termination → Authentication middleware
2. Routed to **Endpoint** handler (e.g., `app.MapPost("/api/users", handler)`)
3. Endpoint calls corresponding **Service** interface (`IUserService.CreateAsync`)
4. Service uses **AppDbContext** for EF Core operations → translates to SQL queries → **Database**
5. Services like DataMigrationService may also call **SftpFileTransferService** to push/pull files to an **SFTP Server**
6. **IdempotencyService** ensures safe retries via a dedicated IdempotencyRecords table in the database
7. **Middleware** sits around this flow to catch exceptions (ExceptionHandler) and log or standardize errors

c. Architectural patterns & design principles
- **Layered / Clean Architecture**: strict separation of concerns
- **Dependency Injection**: all services & DbContext registered in Program.cs
- **Minimal API**: lightweight, no MVC controllers
- **Repository pattern** (via EF Core DbContext directly or via repository classes)
- **Idempotency** for safe external calls
- **Extensions-based configuration** for Authentication and TLS in Infrastructure/Hosting

d. Key technologies/frameworks
- .NET 9 Minimal APIs
- C# 12
- Entity Framework Core (DbContext, Migrations)
- SQL Server (or any EF Core-compatible RDBMS)
- SFTP (via a custom SftpFileTransferService)
- Custom Middleware

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients (Web/Mobile)"]:::external
    Clients -->|"HTTPS/TLS"| TlsExt["TlsConfigurationExtensions"]:::api

    %% Infrastructure Extensions & Middleware Pipeline
    TlsExt --> AuthExt["AuthenticationExtensions"]:::api
    AuthExt --> ExceptionHandler["ExceptionHandler"]:::api
    ExceptionHandler --> Program["Program.cs"]:::api

    %% API Layer - Endpoints
    subgraph "API Layer" 
        direction TB
        AuthE["AuthEndpoints"]:::api
        UserE["UserEndpoints"]:::api
        CarE["CarEndpoints"]:::api
        ReportE["ReportEndpoints"]:::api
        DataMigE["DataMigrationEndpoints"]:::api
    end

    Program --> AuthE
    Program --> UserE
    Program --> CarE
    Program --> ReportE
    Program --> DataMigE

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        UserService["UserService"]:::service
        CarService["CarService"]:::service
        ReportsService["ReportsService"]:::service
        DataMigrationService["DataMigrationService"]:::service
        IdempotencyService["IdempotencyService"]:::service
        SftpFileTransferService["SftpFileTransferService"]:::service
    end

    AuthE --> UserService
    UserE --> UserService
    CarE --> CarService
    ReportE --> ReportsService
    DataMigE --> DataMigrationService
    DataMigE --> IdempotencyService
    DataMigE --> SftpFileTransferService

    %% Models
    subgraph "Models" 
        direction TB
        UserModel["User"]:::data
        CarModel["Car"]:::data
        LoginDto["LoginDto"]:::data
        IdempotencyRecord["IdempotencyRecord"]:::data
    end

    UserService --> UserModel
    CarService --> CarModel
    AuthE --> LoginDto
    IdempotencyService --> IdempotencyRecord

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        AutoDb["AutoShopDbContext"]:::data
        subgraph Migrations 
            direction TB
            Mig1["20250605082615_InitialCreate.cs"]:::data
            Mig1D["20250605082615_InitialCreate.Designer.cs"]:::data
            Snapshot["AutoShopDbContextModelSnapshot.cs"]:::data
        end
    end

    UserService --> AutoDb
    CarService --> AutoDb
    ReportsService --> AutoDb
    DataMigrationService --> AutoDb
    IdempotencyService --> AutoDb

    Mig1 --> AutoDb
    Mig1D --> AutoDb
    Snapshot --> AutoDb

    SftpFileTransferService -->|"SFTP"| SftpServer["SFTP Server"]:::external
    AutoDb -->|"SQL"| SqlServer["SQL Server"]:::external

    %% Click Events
    click Program "https://github.com/maorte/advusermanagementapi/blob/main/Program.cs"
    click TlsExt "https://github.com/maorte/advusermanagementapi/blob/main/Infrastructure/Hosting/TlsConfigurationExtensions.cs"
    click AuthExt "https://github.com/maorte/advusermanagementapi/blob/main/Infrastructure/Hosting/AuthenticationExtensions.cs"
    click ExceptionHandler "https://github.com/maorte/advusermanagementapi/blob/main/Middleware/ExceptionHandler.cs"
    click AuthE "https://github.com/maorte/advusermanagementapi/blob/main/Endpoints/AuthEndpoints.cs"
    click UserE "https://github.com/maorte/advusermanagementapi/blob/main/Endpoints/UserEndPoint.cs"
    click CarE "https://github.com/maorte/advusermanagementapi/blob/main/Endpoints/CarEndpoints.cs"
    click ReportE "https://github.com/maorte/advusermanagementapi/blob/main/Endpoints/ReportEndpoints.cs"
    click DataMigE "https://github.com/maorte/advusermanagementapi/blob/main/Endpoints/DataMigrationEndpoints.cs"
    click UserService "https://github.com/maorte/advusermanagementapi/blob/main/Services/UserService.cs"
    click CarService "https://github.com/maorte/advusermanagementapi/blob/main/Services/CarService.cs"
    click ReportsService "https://github.com/maorte/advusermanagementapi/blob/main/Services/ReportsService.cs"
    click DataMigrationService "https://github.com/maorte/advusermanagementapi/blob/main/Services/DataMigrationService.cs"
    click IdempotencyService "https://github.com/maorte/advusermanagementapi/blob/main/Services/IdempotencyService.cs"
    click SftpFileTransferService "https://github.com/maorte/advusermanagementapi/blob/main/Services/SftpFileTransferService.cs"
    click AutoDb "https://github.com/maorte/advusermanagementapi/blob/main/Data/AutoShopDbContext.cs"
    click Mig1 "https://github.com/maorte/advusermanagementapi/blob/main/Migrations/20250605082615_InitialCreate.cs"
    click Mig1D "https://github.com/maorte/advusermanagementapi/blob/main/Migrations/20250605082615_InitialCreate.Designer.cs"
    click Snapshot "https://github.com/maorte/advusermanagementapi/blob/main/Migrations/AutoShopDbContextModelSnapshot.cs"
    click UserModel "https://github.com/maorte/advusermanagementapi/blob/main/Models/User.cs"
    click CarModel "https://github.com/maorte/advusermanagementapi/blob/main/Models/Car.cs"
    click LoginDto "https://github.com/maorte/advusermanagementapi/blob/main/Models/LoginDto.cs"
    click IdempotencyRecord "https://github.com/maorte/advusermanagementapi/blob/main/Models/IdempotencyRecord.cs"

    %% Styles
    classDef api fill:#cee7ff,stroke:#0366d6,color:#0366d6;
    classDef service fill:#e6ffe6,stroke:#28a745,color:#28a745;
    classDef data fill:#fff4e6,stroke:#d9730d,color:#d9730d;
    classDef external fill:#f0f0f0,stroke:#6a737d,color:#6a737d;
    class Clients,SftpServer,SqlServer external
    class TlsExt,AuthExt,ExceptionHandler,Program,AuthE,UserE,CarE,ReportE,DataMigE api
    class UserService,CarService,ReportsService,DataMigrationService,IdempotencyService,SftpFileTransferService service
    class AutoDb,Mig1,Mig1D,Snapshot,UserModel,CarModel,LoginDto,IdempotencyRecord data
```
