108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
# TrakQR Architecture Guidelines
|
|
|
|
## Core Principles
|
|
|
|
### 1. Modular Monolith
|
|
The application is structured as a modular monolith where each feature/domain is self-contained but runs in a single deployable unit.
|
|
|
|
This provides:
|
|
- Clear boundaries between features
|
|
- Easy refactoring to microservices if needed later
|
|
- Simplified deployment and operations
|
|
|
|
### 2. Vertical Slice Architecture
|
|
Code is organized by **feature** (vertical slices), not by technical layer (horizontal).
|
|
|
|
Each feature contains everything it needs:
|
|
- Endpoint definitions
|
|
- Request/Response models
|
|
- Business logic
|
|
- Validators
|
|
|
|
```
|
|
/Features
|
|
/Auth
|
|
/Endpoints
|
|
SmallEndpoint.cs (contains Request, Response, Validator and Endpoint)
|
|
/Register
|
|
Endpoint.cs
|
|
Request.cs
|
|
Response.cs
|
|
Validator.cs
|
|
/Login
|
|
...
|
|
/Links
|
|
/Create
|
|
...
|
|
/List
|
|
...
|
|
/QRCodes
|
|
...
|
|
```
|
|
|
|
### 3. Minimal API with FastEndpoints
|
|
We use [FastEndpoints](https://fast-endpoints.com/) instead of traditional MVC Controllers because:
|
|
- Better performance (no reflection-based model binding)
|
|
- Cleaner, more focused endpoint classes
|
|
- Built-in validation with FluentValidation
|
|
- Request/Response DTOs are co-located with endpoints
|
|
- Easier testing
|
|
|
|
### 4. No Traditional Controllers
|
|
**DO NOT** use `[ApiController]` or `ControllerBase`. All HTTP endpoints must be FastEndpoints.
|
|
|
|
## Module Structure
|
|
|
|
Each feature module should be **fully self-contained**. All code related to a feature lives within that feature's folder:
|
|
|
|
```
|
|
/Features/{Module}/
|
|
- {Module}Responses.cs # Shared response DTOs for this module
|
|
- {Module}Settings.cs # Configuration classes for this module
|
|
/{Operation}/
|
|
- Endpoint.cs # The FastEndpoint class
|
|
- Request.cs # Input DTO
|
|
- Validator.cs # FluentValidation rules
|
|
```
|
|
|
|
**Example - Auth module:**
|
|
```
|
|
/Features/Auth/
|
|
- AuthResponses.cs # AuthResponse, UserInfo, MessageResponse
|
|
- JwtSettings.cs # JWT configuration
|
|
/Register/
|
|
- Endpoint.cs
|
|
- Request.cs
|
|
- Validator.cs
|
|
/Login/
|
|
- Endpoint.cs
|
|
- Request.cs
|
|
- Validator.cs
|
|
```
|
|
|
|
For simple operations, business logic lives directly in the Endpoint class. For complex logic, add a `Handler.cs` or `Service.cs` within the same feature folder.
|
|
|
|
## Shared Infrastructure
|
|
|
|
Only truly cross-cutting infrastructure goes outside Features:
|
|
- `/Data` - DbContext, migrations (shared database access)
|
|
- `/Models` - EF Core entities (shared domain model)
|
|
|
|
## Dependency Injection
|
|
|
|
- Use constructor injection
|
|
- Register services in `Program.cs` or feature-specific extension methods
|
|
- Prefer scoped services for request-specific work
|
|
|
|
## Validation
|
|
|
|
- Use FluentValidation via FastEndpoints' built-in support
|
|
- Validate at the endpoint level, not in services
|
|
- Return 400 Bad Request with structured error responses
|
|
|
|
## Authentication
|
|
|
|
- JWT Bearer tokens for API authentication
|
|
- Claims-based authorization
|
|
- User ID extracted from JWT `sub` claim
|