# micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres architecture

> Architecture diagram of the GitHub repository micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres
- Repository: https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres

## Overview

##### Project type and purpose
- This is a high-performance, containerized backend API (“Rinha de Backend 2025”) implemented in .NET 10 with AOT for minimal startup time and resource usage.
- It exposes endpoints to enqueue payments, process them asynchronously, and return aggregated summaries under a distributed lock.

##### File structure
- src/backend: Contains the .NET solution with Program.cs, HTTP handlers (CountingHandler), domain models (Record.cs), services (PaymentService, PaymentProcessorService, PaymentBatchInserterService, PaymentSummaryService, ConsoleWriterService) and a RedisQueueWorker.
- Configuration files: appsettings.json, launchSettings.json, Dockerfile.
- Docker Compose files at src/: docker-compose.yml / override / .dcproj orchestrate four containers (backend, nginx, redis, postgres).
- init.sql seeds the PostgreSQL schema.
- nginx.conf configures the NGINX reverse proxy.

##### Extract architecture from README
- Two .NET AOT backend instances behind an NGINX load balancer.
- Redis acts as both message queue and backing store for the ReactiveLock distributed lock.
- PostgreSQL persists payments via bulk inserts (batch of 100).
- ReactiveLock synchronizes flushes before returning the payments summary.
- Services are built with Dapper.AOT, Polly for retries, and ReactiveLock.Distributed.Redis.

##### Main components & their relationships
a. External Client (HTTP/JSON)
b. NGINX Load Balancer (reverse proxy & round-robin)
c. Backend Instances (1 & 2)
- HTTP Handler → PaymentService enqueues to Redis
- RedisQueueWorker dequeues → PaymentProcessorService → PaymentBatchInserterService → PostgreSQL
- PaymentSummaryService under ReactiveLock reads from PostgreSQL → HTTP response
d. Redis
- Message queue for workers
- Backing store for ReactiveLock coordination
e. PostgreSQL
- Bulk insertion store for processed payments
f. ReactiveLock
- Distributed lock library coordinating flush + summary across instances

##### Architectural patterns & design principles
- Queue-based asynchronous processing (Redis ← HTTP enqueue)
- Bulk-write optimization for high throughput
- Distributed coordination (ReactiveLock) for consistency on summary reads
- Resilience and retry logic (Polly) on external calls
- Containerized deployment using Docker Compose
- Separation of concerns: Handlers → Services → Workers → Data stores

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client\n(HTTP/JSON)"]:::external

    %% Docker Compose Services
    subgraph "Docker Compose Services"
        direction TB
        NG["NGINX Load Balancer"]:::network
        BE1["Backend Instance 1\n.NET 10 AOT"]:::compute
        BE2["Backend Instance 2\n.NET 10 AOT"]:::compute
        RedisNode["Redis\n(Queue & Lock Store)"]:::storage
        Postgres["PostgreSQL"]:::storage
    end

    %% Coordination Component
    Lock["ReactiveLock\nDistributed (Redis)"]:::coord

    %% Backend Internal Flow
    subgraph "Backend Internal Components"
        direction TB
        H["CountingHandler"]:::compute
        PS["PaymentService"]:::compute
        RQW["RedisQueueWorker"]:::compute
        PPS["PaymentProcessorService"]:::compute
        PBIS["PaymentBatchInserterService"]:::compute
        PSS["PaymentSummaryService"]:::compute
        CWS["ConsoleWriterService"]:::compute
        DM["Record (Domain Model)"]:::model
        Config["Shared Config & Defaults"]:::config
    end

    %% Configuration & Scripts
    subgraph "Configuration & Scripts"
        direction TB
        AppConfig["appsettings.json"]:::config
        AppConfigDev["appsettings.Development.json"]:::config
        Launch1["Properties/launchSettings.json"]:::config
        Launch2["launchSettings.json"]:::config
        Dockerfile["Dockerfile"]:::container
        DCproj["docker-compose.dcproj"]:::container
        Init["init.sql"]:::storage
        SLN["Solution (.sln)"]:::config
        Workspace["Workspace (.code-workspace)"]:::config
    end

    %% Connections
    Client -->|"HTTP/80"| NG
    NG -->|"HTTP/5000 (RR)"| BE1
    NG -->|"HTTP/5000 (RR)"| BE2

    BE1 -->|"enqueue (TCP/6379)"| RedisNode
    BE2 -->|"enqueue (TCP/6379)"| RedisNode

    RedisNode -->|"dequeue loop"| RQW
    RQW -->|"process"| PPS
    PPS -->|"bulk insert\n(batch size=100)"| PBIS
    PBIS -->|"TCP/5432"| Postgres

    PSS -->|"select under lock"| Postgres
    PSS -->|"acquire/release"| Lock

    %% Internal flow to data stores
    H --> PS
    PS --> RedisNode
    CWS --> PS

    %% Subgraph linking internal to external
    BE1 --> H
    BE2 --> H
    BE1 --> CWS
    BE2 --> CWS
    BE1 --> PSS
    BE2 --> PSS

    %% Configuration links
    BE1 --> AppConfig
    BE1 --> AppConfigDev
    BE1 --> Launch1
    NG --> Launch2
    BE1 --> Dockerfile
    NG --> DCproj
    Postgres --> Init
    BE1 --> SLN
    BE1 --> Workspace

    %% Click Events
    click NG "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/nginx.conf"
    click NG "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/docker-compose.yml"
    click NG "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/docker-compose.override.yml"
    click BE1 "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Program.cs"
    click BE1 "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/backend.csproj"
    click H "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Handler/CountingHandler.cs"
    click DM "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Model/Record.cs"
    click PS "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Service/PaymentService.cs"
    click RQW "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Worker/RedisQueueWorker.cs"
    click PPS "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Service/PaymentProcessorService.cs"
    click PBIS "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Service/PaymentBatchInserterService.cs"
    click PSS "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Service/PaymentSummaryService.cs"
    click CWS "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Service/ConsoleWriterService.cs"
    click Config "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Shared/Constant.cs"
    click Config "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Shared/DefaultOptions.cs"
    click Config "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Shared/RunningPaymentsSummaryData.cs"
    click AppConfig "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/appsettings.json"
    click AppConfigDev "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/appsettings.Development.json"
    click Launch1 "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/backend/Properties/launchSettings.json"
    click Launch2 "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/launchSettings.json"
    click Dockerfile "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/tree/main/src/backend/Dockerfile"
    click DCproj "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/docker-compose.dcproj"
    click Init "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/init.sql"
    click SLN "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/rinha-de-backend-2025-dotnet-csharp.sln"
    click Workspace "https://github.com/micheloliveira-com/rinha-de-backend-2025-dotnet-csharp-postgres/blob/main/src/rinha-de-backend-2025-dotnet-csharp-postgres.code-workspace"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef network fill:#bbeeff,stroke:#333,stroke-width:1px
    classDef compute fill:#cceeff,stroke:#333,stroke-width:1px
    classDef storage fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef coord fill:#fff0b3,stroke:#333,stroke-width:1px
    classDef model fill:#ffe4b3,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef container fill:#d9f2d9,stroke:#333,stroke-width:1px
```
