# domoar/northwind-api architecture

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

- Interactive diagram: https://gitdiagram.com/domoar/northwind-api
- Repository: https://github.com/domoar/northwind-api

## Overview

##### Project Type and Purpose
- This is a full-stack RESTful API (ASP.NET Core) following a Clean-Architecture/Onion-Architecture template.
- Its purpose is to expose Northwind database data (Customers, Employees, Products, Orders, etc.) over HTTP, with built-in support for metrics, logging, tracing, and Docker-based deployment.

##### Main Architectural Components
a. Clients & Entry Points
- REST clients (curl, Postman, Swagger UI, custom HTTP client)
- HTTPS endpoint: `/api/v1/...`
b. API Layer (Presentation)
- Controllers (CustomerController, EmployeeController, ProductController)
- Middleware (GlobalExceptionHandler, OpenTelemetry, Logging, Metrics, ResponseCompression)
- Service extensions (Dependency injection, API versioning, Swagger generation)
c. Application Layer
- Services (CustomerService, EmployeeService, ProductService)
- Request/Response models & validations (FluentValidation)
- Cross-cutting extensions
d. Domain Layer (Core)
- Domain entities and interfaces
- Business rules, domain events
e. Infrastructure Layer (Data & External Integrations)
- EF Core DbContext (NorthwindContext)
- Repositories (NorthwindRepository)
- Health-check resilience service
f. Database
- PostgreSQL (Northwind schema)
- SQL scripts, migrations
g. Supporting Services (Docker-compose)
- pgAdmin (DB UI)
- Seq (centralized structured logging)
- Jaeger (distributed tracing)
h. CI/CD & Dev Tools
- GitHub Actions (build, test, documentation, code coverage)
- Git hooks (pre-commit formatting & build)
- Dockerfiles & multi-file docker-compose setup

##### Relationships & Data Flow
- Clients → API Gateway (Swashbuckle/Swagger UI or HTTP)
- API Controllers invoke → Application Services via DI
- Application Services orchestrate → Domain layer (business logic & interfaces)
- Domain interfaces implemented by → Infrastructure Repositories/DbContext
- Infrastructure writes/reads → PostgreSQL database
- Middleware emits logs to → Seq, emits traces to → Jaeger
- CI/CD pipelines trigger → Build, Test, Coverage, Docs

##### Architectural Patterns & Principles
- Onion/Clean Architecture: Layers depend inward, no circular dependencies
- Dependency Inversion: Application & Domain define interfaces, Infrastructure implements them
- Separation of Concerns: Presentation, business logic, persistence are isolated
- Cross-cutting via Middleware & ServiceExtensions

##### Technologies & Frameworks
- ASP.NET Core Web API
- Entity Framework Core with Npgsql provider
- FluentValidation for request validation
- OpenTelemetry for tracing
- Serilog → Seq for logging storage
- Docker & Docker-Compose for containerization
- GitHub Actions for CI/CD
- xUnit for Unit and Integration testing

