Skip to main content

Backend Documentation

This directory contains technical documentation for the backend components of the arolariu.ro platform.

Overview​

The backend is built using:

  • Framework: .NET 10.0 (LTS)
  • Language: C# 13 with modern language features
  • Architecture: Modular Monolith
  • Design Patterns: Domain-Driven Design (DDD) + SOLID principles
  • API Style: ASP.NET Core Minimal APIs
  • Testing: xUnit

Architecture​

Modular Monolith Structure​

src/
├── Core/              # Application entry point and pipeline configuration
├── Core.Auth/         # Authentication domain
├── Common/            # Shared infrastructure and cross-cutting concerns
└── Invoices/          # Invoices domain (business logic)

Domain-Driven Design Principles​

  • Bounded Contexts: Clear service boundaries
  • Aggregates: Root entities maintaining consistency
  • Value Objects: Immutable domain concepts
  • Domain Events: Business-significant state changes
  • Domain Services: Complex operations across aggregates
  • Repositories: Aggregate persistence abstraction
  • Ubiquitous Language: Consistent business terminology

SOLID Principles​

  • Single Responsibility Principle
  • Open/Closed Principle
  • Liskov Substitution Principle
  • Interface Segregation Principle
  • Dependency Inversion Principle

RFCs (Request for Comments)​

Backend RFCs are numbered 2000-2999 and located in /docs/rfc/.

Implemented RFCs​

RFC #TitleStatusDateDescription
2001Domain-Driven Design Architecture✅ Implemented2025-10-12Complete DDD architecture with modular monolith, SOLID principles, and bounded contexts
2002OpenTelemetry Backend Observability✅ Implemented2025-10-12Backend distributed tracing with OpenTelemetry, Activity API, and Azure Application Insights
2003The Standard Implementation✅ Implemented2025-01-26Implementation of Hassan Habib's Standard with Brokers, Foundation, Processing, and Orchestration layers
2004XML Documentation Standard✅ Implemented2025-01-26Comprehensive XML documentation standard for C# public APIs

Proposed RFCs​

None currently.

Draft RFCs​

None currently.

Quick Start Guides​

Practical, concise guides for rapid development:

  • OpenTelemetry Guide - Activity tracing, tags, events, and Azure Application Insights integration

Key Topics​

Architecture Patterns​

  • Modular monolith organization
  • DDD aggregate design
  • Domain event handling
  • Repository pattern implementation
  • Dependency injection strategies

API Design​

  • Minimal API patterns
  • RESTful conventions
  • GraphQL endpoints (if implemented)
  • gRPC services (if implemented)
  • API versioning strategy

Data Access​

  • Entity Framework Core usage
  • Database migrations
  • Query optimization
  • Transaction management
  • Caching strategies

Authentication & Authorization​

  • JWT token validation
  • Role-based access control
  • External identity providers
  • API key management

Testing​

  • Unit testing with xUnit
  • Integration testing patterns
  • Test naming conventions: MethodName_Condition_ExpectedResult()
  • Test coverage standards (85%+)
  • Mocking strategies

Observability​

  • Structured logging
  • OpenTelemetry integration (see OpenTelemetry Guide, RFC 2002)
  • Health checks
  • Metrics collection

Security​

  • Input validation
  • SQL injection prevention
  • XSS protection
  • CSRF protection
  • Secrets management
  • GDPR/LGPD compliance

Domains​

General Domain (Core Infrastructure)​

Responsibilities:

  • Application bootstrapping
  • Middleware pipeline
  • CORS configuration
  • Authentication/Authorization setup
  • Logging and telemetry
  • Health checks
  • OpenAPI/Swagger documentation

Invoices Domain​

Responsibilities:

  • Invoice CRUD operations
  • Merchant management
  • Product/line item handling
  • Invoice metadata
  • Business rule validation

Key Aggregates:

  • Invoice (root)
  • Merchant
  • Product

Authentication Domain (Core.Auth)​

Responsibilities:

  • User authentication
  • Authorization policies
  • JWT token management
  • External provider integration
  • Site README: /sites/api.arolariu.ro/README.md - Development setup guide
  • API Documentation: /sites/docs.arolariu.ro/api/ - Generated XML documentation
  • Copilot Instructions: /.github/instructions/backend.instructions.md - DDD & SOLID guidelines
  • Infrastructure: /infra/Azure/Bicep/ - Azure deployment configurations

Creating Backend RFCs​

When creating a new backend RFC:

  1. Use the RFC template from /docs/RFC_TEMPLATE.md
  2. Number it in the 2000-2999 range (2002, 2003, etc.)
  3. Place in /docs/rfc/
  4. Update this README with the new RFC entry
  5. Submit for review

Suggested Topics for Future RFCs​

  • RFC 2002: Domain event architecture and implementation
  • RFC 2003: Repository pattern and data access strategy
  • RFC 2004: API versioning and backward compatibility
  • RFC 2005: Background job processing architecture
  • RFC 2006: Multi-tenancy implementation
  • RFC 2007: Caching strategy (distributed cache, in-memory)
  • RFC 2008: Rate limiting and throttling
  • RFC 2009: Audit logging and compliance
  • RFC 2010: Database migration strategy
  • RFC 2011: Error handling and response standardization

Code Quality Standards​

All backend code must follow:

  • ✅ DDD principles and patterns
  • ✅ SOLID design principles
  • ✅ Ubiquitous language from business domain
  • ✅ Test naming: MethodName_Condition_ExpectedResult()
  • ✅ XML documentation for public APIs
  • ✅ 85%+ code coverage for domain and application layers
  • ✅ async/await for I/O-bound operations
  • ✅ Proper exception handling and logging

Questions?​

For backend-specific questions:

  • Check existing RFCs (when available)
  • Review site README
  • Review DDD/SOLID instructions
  • Open a GitHub issue
  • Contact: admin@arolariu.ro

Last Updated: 2025-12-25 Maintained By: Backend team

// was this page useful?