How domoar/northwind-api works
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.