# matiasfmart/product-comparison architecture

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

- Interactive diagram: https://gitdiagram.com/matiasfmart/product-comparison
- Repository: https://github.com/matiasfmart/product-comparison

## Overview

##### Project type and purpose
- This is a backend-only REST API built on .NET 8 Minimal APIs.
- Purpose: expose a single “compare products” endpoint (`GET /api/v1/products`) that reads product data from a local JSON file and returns details for multiple product IDs.
- Emphasis on best practices: vertical-slice design, hexagonal (ports/adapters) style, uniform RFC-7807 error handling, ETag-based conditional caching, structured logging with correlation IDs, and a full test suite (unit, integration, E2E).

##### File structure
- Top level
- src/ApiHost – Minimal API host and startup (HTTP configuration, middleware, Swagger, versioning)
- src/BuildingBlocks – Shared utilities
– Configuration/DataOptions (JSON file path)
– Errors/ProblemDetailsExtensions (RFC-7807 support)
- src/Feature.Products – Vertical-slice for “GetByIds” feature
– Domain/Product entity
– Infrastructure/IProductRepository & JsonProductRepository
– GetByIds/ (endpoint, handler, request/response DTOs, validator)
- data/products.json – sample data source on disk
- docs/ – design notes, run instructions, AI prompts
- test/ – three separate test projects (unit tests for validator/handler/repo, integration tests for JsonProductRepository, E2E tests using WebApplicationFactory)
- Config files: appsettings.json, launchSettings.json for dev and tests

##### README for additional insights
- Architectural decisions spelled out: Minimal APIs + Asp.Versioning, vertical slices, hexagonal concepts.
- Error handling: global middleware + slice-level ProblemDetails.
- Caching flow: SHA-256 ETag generated by the repository, returned in response, supports 304 Not Modified.
- Observability: request logging, latency, business logs, correlation IDs.
- Tests pyramid defined and how they run.

a. Main components
- API Host Layer
– HTTP Server (Kestrel)
– Middleware pipeline:
· Correlation-ID & structured logging middleware
· Error-handling middleware (ProblemDetails global handler)
· Routing & versioning (api/v{version}/products)
– Swagger/OpenAPI
- Feature.Products Vertical Slice
– Endpoint adapter (HTTP → Request DTO)
– Validator (fail-fast input validation)
– Handler (application use case)
- Infrastructure (ports/adapters)
– IProductRepository (interface)
– JsonProductRepository (reads data/products.json, maintains in-memory index, computes ETag, handles reload lock)
- Domain
– Product entity, Money/value objects
- Data Source
– Local JSON file (data/products.json)
- External Clients
– UI or CDN caching layers that consume the API
- Tests (optional to show)
– Unit tests, integration tests, E2E via WebApplicationFactory

b. Relationships and data flow
1. Client → HTTP Server
2. Middleware (correlation ID, logging) → Router
3. Router → GET /api/v1/products endpoint
4. Endpoint → Validator → Handler
5. Handler → IProductRepository → JsonProductRepository
6. JsonProductRepository reads JSON file or memory cache, computes ETag
7. Repository returns domain models → Handler maps to response DTO
8. Endpoint sets ETag header and status (200/304/400/404) → HTTP Response → Client

c. Architectural patterns and principles
- Vertical Slice: group code by feature, not by technical layer
- Hexagonal (Ports & Adapters): decouple business logic (handler + domain) from external concerns (HTTP, JSON store) via interfaces
- Middleware pipeline: cross-cutting concerns (logging, error handling, correlation)
- Fail-fast validation with FluentValidator or custom validator
- RFC-7807 ProblemDetails for uniform error contracts
- ETag conditional caching for performance

