How matiasfmart/product-comparison works
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