# melandel/dotnet-web-service architecture

> Architecture diagram of the GitHub repository melandel/dotnet-web-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/melandel/dotnet-web-service
- Repository: https://github.com/melandel/dotnet-web-service

## Overview

##### Project type and purpose
- This is a single‐service ASP .NET Core Web API (a “monolith”) whose only responsibility is to expose HTTP endpoints to return greeting messages.
- There is no database or UI in this repo—just a backend API, a shared cross‐cutting library, a battery of in‐process tests, plus documentation (architecture decision logs) and CI/CD scripts.

##### Key components
a. External Client
- Any HTTP client (curl, Postman, browser) invoking the greeting endpoint.
b. ASP .NET Core Web Service
- Program.cs / Startup logic (web host, Kestrel).
- Middleware pipeline:
– Routing (Kebab-case converter)
– Error-handling middleware (translates exceptions into RFC 7807 ProblemDetails)
– Enum-handling filters and JSON serialization options.
– Swagger/OpenAPI generator & UI.
- Controllers (ApiController.cs) implementing endpoints.
- Configuration (appsettings.json / launchSettings.json).
c. Cross-Cutting Concerns Library
- Shared types and converters (constrained types, enum naming conventions, JSON converters, error-handling types).
- Referenced by the API project to enforce policies.
d. Test Project (FearlessProgramming Tests)
- In‐memory test server to simulate HTTP requests.
- Test doubles, test archetypes, coding-standards suites, routing and error-handling suites.
e. Documentation & CI/CD
- adl/ (Architecture Decision Records)
- cicd/ (build and deployment scripts or guidance)

##### How these components interact
- The HTTP client issues a request → Kestrel receives it → ASP .NET middleware pipeline applies routing, filters, error handlers, JSON settings → Controller executes business logic (constructs greeting string) → Response passes back through middleware to client.
- The API project references the Cross-Cutting Concerns library to share serialization rules and error types.
- The Test Project spins up an in-memory host of the API to exercise the full pipeline and validate policies.
- CI/CD scripts build both API and Test projects, run tests, and (optionally) package/deploy the API.

##### Architectural patterns and principles
- Middleware pipeline (chain of responsibility) for cross-cutting policies.
- Feature-folder organization in the API (controllers + concerns grouped by functionality).
- “Clean” separation of concerns: serialization, routing, error handling, swagger setup all in dedicated extension methods or filters.
- In-process integration testing via test server and test doubles, enforcing “nothing-up-your-sleeve” transparency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    EC["External Client"]:::external

    subgraph "API Host"
        direction TB
        Program["Program.cs / Startup"]:::api
        Config["appsettings.json<br/>launchSettings.json"]:::config
        subgraph "Middleware Pipeline"
            direction TB
            Routing["Routing (Kebab-case)"]:::middleware
            ErrorHandling["Error-handling"]:::middleware
            EnumHandling["Enum-handling filters & JSON options"]:::middleware
            SwaggerUI["Swagger/OpenAPI generator & UI"]:::middleware
        end
        Controller["Controllers (ApiController.cs)"]:::api
    end

    CrossCutting["Cross-Cutting Library"]:::library
    TestHarness["Test Harness<br/>(In-memory Test Server)"]:::test
    subgraph "Repository Documentation & Workflow"
        direction TB
        ADR["adl/"]:::doc
        CICD["cicd/"]:::doc
    end

    EC -->|"HTTP"| Program
    Program -->|"references"| CrossCutting
    Program -->|"runs tests against"| TestHarness
    CICD -->|"build & deploy"| Program
    CICD -->|"run tests"| TestHarness

    class EC external
    class Program,Controller api
    class Config config
    class Routing,ErrorHandling,EnumHandling,SwaggerUI middleware
    class CrossCutting library
    class TestHarness test
    class ADR,CICD doc

    click Program "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Program.cs"
    click Controller "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/ApiController.cs"
    click Config "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/appsettings.json"
    click Config "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Properties/launchSettings.json"
    click Routing "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Concerns/Routing/AttributeRouteTokenReplacement/KebabCaseConverter.cs"
    click ErrorHandling "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Concerns/ErrorHandling/Middlewares/ReturnProblemDetailsWhenExceptionIsThrown.cs"
    click EnumHandling "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Concerns/EnumsHandling/ActionFilters/ProhibitEnumsPassedAsIntegersInRouteOrQueryStringAttribute.cs"
    click SwaggerUI "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Api/Concerns/SwaggerUI/ConfigureSwaggerOptions.cs"
    click CrossCutting "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.CrossCuttingConcerns/Mel.DotnetWebService.CrossCuttingConcerns.csproj"
    click TestHarness "https://github.com/melandel/dotnet-web-service/blob/main/src/Mel.DotnetWebService.Tests.FearlessProgramming/TestEnvironments/TestServers/InMemoryTestServer.cs"
    click ADR "https://github.com/melandel/dotnet-web-service/tree/main/adl/"
    click CICD "https://github.com/melandel/dotnet-web-service/tree/main/cicd/"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef config fill:#eef,stroke:#333,stroke-width:1px
    classDef middleware fill:#fcf,stroke:#333,stroke-width:1px
    classDef library fill:#cfc,stroke:#333,stroke-width:1px
    classDef test fill:#fcc,stroke:#333,stroke-width:1px
    classDef doc fill:#ffe,stroke:#333,stroke-width:1px
```
