# jabelresendiz/backend architecture

> Architecture diagram of the GitHub repository jabelresendiz/backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jabelresendiz/backend
- Repository: https://github.com/jabelresendiz/backend

## Overview

1. This repository is a layered ASP.NET Core backend split into four main projects: `API`, `Application`, `Domain`, and `Infrastructure`. The separation is deliberate: HTTP concerns live in `API`, business use cases in `Application`, core business objects in `Domain`, and all persistence/integration details in `Infrastructure`.

2. `Finlay.PharmaVigilance.API` is the entry boundary. Its controllers are organized by business area rather than by technical CRUD: authentication, catalog, dashboard, lot, manufacturer, medical review, report, and vaccination center. It also contains middleware for centralized error handling and rate limiting, plus a `UserContextService` for accessing the current caller identity/claims.

3. `Finlay.PharmaVigilance.Application` is the orchestration layer. It defines service interfaces, DTOs, validators, and helpers. Most controllers depend on application services rather than repositories directly, so business workflows are coordinated here and data is projected into feature-specific DTOs instead of exposing domain entities.

4. `Finlay.PharmaVigilance.Domain` holds the core model: entities such as `AefiReport`, `AdverseEvent`, `MedicalReview`, `MedicalReviewAssignment`, `Reporter`, `VaccinatedSubject`, `Vaccination`, `Lot`, `Vaccine`, `Manufacturer`, `VaccinationCenter`, `User`, and role-specific users like `MedicalReviewer` and `SectionResponsible`. Enums like `ReportStatus`, `ReviewAssignmentStatus`, `UserRole`, and `Severity` define the business vocabulary. Domain events are also modeled here, including `AssignmentExpiredEvent`, `EmailToReporterEvent`, and `MedicalReviewerRegisteredEvent`.

5. `Finlay.PharmaVigilance.Infrastructure` is where the system integrates with external services and persistence. It contains `FinlayDbContext`, repository implementations, a unit of work, an identity manager, JWT token generation, SMTP email delivery, a RabbitMQ message bus, consumers, and a background service for assignment expiration. This is the main boundary to the database, authentication provider logic, messaging, and email infrastructure.

6. Data access follows a repository + unit-of-work pattern. The `Application` layer defines repository abstractions and command/query services, while `Infrastructure/Repository` provides the concrete implementations over `FinlayDbContext`. This keeps query and mutation logic centralized in application services and avoids coupling controllers to EF Core.

7. Authentication and authorization are a distinct subsystem. The API exposes login and registration flows for general users, medical reviewers, and section responsible users. `IdentityManager`, `IIdentityService`, JWT token generation, and refresh token repositories indicate a token-based auth model with role-based access control. The current user context is used downstream to tailor behavior and permissions.

8. The report / AEFI workflow is the central business flow. Public or authenticated users submit reports through report controllers and command services, with validators enforcing domain-specific rules on reporters, vaccinated subjects, vaccinations, and adverse events. Reporting results in DTO-based responses and can trigger downstream events for notifications or review handling.

9. Medical review is a separate operational workflow. Reports can be assigned to medical reviewers via dedicated assignment and review controllers/services. The presence of assignment expiration logic, `AssignmentExpirationBackgroundService`, and `AssignmentExpiredConsumer` shows that review ownership is time-bound and partially automated through background processing and messaging.

10. Messaging is event-driven and used for side effects, not core request handling. `IEventBus` and `RabbitMqMessageBus` connect domain/application events to consumers such as `EmailToReporterConsumer`, `EmailToSectionResponsibleConsumer`, `MedicalReviewerConsumer`, and `AssignmentExpiredConsumer`. This decouples report submission and review actions from notifications and other asynchronous follow-up work.

11. Master data and lookup flows are handled as catalogs and reference entities. Vaccines, symptoms, manufacturers, lots, and vaccination centers have their own command/query services and controllers. These are likely used across report creation, administration screens, and search/filter features.

12. Dashboards are a read-optimized subsystem. Separate admin and municipal dashboard controllers/services expose aggregated views such as performance, report summaries, and vaccine-related metrics. The DTO structure suggests these endpoints are projection-heavy and role-dependent rather than entity-centric.

13. Validation is treated as a first-class boundary. The application layer includes dedicated validators for reports, medical reviewers, vaccinations, vaccinated subjects, and reporters, plus custom attributes for email, enum, and identity-number validation. This means malformed or incomplete input is rejected before it reaches domain/persistence logic.

14. Operationally, the repo is container-friendly and deployment-oriented. There is a root `Dockerfile`, a `docker-compose.yml`, a RabbitMQ container folder, Railway configuration files, migration scripts, and a `Requests/` directory with `.http` samples for manual API testing. Those files indicate the backend is designed to run as a service with supporting infrastructure and scripted environment setup.