##### Final Checklist for the Engineer
- Docker service topology (API, DB, pgAdmin, Seq, Jaeger).
- Database initialization via SQL scripts in volume mounts.
- Test harness and CI/CD pipelines as side components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients & Entry Points
    subgraph "Clients & Entry Points" 
        direction TB
        Client(["HTTP Clients (curl/Postman)"]):::external
        SwaggerUI(["Swagger UI"]):::external
    end

    %% API Layer
    subgraph "API Layer (Presentation)" 
        direction TB
        CustomerController["CustomerController"]:::api
        EmployeeController["EmployeeController"]:::api
        ProductController["ProductController"]:::api

        subgraph "Middleware & Extensions"
            direction TB
            GlobalExceptionHandler["GlobalExceptionHandler"]:::api
            OpenTelemetryExt["OpenTelemetry"]:::api
            LoggingExt["Logging"]:::api
            MetricsExt["Metrics"]:::api
            ResponseCompressionExt["ResponseCompression"]:::api
            ApiVersioningExt["ApiVersioning"]:::api
            SwaggerGenerationExt["SwaggerGeneration"]:::api
        end

        subgraph "Request/Validation"
            direction TB
            CustomerRequest["CustomerRequest"]:::api
            CustomerRequestValidator["CustomerRequestValidator"]:::api
        end
    end

    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        CustomerService["CustomerService"]:::app
        EmployeeService["EmployeeService"]:::app
        ProductService["ProductService"]:::app
        AppDI["DependencyInjectionContainer"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer" 
        direction TB
        DomainDI["DependencyInjectionContainer"]:::domain
        Entities["Domain Entities & Interfaces"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer" 
        direction TB
        NorthwindContext["NorthwindContext"]:::infra
        DesignTimeFactory["DesignTimeDbContextFactory"]:::infra
        NorthwindRepository["NorthwindRepository"]:::infra
        HealthCheckService["HealthCheckResilienceService"]:::infra
        EFEntities["EF Core Entities"]:::infra
    end

    %% Database & External Services
    subgraph "Data & External Services"
        direction TB
        PostgreSQL[(PostgreSQL)]:::external
        SQLScripts["SQL Scripts"]:::external
        pgAdmin["pgAdmin"]:::external
        Seq["Seq"]:::external
        Jaeger["Jaeger"]:::external
    end

    %% Docker & Supporting
    subgraph "Docker & Supporting" 
        direction TB
        DockerCompose["docker-compose.yml"]:::external
        DockerComposeDev["docker-compose.dev.yml"]:::external
        DockerComposeProd["docker-compose.prod.yml"]:::external
    end

    %% CI/CD & Tests
    subgraph "CI/CD & Tests"
        direction TB
        GitHubActions["GitHub Actions Workflows"]:::external
        GitHooks["Git Hooks (pre-commit)"]:::external
        IntegrationTests["Integration Tests"]:::external
        UnitTests["Unit Tests"]:::external
        PlantUML["PlantUML Diagrams"]:::external
        ApiClientExamples["API Client Examples"]:::external
    end

    %% Connections
    Client -->|"HTTP /api/v1/*"| CustomerController
    Client -->|"HTTP /api/v1/*"| EmployeeController
    Client -->|"HTTP /api/v1/*"| ProductController
    Client -->|Swagger UI| SwaggerUI

    CustomerController -->|uses| CustomerService
    EmployeeController -->|uses| EmployeeService
    ProductController -->|uses| ProductService

    GlobalExceptionHandler -.->|logs/traces| Seq
    OpenTelemetryExt -.->|traces| Jaeger
    LoggingExt -.->|logs| Seq
    MetricsExt -.->|metrics| Seq
    ResponseCompressionExt --> CustomerController
    ApiVersioningExt --> CustomerController
    SwaggerGenerationExt --> SwaggerUI

    CustomerController --> CustomerRequest
    CustomerController --> CustomerRequestValidator

    CustomerService -->|calls| DomainDI
    EmployeeService -->|calls| DomainDI
    ProductService -->|calls| DomainDI

    DomainDI --> Entities
    AppDI --> CustomerService
    AppDI --> EmployeeService
    AppDI --> ProductService

    Entities -->|interfaces| NorthwindRepository
    NorthwindRepository -->|uses| NorthwindContext
    NorthwindContext -->|reads/writes| PostgreSQL
    DesignTimeFactory --> NorthwindContext
    HealthCheckService --> PostgreSQL
    EFEntities --> NorthwindContext

    DockerCompose --> PostgreSQL
    DockerCompose -->|includes| pgAdmin
    DockerCompose -->|includes| Seq
    DockerCompose -->|includes| Jaeger
    DockerComposeDev --> DockerCompose
    DockerComposeProd --> DockerCompose

    GitHubActions -->|build/test| DockerCompose
    GitHooks -->|pre-commit| GitHubActions
    IntegrationTests -->|run against| CustomerController
    UnitTests -->|test| CustomerService
    UnitTests -->|test| NorthwindRepository
    PlantUML --> Entities
    ApiClientExamples --> CustomerController

    SQLScripts --> PostgreSQL

    %% Click Events
    click CustomerController "https://github.com/domoar/northwind-api/blob/main/src/Api/Controller/v1/CustomerController.cs"
    click EmployeeController "https://github.com/domoar/northwind-api/blob/main/src/Api/Controller/v1/EmployeeController.cs"
    click ProductController "https://github.com/domoar/northwind-api/blob/main/src/Api/Controller/v1/ProductController.cs"
    click GlobalExceptionHandler "https://github.com/domoar/northwind-api/blob/main/src/Api/Middleware/GlobalExceptionHandler.cs"
    click OpenTelemetryExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/OpenTelemetry.cs"
    click LoggingExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/Logging.cs"
    click MetricsExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/Metrics.cs"
    click ResponseCompressionExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/ResponseCompression.cs"
    click ApiVersioningExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/ApiVersioning.cs"
    click SwaggerGenerationExt "https://github.com/domoar/northwind-api/blob/main/src/Api/ServiceExtension/SwaggerGeneration.cs"
    click CustomerRequest "https://github.com/domoar/northwind-api/blob/main/src/Api/Request/Parameters/CustomerRequest.cs"
    click CustomerRequestValidator "https://github.com/domoar/northwind-api/blob/main/src/Api/Request/Validation/CustomerRequestValidator.cs"
    click CustomerService "https://github.com/domoar/northwind-api/blob/main/src/Application/Service/CustomerService.cs"
    click EmployeeService "https://github.com/domoar/northwind-api/blob/main/src/Application/Service/EmployeeService.cs"
    click ProductService "https://github.com/domoar/northwind-api/blob/main/src/Application/Service/ProductService.cs"
    click AppDI "https://github.com/domoar/northwind-api/blob/main/src/Application/DependencyInjectionContainer.cs"
    click DomainDI "https://github.com/domoar/northwind-api/blob/main/src/Domain/DependencyInjectionContainer.cs"
    click NorthwindContext "https://github.com/domoar/northwind-api/blob/main/src/Infrastructure/Context/NorthwindContext.cs"
    click DesignTimeFactory "https://github.com/domoar/northwind-api/blob/main/src/Infrastructure/Context/Factory/DesignTimeDbContextFactory.cs"
    click NorthwindRepository "https://github.com/domoar/northwind-api/blob/main/src/Infrastructure/Repository/NorthwindRepository.cs"
    click HealthCheckService "https://github.com/domoar/northwind-api/blob/main/src/Infrastructure/Service/HealthCheckResilienceService.cs"
    click EFEntities "https://github.com/domoar/northwind-api/blob/main/.extras/db/postgres/sql/create-db-northwind.sql"
    click SQLScripts "https://github.com/domoar/northwind-api/blob/main/.extras/db/postgres/sql/create-db-northwind.sql"
    click DockerCompose "https://github.com/domoar/northwind-api/blob/main/docker-compose.yml"
    click DockerComposeDev "https://github.com/domoar/northwind-api/blob/main/docker-compose.dev.yml"
    click DockerComposeProd "https://github.com/domoar/northwind-api/blob/main/docker-compose.prod.yml"
    click GitHubActions "https://github.com/domoar/northwind-api/blob/main/.github/workflows/build.yml"
    click GitHooks "https://github.com/domoar/northwind-api/tree/main/.githooks/pre-commit"
    click IntegrationTests "https://github.com/domoar/northwind-api/blob/main/tests/IntegrationTests/ApiFactory.cs"
    click UnitTests "https://github.com/domoar/northwind-api/blob/main/tests/UnitTests/Api/ApiUnitTest.cs"
    click PlantUML "https://github.com/domoar/northwind-api/blob/main/.extras/docu/plantuml/CustomerController.puml"
    click ApiClientExamples "https://github.com/domoar/northwind-api/blob/main/.extras/client/Api.http"

    %% Styles
    classDef api fill:#cce5ff,stroke:#4b9cd3,stroke-width:1px;
    classDef app fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef domain fill:#fff3cd,stroke:#ffc107,stroke-width:1px;
    classDef infra fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef external fill:#f8f9fa,stroke:#adb5bd,stroke-width:1px;
```
