pos-system/services/_template_dot_net/docs/en/ARCHITECTURE.md

Architecture Documentation

Detailed architecture documentation for the .NET 10 Microservice Template.

Architecture Overview

graph TB
    subgraph "API Layer"
        C[Controllers]
        CMD[Commands]
        Q[Queries]
        B[Behaviors]
        V[Validations]
    end
    
    subgraph "Domain Layer"
        AR[Aggregate Roots]
        E[Entities]
        VO[Value Objects]
        DE[Domain Events]
        DX[Domain Exceptions]
    end
    
    subgraph "Infrastructure Layer"
        DB[(PostgreSQL)]
        R[Repositories]
        CTX[DbContext]
        ID[Idempotency]
    end
    
    C --> CMD
    C --> Q
    CMD --> B --> V
    CMD --> AR
    Q --> R
    R --> CTX --> DB
    AR --> DE
    R --> AR
    
    style C fill:#4a90d9,stroke:#2d5986,color:#fff
    style AR fill:#50c878,stroke:#2d8659,color:#fff
    style DB fill:#ff6b6b,stroke:#c0392b,color:#fff

Layer Responsibilities

1. Domain Layer (MyService.Domain)

The heart of the application containing pure business logic. This layer:

• Has ZERO external dependencies (except MediatR.Contracts for events)
• Contains only POCO classes
• Implements DDD tactical patterns

Components

Component	Purpose
SeedWork	Base classes: Entity, ValueObject, Enumeration, IAggregateRoot
AggregatesModel	Aggregate roots with their entities and value objects
Events	Domain events for cross-aggregate communication
Exceptions	Domain-specific exceptions for business rule violations

2. Infrastructure Layer (MyService.Infrastructure)

Technical implementations and external concerns:

• Database access (EF Core)
• Repository implementations
• External service integrations

3. API Layer (MyService.API)

Application entry point and CQRS implementation:

• Controllers for HTTP handling
• Commands for write operations
• Queries for read operations
• MediatR behaviors for cross-cutting concerns

CQRS Flow

sequenceDiagram
    participant Client
    participant Controller
    participant MediatR
    participant LoggingBehavior
    participant ValidatorBehavior
    participant TransactionBehavior
    participant CommandHandler
    participant Repository
    participant DbContext
    
    Client->>Controller: HTTP Request
    Controller->>MediatR: Send(Command)
    MediatR->>LoggingBehavior: Handle
    LoggingBehavior->>ValidatorBehavior: Next()
    ValidatorBehavior->>TransactionBehavior: Next()
    TransactionBehavior->>CommandHandler: Next()
    CommandHandler->>Repository: Add/Update/Delete
    Repository->>DbContext: SaveEntitiesAsync()
    DbContext-->>Repository: Success
    Repository-->>CommandHandler: Result
    CommandHandler-->>Controller: Response
    Controller-->>Client: HTTP Response

Domain Events

graph LR
    AR[Aggregate Root] -->|Raises| DE[Domain Event]
    DE -->|Dispatched by| CTX[DbContext]
    CTX -->|Publishes to| M[MediatR]
    M -->|Handled by| H1[Handler 1]
    M -->|Handled by| H2[Handler 2]
    
    style AR fill:#50c878,stroke:#2d8659,color:#fff
    style DE fill:#f39c12,stroke:#d68910,color:#fff
    style M fill:#9b59b6,stroke:#7d3c98,color:#fff

Database Schema

Sample Aggregate

erDiagram
    samples {
        uuid id PK
        varchar(200) name
        varchar(1000) description
        int status_id FK
        timestamp created_at
        timestamp updated_at
    }
    
    sample_statuses {
        int id PK
        varchar(50) name
    }
    
    samples ||--o{ sample_statuses : has

MediatR Pipeline

Request → LoggingBehavior → ValidatorBehavior → TransactionBehavior → Handler → Response
            │                     │                    │
            ▼                     ▼                    ▼
       Log start/end         Validate           Begin/Commit
       + timing              with                Transaction
                            FluentValidation

Behavior Order

1. LoggingBehavior - Logs request handling with timing
2. ValidatorBehavior - Validates request using FluentValidation
3. TransactionBehavior - Wraps command handlers in database transactions

Error Handling

Exception Hierarchy

Exception
└── DomainException
    └── SampleDomainException

Problem Details (RFC 7807)

All errors are returned in Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "Name": ["Name is required"]
  }
}

Health Checks

graph TD
    HC[Health Check Endpoint]
    HC --> |/health/live| L[Liveness]
    HC --> |/health/ready| R[Readiness]
    HC --> |/health| F[Full Status]
    
    R --> PG[(PostgreSQL)]
    R --> RD[(Redis)]
    
    style HC fill:#3498db,stroke:#2980b9,color:#fff
    style L fill:#2ecc71,stroke:#27ae60,color:#fff
    style R fill:#f39c12,stroke:#d68910,color:#fff

Deployment Architecture

Docker Compose (Local)

services:
  myservice-api:
    build: .
    ports: ["5000:8080"]
    depends_on:
      - postgres
      - redis
  
  postgres:
    image: postgres:16-alpine
    
  redis:
    image: redis:7-alpine

Kubernetes (Production)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myservice-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: myservice:latest
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080

Security Considerations

1. Authentication: JWT Bearer token (configure in production)
2. Authorization: Role-based access control
3. Input Validation: FluentValidation on all requests
4. SQL Injection: EF Core parameterized queries
5. Secrets: Environment variables, never in code

Performance Optimization

1. Connection Pooling: EF Core with Npgsql connection resilience
2. Async/Await: All I/O operations are async
3. Response Caching: Add caching headers for queries
4. Database Indexes: Configure in EntityConfigurations

References

• eShopOnContainers
• .NET Microservices Architecture Guide
• Domain-Driven Design
• CQRS Pattern