Main entry points: [`Finlay.PharmaVigilance.API/Program.cs`](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Program.cs) (API Host), [`Finlay.PharmaVigilance.Application`](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application) (Contracts & Validation), [`Finlay.PharmaVigilance.Application/Services/MedicalReview`](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/MedicalReview) (Review Services), [`Finlay.PharmaVigilance.API/Controllers/ReportControllers/ReportController.cs`](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/ReportControllers/ReportController.cs) (Report API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_api_root["API Host<br/>aspnet host<br/>[Program.cs]"]
  node_api_middleware["Middleware<br/>http pipeline<br/>[Middleware]"]
  node_api_user_context["User Context<br/>caller context"]
  node_api_auth["Auth Controllers<br/>auth endpoints"]
  node_api_reports["Report API<br/>report endpoints"]
  node_api_review["Review API<br/>review endpoints"]
  node_api_catalog["Catalog API<br/>lookup endpoints"]
  node_api_dashboards["Dashboards<br/>read endpoints<br/>[Dashboard]"]
  node_api_masterdata["Master Data<br/>entity endpoints<br/>[Controllers]"]
end

subgraph group_app["Application"]
  node_app_auth["Identity Services<br/>auth orchestration<br/>[Authentication]"]
  node_app_reports["Report Services<br/>report orchestration<br/>[Report]"]
  node_app_review["Review Services<br/>review orchestration<br/>[MedicalReview]"]
  node_app_catalog["Catalog Services<br/>lookup orchestration<br/>[Catalog]"]
  node_app_dashboard["Dashboard Services<br/>projection services<br/>[Dashboard]"]
  node_app_shared["Contracts & Validation<br/>application boundary"]
end

subgraph group_domain["Domain"]
  node_domain_model["Core Model<br/>entities and enums<br/>[Entities]"]
  node_domain_events["Domain Events<br/>[Events]"]
end

subgraph group_infra["Infrastructure"]
  node_infra_db[("Db Context<br/>ef core persistence<br/>[FinlayDbContext.cs]")]
  node_infra_repos["Repositories<br/>data access<br/>[Repository]"]
  node_infra_uow["Unit of Work<br/>transaction boundary<br/>[UnitOfWork.cs]"]
  node_infra_identity["Identity & JWT<br/>auth infrastructure<br/>[Authentication]"]
  node_infra_messaging["Event Bus<br/>messaging infrastructure"]
  node_infra_notifications["Email Delivery<br/>email infrastructure"]
  node_infra_background["Expiration Worker<br/>background service"]
end

node_api_root -->|"pipeline"| node_api_middleware
node_api_root -->|"routes"| node_api_auth
node_api_root -->|"routes"| node_api_reports
node_api_root -->|"routes"| node_api_review
node_api_root -->|"routes"| node_api_catalog
node_api_root -->|"routes"| node_api_dashboards
node_api_root -->|"routes"| node_api_masterdata
node_api_auth -->|"uses"| node_app_auth
node_api_reports -->|"uses"| node_app_reports
node_api_review -->|"uses"| node_app_review
node_api_catalog -->|"uses"| node_app_catalog
node_api_dashboards -->|"uses"| node_app_dashboard
node_api_masterdata -->|"uses"| node_app_shared
node_api_reports -->|"context"| node_api_user_context
node_app_auth -->|"depends on"| node_app_shared
node_app_reports -->|"depends on"| node_app_shared
node_app_review -->|"depends on"| node_app_shared
node_app_catalog -->|"depends on"| node_app_shared
node_app_dashboard -->|"depends on"| node_app_shared
node_app_shared -->|"models"| node_domain_model
node_app_shared -->|"publishes"| node_domain_events
node_infra_repos -->|"implements over"| node_infra_db
node_infra_uow -->|"coordinates"| node_infra_repos
node_infra_identity -->|"persists"| node_infra_db
node_infra_messaging -->|"delivers"| node_domain_events
node_infra_notifications -->|"consumes"| node_infra_messaging
node_infra_background -->|"publishes"| node_infra_messaging
node_infra_background -->|"coordinates"| node_app_review
node_app_reports -->|"persists via"| node_infra_uow
node_app_review -->|"persists via"| node_infra_uow
node_app_auth -->|"auth via"| node_infra_identity
node_app_catalog -->|"queries via"| node_infra_repos

click node_api_root "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Program.cs"
click node_api_middleware "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Middleware"
click node_api_user_context "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Common/UserContextService.cs"
click node_api_auth "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/AuthenticationControllers"
click node_api_reports "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/ReportControllers/ReportController.cs"
click node_api_review "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/MedicalReviewControllers"
click node_api_catalog "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/CatalogControllers/CatalogController.cs"
click node_api_dashboards "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/Dashboard"
click node_api_masterdata "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers"
click node_app_auth "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Authentication"
click node_app_reports "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Report"
click node_app_review "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/MedicalReview"
click node_app_catalog "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Catalog"
click node_app_dashboard "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Dashboard"
click node_app_shared "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application"
click node_domain_model "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Domain/Entities"
click node_domain_events "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Domain/Events"
click node_infra_db "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/FinlayDbContext.cs"
click node_infra_repos "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Repository"
click node_infra_uow "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/UnitOfWork/UnitOfWork.cs"
click node_infra_identity "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Authentication"
click node_infra_messaging "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Messaging/RabbitMqMessageBus.cs"
click node_infra_notifications "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Email/SmtpEmailService.cs"
click node_infra_background "https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/BackgroundServices/AssignmentExpirationBackgroundService.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_root,node_api_middleware,node_api_user_context,node_api_auth,node_api_reports,node_api_review,node_api_catalog,node_api_dashboards,node_api_masterdata toneBlue
class node_app_auth,node_app_reports,node_app_review,node_app_catalog,node_app_dashboard,node_app_shared toneAmber
class node_domain_model,node_domain_events toneMint
class node_infra_db,node_infra_repos,node_infra_uow,node_infra_identity,node_infra_messaging,node_infra_notifications,node_infra_background toneRose
```

## Components

### API

HTTP entry boundary, controllers, middleware, and caller context.

- [API Host](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Program.cs): aspnet host · Bootstraps HTTP pipeline and exposes the backend entry point. · `Finlay.PharmaVigilance.API/Program.cs`
- [Middleware](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Middleware): http pipeline · Centralized error handling and rate limiting. · `Finlay.PharmaVigilance.API/Middleware`
- [User Context](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Common/UserContextService.cs): caller context · Resolves current user identity and claims for downstream services. · `Finlay.PharmaVigilance.API/Common/UserContextService.cs`
- [Auth Controllers](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/AuthenticationControllers): auth endpoints · Login and registration endpoints for users and role-specific accounts. · `Finlay.PharmaVigilance.API/Controllers/AuthenticationControllers`
- [Report API](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/ReportControllers/ReportController.cs): report endpoints · Creates and reads AEFI reports and report access views. · `Finlay.PharmaVigilance.API/Controllers/ReportControllers/ReportController.cs`
- [Review API](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/MedicalReviewControllers): review endpoints · Medical review and assignment endpoints for report handling. · `Finlay.PharmaVigilance.API/Controllers/MedicalReviewControllers`
- [Catalog API](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/CatalogControllers/CatalogController.cs): lookup endpoints · Reference data endpoints for vaccines and symptoms. · `Finlay.PharmaVigilance.API/Controllers/CatalogControllers/CatalogController.cs`
- [Dashboards](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers/Dashboard): read endpoints · Role-based aggregate views for admin and municipal users. · `Finlay.PharmaVigilance.API/Controllers/Dashboard`
- [Master Data](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.API/Controllers): entity endpoints · Endpoints for lots, manufacturers, and vaccination centers. · `Finlay.PharmaVigilance.API/Controllers`

### Application

Use-case orchestration, DTOs, validation, and repository/service contracts.

- [Identity Services](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Authentication): auth orchestration · Coordinates login, registration, JWT issuance, and role-based identity flows. · `Finlay.PharmaVigilance.Application/Services/Authentication`
- [Report Services](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Report): report orchestration · Coordinates report creation, validation, querying, and DTO projection. · `Finlay.PharmaVigilance.Application/Services/Report`
- [Review Services](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/MedicalReview): review orchestration · Manages medical review, assignment, and expiration workflows. · `Finlay.PharmaVigilance.Application/Services/MedicalReview`
- [Catalog Services](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Catalog): lookup orchestration · Handles vaccine and symptom command/query flows. · `Finlay.PharmaVigilance.Application/Services/Catalog`
- [Dashboard Services](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application/Services/Dashboard): projection services · Builds admin and municipal dashboard projections. · `Finlay.PharmaVigilance.Application/Services/Dashboard`
- [Contracts & Validation](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Application): application boundary · Repository interfaces, service interfaces, DTOs, validators, and helpers. · `Finlay.PharmaVigilance.Application`

### Domain

Core business model, enums, and domain events.

- [Core Model](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Domain/Entities): entities and enums · AEFI reports, users, vaccinations, medical review entities, and business enums. · `Finlay.PharmaVigilance.Domain/Entities`
- [Domain Events](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Domain/Events): events · Business events used to trigger notifications and follow-up processing. · `Finlay.PharmaVigilance.Domain/Events`

### Infrastructure

Persistence, auth, messaging, email, background processing, and external integrations.

- [Db Context](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/FinlayDbContext.cs): ef core persistence · Entity Framework Core context and database boundary. · `Finlay.PharmaVigilance.Infrastructure/FinlayDbContext.cs`
- [Repositories](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Repository): data access · Concrete repository implementations over the database context. · `Finlay.PharmaVigilance.Infrastructure/Repository`
- [Unit of Work](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/UnitOfWork/UnitOfWork.cs): transaction boundary · Coordinates repository commits as a single persistence unit. · `Finlay.PharmaVigilance.Infrastructure/UnitOfWork/UnitOfWork.cs`
- [Identity & JWT](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Authentication): auth infrastructure · Identity manager and token generation for authentication and refresh tokens. · `Finlay.PharmaVigilance.Infrastructure/Authentication`
- [Event Bus](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Messaging/RabbitMqMessageBus.cs): messaging infrastructure · RabbitMQ-backed bus and consumers for async side effects. · `Finlay.PharmaVigilance.Infrastructure/Messaging/RabbitMqMessageBus.cs`
- [Email Delivery](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/Email/SmtpEmailService.cs): email infrastructure · SMTP email service and notification consumers. · `Finlay.PharmaVigilance.Infrastructure/Email/SmtpEmailService.cs`
- [Expiration Worker](https://github.com/jabelresendiz/backend/blob/main/Finlay.PharmaVigilance.Infrastructure/BackgroundServices/AssignmentExpirationBackgroundService.cs): background service · Background processing for assignment expiration and related automation. · `Finlay.PharmaVigilance.Infrastructure/BackgroundServices/AssignmentExpirationBackgroundService.cs`

## Connections

- API Host → Middleware: pipeline · HTTP requests flow through centralized middleware.
- API Host → Auth Controllers: routes · The host maps authentication endpoints.
- API Host → Report API: routes · The host maps report endpoints.
- API Host → Review API: routes · The host maps review endpoints.
- API Host → Catalog API: routes · The host maps catalog endpoints.
- API Host → Dashboards: routes · The host maps dashboard endpoints.
- API Host → Master Data: routes · The host maps master-data endpoints.
- Auth Controllers → Identity Services: uses · Authentication controllers delegate to application identity services.
- Report API → Report Services: uses · Report controllers coordinate report use cases through application services.
- Review API → Review Services: uses · Review controllers delegate assignment and review workflows.
- Catalog API → Catalog Services: uses · Catalog controllers call application lookup services.
- Dashboards → Dashboard Services: uses · Dashboard controllers request projection services.
- Master Data → Contracts & Validation: uses · Master-data controllers depend on shared application contracts and DTOs.
- Report API → User Context: context · Report endpoints use caller identity and claims for access and tailoring.
- Identity Services → Contracts & Validation: depends on · Identity services rely on shared interfaces and DTOs.
- Report Services → Contracts & Validation: depends on · Report services use DTOs, validators, and repository contracts.
- Review Services → Contracts & Validation: depends on · Review services use repository contracts and event abstractions.
- Catalog Services → Contracts & Validation: depends on · Catalog services use shared application contracts.
- Dashboard Services → Contracts & Validation: depends on · Dashboard services use DTO projections and common services.
- Contracts & Validation → Core Model: models · Application contracts are shaped by the domain model and vocabularies.
- Contracts & Validation → Domain Events: publishes · Application logic can raise domain events through shared messaging abstractions.
- Repositories → Db Context: implements over · Repositories are built on the EF Core context.
- Unit of Work → Repositories: coordinates · Unit of work composes repository mutations.
- Identity & JWT → Db Context: persists · Identity and token flows read and write through the database boundary.
- Event Bus → Domain Events: delivers · Events are transported to async consumers.
- Email Delivery → Event Bus: consumes · Notification side effects are triggered from the message bus.
- Expiration Worker → Event Bus: publishes · Background expiration processing emits follow-up messages.
- Expiration Worker → Review Services: coordinates · Expiration work supports review assignment workflows.
- Report Services → Unit of Work: persists via · Report use cases commit through the unit of work.
- Review Services → Unit of Work: persists via · Review use cases commit through the unit of work.
- Identity Services → Identity & JWT: auth via · Identity services rely on token generation and identity management.
- Catalog Services → Repositories: queries via · Catalog services read and write through repositories.
