How qurtuba-team/bookorbit-backend works
1. Overall shape
- This is a layered ASP.NET Core 9 backend organized as Clean Architecture + DDD + CQRS.
- The solution is split into four main runtime projects: Api, Application, Domain, and Infrastructure.
- Dependencies point inward: the API depends on Application/Infrastructure, Infrastructure depends on Application/Domain, and Domain stays framework-light.
2. Request entry point
- HTTP traffic enters BookOrbit.Api through feature-based controllers under /api/v1/....
- Controllers are thin: they accept request contracts, send commands/queries through MediatR, and translate Result<T> responses into HTTP results.
- Presentation-specific concerns live here: request DTOs, OpenAPI transformers, exception middleware, request logging middleware, rate limiting, and error-to-ProblemDetails mapping.
3. Application layer as use-case orchestration
- BookOrbit.Application contains the actual use cases, organized by feature folders such as Books, Students, BorrowingRequests, BorrowingTransactions, Identity, Chat, Notifications, and OTPs.
- Each feature follows CQRS: commands change state, queries read projections.
- Most features have handlers, validators, DTOs, and optional event handlers.
- Cross-cutting MediatR pipeline behaviors handle validation, caching, logging, performance timing, and unhandled exception capture.
4. Domain model boundaries
- BookOrbit.Domain holds the business model: aggregates, value objects, enums, domain errors, and domain events.
- Main aggregates include Student, Book, BookCopy, LendingListRecord, BorrowingRequest, BorrowingTransaction, BorrowingReview, PointTransaction, ChatGroup, ChatMessage, Notification, Otp, OutboxMessage, and RefreshToken.
- The model emphasizes explicit state machines and factory methods so invalid state is hard to create.
5. Core business flow
- The main domain flow is: book cataloging → copy registration → lending listing → borrowing request → transaction → review → point settlement.
- Book and student lifecycles are managed through state transitions in application commands.
- Borrowing requests and transactions drive most of the system’s business rules, including expiration, return/lost handling, and points changes.
6. Persistence and data access
- BookOrbit.Infrastructure owns EF Core, SQL Server persistence, entity configuration, migrations, and the AppDbContext.
- The application layer depends on IAppDbContext; Infrastructure provides the concrete DbContext implementation.
- Domain events are dispatched during SaveChanges, so persistence is also the handoff point from state changes to side effects.
7. Side effects and integration services
- Infrastructure implements the ports defined by Application: identity, email, image handling, OTP generation/verification, masking, route building, serialization, student queries, system notifications, and caching.
- External integrations include SMTP email, JWT signing, and file storage for book/student images under the API’s upload/static folders.
- The chat subsystem also includes a real-time service and SignalR hub, so chat messages are not just stored; they can be pushed live.
8. AuthN/AuthZ architecture
- Authentication is JWT-based with refresh token rotation backed by the database.
- Authorization is policy-driven and based on roles, user/student state, ownership, and entity relationships.
- Policies are implemented as dedicated requirements/handlers in Infrastructure and applied at controller action level.
9. Caching and query optimization
- Read-heavy use cases use a caching pipeline with HybridCache and tag-based invalidation.
- Cached queries define cache keys, TTLs, and tags; mutation commands invalidate by tag after successful writes.
- List endpoints use a shared paged-query pattern with filtering, searching, sorting, and projection into DTOs.
10. Consistency, events, and background jobs
- The system uses domain events for internal reactions such as student creation, borrowing request changes, transaction state changes, and review creation.
- There is also an outbox message subsystem, with a background service that processes pending messages.
- Another background job marks expirable entities, supporting time-based lifecycle transitions.
11. Operational boundaries
- The repo is prepared for containerized deployment with Docker Compose.
- The compose stack includes the API, SQL Server, Seq for logs, Prometheus for metrics, Grafana for dashboards, and Jaeger for traces.
- The API exposes /health and /metrics, and OpenTelemetry/Serilog are wired for observability and correlation.
12. Testing structure
- Tests are split into Domain unit tests, Application unit tests, and Application subcutaneous tests.
- Domain tests focus on invariants and state transitions.
- Subcutaneous tests exercise feature flows through MediatR and the application pipeline, which makes them useful for validating architecture-level behavior.
13. Key diagram boundaries to draw
- Draw a hard boundary around Domain for pure business rules.
- Draw Application as the orchestration layer between HTTP and persistence.
- Draw Infrastructure as the adapter layer to SQL Server, email, files, auth, caching, real-time chat, and background processing.
- Draw API as the thin presentation edge that handles transport, auth, routing, rate limits, and error formatting.
Main entry points: BookOrbit.Application BookOrbit.Application · BookOrbit.Infrastructure BookOrbit.Infrastructure · BookOrbit.Api BookOrbit.Api · BookOrbit.Domain BookOrbit.Domain
Components 26
API
HTTP edge, transport concerns, and request/response mapping.
- BookOrbit.Api · Thin HTTP presentation layer with controllers, middleware, OpenAPI, and request contracts.
Code/BookOrbit.Api - Controllers · Feature-based controllers for books, students, borrowing, chat, identity, images, and notifications.
Code/BookOrbit.Api/Controllers - Middleware · Exception handling, request logging, rate limiting, and ProblemDetails mapping.
Code/BookOrbit.Api/Middlewares - Contracts · API request models and paging/filter contracts used by controllers.
Code/BookOrbit.Api/Contracts/Requests - OpenAPI · Swagger/OpenAPI transformers for bearer auth and version metadata.
Code/BookOrbit.Api/OpenApi/Transformers
Application
CQRS use-case orchestration, policies, and pipeline behaviors.
- BookOrbit.Application · Use-case orchestration layer built around MediatR, validation, caching, and event handlers.
Code/BookOrbit.Application - Pipeline · Validation, caching, logging, performance timing, and unhandled exception behaviors.
Code/BookOrbit.Application/Common/Behaviours - Ports · Abstractions for DB, cache, identity, email, images, OTPs, routes, serialization, chat, and notifications.
Code/BookOrbit.Application/Common/Interfaces - Books · Book catalog use cases with commands, queries, and DTO projections.
Code/BookOrbit.Application/Features/Books - Borrowing · Borrowing requests, transactions, reviews, and transaction events orchestration.
Code/BookOrbit.Application/Features/BorrowingTransactions - Students · Student lifecycle, public/profile queries, and state transitions.
Code/BookOrbit.Application/Features/Students - Identity · Tokens, password reset, email confirmation, and authentication workflows.
Code/BookOrbit.Application/Features/Identity - Chat · Chat commands and queries for groups, history, and message state.
Code/BookOrbit.Application/Features/Chat - Notifications · Notification queries and read-state commands.
Code/BookOrbit.Application/Features/Notifications
Domain
Framework-light business model and invariants.
- BookOrbit.Domain · Pure business model with aggregates, value objects, enums, errors, and domain events.
Code/BookOrbit.Domain - Core Flow · Cataloging books, registering copies, listing for lending, requesting, transacting, reviewing, and settling points.
Code/BookOrbit.Domain - Domain Events · Student, borrowing, review, transaction, and outbox events used for internal reactions and side effects.
Code/BookOrbit.Domain
Infrastructure
Persistence, integrations, auth, caching, real-time, and background processing.
- BookOrbit.Infrastructure · Persistence and external service adapters, plus policies and background services.
Code/BookOrbit.Infrastructure - Data · AppDbContext, entity configurations, migrations, and save-time interception.
Code/BookOrbit.Infrastructure/Data - Services · Email, image, OTP, cache, chat, masking, routing, serialization, student query, and system notification services.
Code/BookOrbit.Infrastructure/Services - AuthZ · Identity service, token provider, refresh tokens, and policy requirements/handlers.
Code/BookOrbit.Infrastructure/Identity - Background Jobs · Outbox processing and expirable-entity marking jobs.
Code/BookOrbit.Infrastructure/BackgroundJobs - Realtime Chat · Chat hub and real-time delivery service for live message push.
Code/BookOrbit.Infrastructure/Services/ChatServices
Tests
Unit and subcutaneous verification layers.
- Domain Tests · Invariant and state-transition tests for aggregates and value objects.
Tests/BookOrbit.Domain.UnitTests - App Tests · Application-level mapper and orchestration tests.
Tests/BookOrbit.Application.UnitTests - Subcutaneous · End-to-end feature tests through MediatR and the application pipeline.
Tests/BookOrbit.Application.SubcutaneousTests
Connections 32
- BookOrbit.Api → Controllers: hosts · Controllers implement the HTTP entry points.
- BookOrbit.Api → Middleware: uses · Central request/error handling is wired at the API edge.
- BookOrbit.Api → Contracts: binds · Incoming requests are mapped from transport DTOs.
- BookOrbit.Api → OpenAPI: describes · OpenAPI transformers shape the published contract.
- Controllers → BookOrbit.Application: sends · Controllers dispatch commands and queries through MediatR.
- Middleware → BookOrbit.Application: normalizes errors · Exception handling translates failures into HTTP problems.
- BookOrbit.Application → Pipeline: wraps · MediatR behaviors apply across all use cases.
- BookOrbit.Application → Ports: depends on · Use cases target abstractions rather than concrete services.
- BookOrbit.Application → BookOrbit.Domain: models rules · Application logic coordinates domain entities and state transitions.
- BookOrbit.Application → BookOrbit.Infrastructure: implemented by · Infrastructure provides concrete implementations of application ports.
- BookOrbit.Application → Books: contains · Book-related commands, queries, and DTOs.
- BookOrbit.Application → Borrowing: contains · Borrowing workflows and transaction/review logic.
- BookOrbit.Application → Students: contains · Student lifecycle and profile use cases.
- BookOrbit.Application → Identity: contains · Authentication, password, and token workflows.
- BookOrbit.Application → Chat: contains · Chat messaging and history use cases.
- BookOrbit.Application → Notifications: contains · Notification retrieval and read-state use cases.
- BookOrbit.Domain → Core Flow: encodes · The main business journey is captured in aggregates and state machines.
- BookOrbit.Domain → Domain Events: emits · Aggregates raise domain events for internal reactions.
- BookOrbit.Infrastructure → Data: persists · EF Core stores aggregates, projections, refresh tokens, and outbox records.
- BookOrbit.Infrastructure → Services: adapts · Concrete adapters implement application service ports.
- BookOrbit.Infrastructure → AuthZ: secures · JWT, refresh rotation, and policy requirements live here.
- BookOrbit.Infrastructure → Background Jobs: processes · Background services handle outbox and time-based lifecycle jobs.
- BookOrbit.Infrastructure → Realtime Chat: pushes · SignalR hub and real-time delivery support chat.
- Data → Domain Events: dispatches · Domain events are handed off around SaveChanges.
- Borrowing → Core Flow: drives · Borrowing commands coordinate the core lending lifecycle.
- Students → Domain Events: reacts to · Student event handlers respond to domain changes.
- Borrowing → Domain Events: reacts to · Borrowing event handlers coordinate follow-up actions.
- Identity → AuthZ: uses · Token and identity workflows depend on infrastructure services.
- Chat → Realtime Chat: publishes · Chat commands can trigger real-time message delivery.
- Domain Tests → BookOrbit.Domain: verifies · Unit tests validate pure business rules.
- App Tests → BookOrbit.Application: verifies · Unit tests cover application mappings and orchestration.
- Subcutaneous → BookOrbit.Application: exercises · Subcutaneous tests run feature flows through the full application stack.