How olgaarenas22/routines works
1. Overall shape
- This is a .NET / ASP.NET Core service named Users.
- It is organized with a clear layering split: Controllers/API, Application, Domain, and Infrastructure.
- The codebase is centered on user profile/onboarding, faction selection, tutorial progression, and reacting to external fitness/routine events.
2. API boundary
- Users/Controllers/UsersController.cs is the main HTTP entry point.
- Request/response DTOs live under Users/Models/Requests and Users/Models/Responses.
- Program.cs and Extensions/DependencyInjectionExtensions.cs wire up the service, middleware, and dependencies.
3. Application layer as the orchestration boundary
- Users/Application/CommandHandler contains the main use-case handlers.
- These handlers implement user-facing flows such as:
- onboarding initialization
- username/profile updates
- gender, goal, height, weight, birth date, activity level, desired weight updates
- faction selection
- routine tutorial completion
- This layer coordinates domain services, repositories, validation, and event publication rather than talking directly to infrastructure.
4. Domain model
- Users/Domain/Entities holds the core persisted concepts:
- UserEntity
- FactionEntity, FactionMainStatEntity
- StatEntity
- UserTutorialProgressEntity
- outbox and processed-integration-event tracking entities
- Users/Domain/Enums defines user-related domain categories like Gender, Goal, ActivityLevel, FactionType, and StatType.
- Users/Domain/Repositories and Users/Domain/Services define the abstraction boundary the application depends on.
5. Business services
- Users/Application/Services contains the core domain logic services:
- UserService
- FactionService
- ProfileCalculationService
- LevelProgressionService
- These services encapsulate calculations and business rules that are reused across handlers and event consumers.
- ProfileCalculationService likely drives derived profile data, while LevelProgressionService handles progression logic from activity/session events.
6. Validation and error handling
- Each command/request has a validator in Users/Application/Validators.
- Validation is explicit and extensive, including both user-facing commands and internal event-driven commands.
- Shared error handling lives in Users/Common/Errors and Users/Common/Exceptions, with ExceptionHandlingMiddleware providing the HTTP boundary for exceptions.
7. Event-driven integration
- The service is not just request/response; it also consumes and emits domain/integration events.
- Internal event types are under Users/Models/Events, including:
- UserRegisteredEvent
- UserOnboardingCompletedEvent
- UserSessionStartedEvent
- WorkoutSessionExerciseCompletedEvent
- RoutineWeekClosedEvent
- UserRoutineSettingsUpdatedEvent
- Application event handlers react to these events and translate them into user state changes.
8. Messaging and asynchronous processing
- Users/Infraestructure/Events contains event consumers, an event publisher, and a dispatcher.
- ServiceBusEventSender plus Configuration/ServiceBusSettings.cs indicate integration with an external message bus, likely Azure Service Bus.
- Workers (OutboxWorker, ServiceBusWorker) suggest background processing for dispatching queued events and consuming inbound messages.
9. Outbox and idempotency pattern
- The presence of OutboxEventEntity, ProcessedIntegrationEventEntity, and corresponding repositories/persistence interfaces shows a classic reliability pattern:
- write business changes and outgoing events together
- asynchronously publish them later
- record processed inbound integration events to avoid duplicate handling
- This is a key architectural boundary: database state is the source of truth, while messaging is made reliable via outbox/inbox tracking.
10. Persistence layer
- Users/Infraestructure/Persistence contains SQL-backed persistence implementations and a SqlUnitOfWork.
- Users/Infraestructure/Repositories wrap those persistence classes and implement the domain repository interfaces.
- This makes the application layer database-agnostic while still using concrete SQL persistence underneath.
11. Security and request context
- Users/Infraestructure/Security/UserContextService.cs provides access to the current user context behind the IUserContextService abstraction.
- That service is likely used by controllers or handlers to scope operations to the authenticated user.
- Configuration/JwtSettings.cs indicates JWT-based authentication is part of the API boundary.
12. Derived profile and appearance logic
- Users/Infraestructure/Services/AppearanceMappingService.cs and its domain interface indicate a separate concern for mapping user data to appearance-related results.
- Configuration/AssetsSettings.cs suggests image/asset URL generation or asset lookup is part of the service’s outputs.
- These are presentation-adjacent calculations, not core persistence concerns.
13. Data flow at a glance
- HTTP request enters UsersController
- controller forwards to an application command handler
- handler validates input and uses domain services/repositories
- persistence writes to SQL via repository/unit-of-work
- domain events are stored in the outbox and later published
- workers or consumers process incoming bus events and update user state or progression
- responses are returned via DTOs in Users/Models/Responses
14. Testing structure
- Users.Tests mirrors the production structure: application command handlers, event handlers, validators, services, controllers, security, infrastructure workers.
- This indicates the repo is tested at multiple boundaries, especially business rules and message-processing flows.
15. Key architectural takeaway
- This service is best drawn as a domain-centric, event-driven ASP.NET Core microservice:
- synchronous API for user profile/onboarding operations
- asynchronous integration for lifecycle/progression events
- SQL persistence with outbox/inbox reliability
- clear separation between controllers, application orchestration, domain abstractions, and infrastructure implementations
Main entry points: CommandHandler Command handlers · DependencyInjectionExtensions.cs DI setup · EventHandler Event handlers · UsersController.cs Users API
Components 31
API boundary
HTTP entrypoint, hosting, middleware, and request/response contracts.
- Program · ASP.NET Core composition root and startup wiring.
Users/Program.cs - DI setup · Registers services, middleware, and infrastructure implementations.
Users/Extensions/DependencyInjectionExtensions.cs - Users API · Main HTTP entrypoint for user profile and onboarding operations.
Users/Controllers/UsersController.cs
Application layer
Use-case orchestration, validation, and event-driven handlers.
- Command handlers · User-facing flows for onboarding, profile updates, faction selection, and routine/tutorial actions.
Users/Application/CommandHandler - Event handlers · React to user lifecycle and workout/routine events to update state.
Users/Application/EventHandler - Validators · Rules for commands and requests at the application boundary.
Users/Application/Validators - User service · Central user-state business logic used by handlers and consumers.
Users/Application/Services/UserService.cs - Faction service · Faction selection and faction-related business rules.
Users/Application/Services/FactionService.cs - Profile calc · Derived profile, appearance, and onboarding-related calculations.
Users/Application/Services/ProfileCalculationService.cs - Progression · Level and progression logic driven by activity and session events.
Users/Application/Services/LevelProgressionService.cs
Domain model
Core entities, enums, and service/repository abstractions.
- User · Core persisted user profile and state aggregate.
Users/Domain/Entities/UserEntity.cs - Faction · Faction definitions and main stat metadata.
Users/Domain/Entities/FactionEntity.cs - Tutorial progress · Persisted tutorial/onboarding progression.
Users/Domain/Entities/UserTutorialProgressEntity.cs - Outbox · Outgoing integration events queued for reliable publication.
Users/Domain/Entities/OutboxEventEntity.cs - Processed events · Tracks consumed integration events to prevent duplicate handling.
Users/Domain/Entities/ProcessedIntegrationEventEntity.cs - Repositories · Persistence abstractions for user, faction, stats, tutorial, outbox, and inbox state.
Users/Domain/Repositories - Domain services · Abstractions for calculation, progression, event publishing, context, and user logic.
Users/Domain/Services
Infrastructure
SQL persistence, messaging, security, and background workers.
- Error middleware · Translates application exceptions into HTTP error responses.
Users/Infraestructure/Middleware/ExceptionHandlingMiddleware.cs - SQL persistence · Concrete SQL-backed persistence and unit-of-work implementations.
Users/Infraestructure/Persistence - Repo adapters · Repository implementations that wrap persistence classes.
Users/Infraestructure/Repositories - Events bus · Integration event dispatcher, consumers, and publisher.
Users/Infraestructure/Events - Bus sender · Sends integration events to the external service bus.
Users/Infraestructure/Events/Sender/ServiceBusEventSender.cs - Workers · Outbox dispatch and service bus consumption loops.
Users/Infraestructure/Workers - User context · Resolves the current authenticated user context.
Users/Infraestructure/Security/UserContextService.cs - Appearance map · Maps user data to appearance-related outputs.
Users/Infraestructure/Services/AppearanceMappingService.cs
Contracts
Commands, events, requests, and responses shared across layers.
Tests
Behavioral coverage mirroring the production architecture.
- App tests · Command handler, event handler, validator, and service tests.
Users.Tests/Application - API tests · Controller-level coverage.
Users.Tests/Controllers - Infra tests · Security, services, and worker processing tests.
Users.Tests/Infrastructure
Connections 46
- Program → DI setup: composes · Startup wires dependency injection and app services.
- Program → Users API: hosts · Exposes the HTTP API endpoints.
- Program → Error middleware: uses · Registers centralized exception handling.
- DI setup → Command handlers: registers · Adds use-case handlers to the container.
- DI setup → Event handlers: registers · Adds event consumers and handlers.
- DI setup → Validators: registers · Adds request and command validators.
- DI setup → Repo adapters: binds · Maps repository interfaces to SQL-backed implementations.
- DI setup → Events bus: binds · Registers messaging pipeline components.
- DI setup → Workers: starts · Adds background workers for dispatch and consumption.
- Users API → HTTP DTOs: uses · Accepts requests and returns DTO responses.
- Users API → Command handlers: calls · Delegates HTTP actions to application use cases.
- Users API → Validators: validates · Enforces request rules before execution.
- Command handlers → Commands: accepts · Handlers are driven by command contracts.
- Command handlers → User service: orchestrates · Coordinates user business logic.
- Command handlers → Faction service: orchestrates · Uses faction rules for selection and assignment.
- Command handlers → Profile calc: derives · Computes profile-related outputs.
- Command handlers → Progression: advances · Applies progression logic where relevant.
- Command handlers → Repositories: persists via · Relies on repository abstractions, not concrete SQL.
- Event handlers → Events: handles · Consumes internal lifecycle and workout events.
- Event handlers → Progression: updates · Applies event-driven progression changes.
- Event handlers → User service: updates · Mutates user state from incoming events.
- Event handlers → Repositories: reads/writes · Uses repository abstractions for state changes.
- Validators → Commands: checks · Validates commands and requests.
- User service → User: governs · Encapsulates core user rules.
- User service → Tutorial progress: updates · Manages onboarding/tutorial progress.
- Faction service → Faction: uses · Operates on faction definitions.
- Profile calc → Appearance map: feeds · Supports appearance and profile presentation data.
- Progression → User: derives · Computes progression from user state and events.
- Repositories → SQL persistence: implemented by · Domain persistence contracts are realized in SQL adapters.
- Repo adapters → SQL persistence: wraps · Repository classes delegate to SQL persistence.
- SQL persistence → Outbox: stores · Persists outgoing integration events.
- SQL persistence → Processed events: stores · Persists processed-event tracking.
- Events bus → Bus sender: publishes via · Sends integration events externally.
- Events bus → Events: consumes/emits · Moves event contracts across boundaries.
- Workers → Events bus: drives · Background jobs dispatch and consume messages.
- Workers → SQL persistence: polls · Reads outbox and inbox state for reliable processing.
- User context → Domain services: implements · Provides the current-user abstraction.
- Appearance map → Domain services: implements · Provides appearance mapping abstraction.
- App tests → Command handlers: covers · Validates user flows and orchestration.
- App tests → Event handlers: covers · Validates event-driven state changes.
- App tests → Validators: covers · Validates input rules.
- App tests → User service: covers · Checks core user business rules.
- API tests → Users API: covers · Exercises the HTTP boundary.
- Infra tests → Workers: covers · Exercises background processing.
- Infra tests → User context: covers · Checks security context behavior.
- Infra tests → Appearance map: covers · Checks derived appearance mapping.