d. Key technologies/frameworks
- .NET 8 Minimal APIs
- Asp.Versioning for API versioning
- Swashbuckle/Swagger for documentation
- SHA-256 for strong ETag
- ReaderWriterLockSlim in repository for safe reloads
- xUnit/NUnit (or chosen test framework) for unit, integration, E2E
- WebApplicationFactory for HTTP contract tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Client<br/>(UI/CDN)"]:::external

    %% API Host Layer
    subgraph "API Host Layer" 
        direction TB
        Program["Program.cs"]:::http
        HealthSetup["HealthSetup.cs"]:::http
        SwaggerSetup["SwaggerSetup.cs"]:::http
        AppSettings["appsettings.json"]:::http
        LaunchSettings["launchSettings.json"]:::http
        Kestrel["Kestrel HTTP Server"]:::http
        Middleware_Correlation["Correlation-ID & Logging Middleware"]:::http
        Middleware_Error["Error-Handling Middleware"]:::http
        Routing["Routing & Versioning"]:::http
        Swagger["Swagger/OpenAPI"]:::http
        Health["Health Endpoints"]:::http
    end

    %% Building Blocks
    subgraph "BuildingBlocks" 
        direction TB
        DataOptions["DataOptions.cs"]:::build
        ProblemDetailsExt["ProblemDetailsExtensions.cs"]:::build
    end

    %% Feature.Products Vertical Slice
    subgraph "Feature.Products" 
        direction TB
        subgraph "GetByIds Slice"
            direction TB
            Endpoint["GetByIdsEndpoint.cs"]:::app
            RequestDTO["GetByIdsRequest.cs"]:::app
            ResponseDTO["GetByIdsResponse.cs"]:::app
            Validator["GetByIdsValidator.cs"]:::app
            Handler["GetByIdsHandler.cs"]:::app
        end
        ProductEntity["Product.cs"]:::app
    end

    %% Infrastructure
    subgraph "Infrastructure (Ports & Adapters)"
        direction TB
        IProductRepo["IProductRepository.cs"]:::infra
        JsonRepo["JsonProductRepository.cs"]:::infra
    end

    %% Data Source
    DataFile["products.json"]:::infra_datastore

    %% Tests
    subgraph "Tests"
        direction TB
        subgraph "Unit Tests"
            direction TB
            UT_Validator["GetByIdsValidatorTests.cs"]:::test
            UT_Handler["GetByIdsHandlerTests.cs"]:::test
            UT_Repo["JsonProductRepositoryTests.cs"]:::test
        end
        subgraph "Integration Tests"
            direction TB
            IT_Factory["ApiFactory.cs"]:::test
            IT_Tests["ProductsApiIntegrationTests.cs"]:::test
        end
        subgraph "End-to-End Tests"
            direction TB
            E2E_Program["Program.cs"]:::test
            E2E_Http["ApiHost.http"]:::test
            E2E_AppSettings["appsettings.json"]:::test
            E2E_LaunchSettings["launchSettings.json"]:::test
        end
    end

    %% Data Flow
    Client -->|requests GET /api/v1/products| Kestrel
    Kestrel --> Middleware_Correlation
    Middleware_Correlation --> Middleware_Error
    Middleware_Error --> Routing
    Routing --> Endpoint
    Endpoint --> Validator
    Validator --> Handler
    Handler --> IProductRepo
    IProductRepo --> JsonRepo
    JsonRepo --> DataFile
    JsonRepo --> Handler
    Handler --> ResponseDTO
    ResponseDTO --> Endpoint
    Endpoint -->|response with ETag| Client

    %% Click Events
    click Program "https://github.com/matiasfmart/product-comparison/blob/master/src/ApiHost/Program.cs"
    click HealthSetup "https://github.com/matiasfmart/product-comparison/blob/master/src/ApiHost/Extensions/HealthSetup.cs"
    click SwaggerSetup "https://github.com/matiasfmart/product-comparison/blob/master/src/ApiHost/Extensions/SwaggerSetup.cs"
    click AppSettings "https://github.com/matiasfmart/product-comparison/blob/master/src/ApiHost/appsettings.json"
    click LaunchSettings "https://github.com/matiasfmart/product-comparison/blob/master/src/ApiHost/Properties/launchSettings.json"
    click DataOptions "https://github.com/matiasfmart/product-comparison/blob/master/src/BuildingBlocks/Configuration/DataOptions.cs"
    click ProblemDetailsExt "https://github.com/matiasfmart/product-comparison/blob/master/src/BuildingBlocks/Errors/ProblemDetailsExtensions.cs"
    click ProductEntity "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/Domain/Product.cs"
    click Endpoint "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/GetByIds/GetByIdsEndpoint.cs"
    click RequestDTO "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/GetByIds/GetByIdsRequest.cs"
    click ResponseDTO "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/GetByIds/GetByIdsResponse.cs"
    click Validator "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/GetByIds/GetByIdsValidator.cs"
    click Handler "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/GetByIds/GetByIdsHandler.cs"
    click IProductRepo "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/Infrastructure/IProductRepository.cs"
    click JsonRepo "https://github.com/matiasfmart/product-comparison/blob/master/src/Feature.Products/Infrastructure/JsonProductRepository.cs"
    click DataFile "https://github.com/matiasfmart/product-comparison/blob/master/data/products.json"
    click UT_Validator "https://github.com/matiasfmart/product-comparison/blob/master/test/Products.UnitTests/GetByIdsValidatorTests.cs"
    click UT_Handler "https://github.com/matiasfmart/product-comparison/blob/master/test/Products.UnitTests/GetByIdsHandlerTests.cs"
    click UT_Repo "https://github.com/matiasfmart/product-comparison/blob/master/test/Products.UnitTests/JsonProductRepositoryTests.cs"
    click IT_Factory "https://github.com/matiasfmart/product-comparison/blob/master/test/Products.IntegrationTests/ApiFactory.cs"
    click IT_Tests "https://github.com/matiasfmart/product-comparison/blob/master/test/Products.IntegrationTests/ProductsApiIntegrationTests.cs"
    click E2E_Program "https://github.com/matiasfmart/product-comparison/blob/master/test/ApiHost/Program.cs"
    click E2E_Http "https://github.com/matiasfmart/product-comparison/blob/master/test/ApiHost/ApiHost.http"
    click E2E_AppSettings "https://github.com/matiasfmart/product-comparison/blob/master/test/ApiHost/appsettings.json"
    click E2E_LaunchSettings "https://github.com/matiasfmart/product-comparison/blob/master/test/ApiHost/Properties/launchSettings.json"

    %% Styles
    classDef external fill:#d0e7ff,stroke:#333,stroke-width:1px
    classDef http fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef app fill:#d4edda,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef infra_datastore fill:#ffdead,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef test fill:#f0f0f0,stroke:#333,stroke-width:1px
```
