# baophucs/finreport architecture

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

- Interactive diagram: https://gitdiagram.com/baophucs/finreport
- Repository: https://github.com/baophucs/finreport

## Overview

FinReport is a financial-reporting and analysis system: users manage companies and reports through an API, uploaded reports are queued for background extraction and validation, and staff can review and approve the resulting data. The repository also exposes analysis, dashboard, chat, authentication, audit, and notification capabilities. The sampled excerpts establish the report-processing worker and persistence model; several other capabilities are represented by their source paths, but their internal calls were not sampled, so those links are omitted or marked unverified.

Main entry points: [`FinReport.API/Program.cs`](https://github.com/baophucs/finreport/blob/main/FinReport.API/Program.cs) (HTTP API), [`FinReport.Worker/ReportProcessorWorker.cs`](https://github.com/baophucs/finreport/blob/main/FinReport.Worker/ReportProcessorWorker.cs) (Report processor), [`FinReport.Infrastructure/Data/FinReportContext.cs`](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Data/FinReportContext.cs) (Application database), [`FinReport.Infrastructure/Services/FinancialReportService.cs`](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/FinancialReportService.cs) (Report lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API capabilities"]
  node_api_entry["HTTP API<br/>[Program.cs]"]
  node_report_api["Report endpoints"]
  node_company_api["Company endpoints"]
  node_analysis_api["Analysis endpoints"]
  node_dashboard_api["Dashboard endpoints"]
  node_chat_api["Chat endpoints<br/>[ChatController.cs]"]
  node_catalog_api["Metric endpoints"]
end

subgraph group_reports["Report workflow"]
  node_report_service["Report lifecycle"]
  node_report_worker["Report processor"]
  node_validation["Report validation"]
end

subgraph group_analysis["Analysis and insights"]
  node_analysis_service["Analysis service<br/>[AnalysisService.cs]"]
  node_chat_service["Financial chat<br/>[ChatBotService.cs]"]
end

subgraph group_identity["Identity and notifications"]
  node_auth_api["Auth endpoints<br/>[AuthController.cs]"]
  node_auth_service["Authentication<br/>[AuthService.cs]"]
  node_notification_service["Notifications"]
  node_notification_hub["Live notifications<br/>[NotificationHub.cs]"]
end

subgraph group_data["Persistence and integrations"]
  node_domain_models["Domain entities<br/>[FinancialReport.cs]"]
  node_database[("Application database")]
  node_repository["Repository layer<br/>[BaseRepository.cs]"]
  node_file_storage["File storage adapter"]
  node_ocr["Azure OCR<br/>[AzureOcrService.cs]"]
  node_analyst["Gemini analyst"]
  node_job_queue["Background job queue"]
end

node_user(("User"))

node_user -.->|"sends requests"| node_api_entry
node_api_entry -.->|"routes requests"| node_report_api
node_api_entry -.->|"routes requests"| node_company_api
node_api_entry -.->|"routes requests"| node_analysis_api
node_api_entry -.->|"routes requests"| node_dashboard_api
node_api_entry -.->|"routes requests"| node_chat_api
node_api_entry -.->|"routes requests"| node_catalog_api
node_api_entry -.->|"routes requests"| node_auth_api
node_report_service -.->|"stores files"| node_file_storage
node_report_service -.->|"enqueues analysis"| node_job_queue
node_report_worker -->|"dequeues jobs"| node_job_queue
node_report_worker -->|"retrieves files"| node_file_storage
node_report_worker -->|"requests extraction"| node_analyst
node_report_worker -->|"validates report"| node_validation
node_report_worker -->|"sends updates"| node_notification_hub
node_auth_api -.->|"delegates auth"| node_auth_service
node_report_service -.->|"persists reports"| node_database
node_report_worker -.->|"updates status"| node_database
node_repository -->|"queries and writes"| node_database
node_database -->|"maps entities"| node_domain_models
node_analysis_api -.->|"delegates analysis"| node_analysis_service
node_chat_api -.->|"delegates chat"| node_chat_service
node_report_worker -.->|"extracts text"| node_ocr

click node_api_entry "https://github.com/baophucs/finreport/blob/main/FinReport.API/Program.cs"
click node_report_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/FinancialReportsController.cs"
click node_company_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/CompaniesController.cs"
click node_analysis_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/AnalysisReportsController.cs"
click node_dashboard_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/DashboardController.cs"
click node_chat_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/ChatController.cs"
click node_catalog_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/MetricsController.cs"
click node_report_service "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/FinancialReportService.cs"
click node_report_worker "https://github.com/baophucs/finreport/blob/main/FinReport.Worker/ReportProcessorWorker.cs"
click node_validation "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/ReportValidationService.cs"
click node_analysis_service "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/AnalysisService.cs"
click node_chat_service "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/ChatBotService.cs"
click node_auth_api "https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/AuthController.cs"
click node_auth_service "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/AuthService.cs"
click node_notification_service "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/NotificationService.cs"
click node_notification_hub "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Hubs/NotificationHub.cs"
click node_domain_models "https://github.com/baophucs/finreport/blob/main/FinReport.Core/Entity/FinancialReport.cs"
click node_database "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Data/FinReportContext.cs"
click node_repository "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Data/BaseRepository.cs"
click node_file_storage "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/MinioStorageService.cs"
click node_ocr "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/AzureOcrService.cs"
click node_analyst "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/GeminiFinancialAnalyst.cs"
click node_job_queue "https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/RedisBackgroundJobQueue.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_entry,node_report_api,node_company_api,node_analysis_api,node_dashboard_api,node_chat_api,node_catalog_api,node_user toneBlue
class node_report_service,node_report_worker,node_validation toneAmber
class node_analysis_service,node_chat_service toneMint
class node_auth_api,node_auth_service,node_notification_service,node_notification_hub toneRose
class node_domain_models,node_database,node_repository,node_file_storage,node_ocr,node_analyst,node_job_queue toneIndigo
```

## Components

### API capabilities

- [HTTP API](https://github.com/baophucs/finreport/blob/main/FinReport.API/Program.cs): `FinReport.API/Program.cs`
- [Report endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/FinancialReportsController.cs): `FinReport.API/Controllers/FinancialReportsController.cs`
- [Company endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/CompaniesController.cs): `FinReport.API/Controllers/CompaniesController.cs`
- [Analysis endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/AnalysisReportsController.cs): `FinReport.API/Controllers/AnalysisReportsController.cs`
- [Dashboard endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/DashboardController.cs): `FinReport.API/Controllers/DashboardController.cs`
- [Chat endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/ChatController.cs): `FinReport.API/Controllers/ChatController.cs`
- [Metric endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/MetricsController.cs): `FinReport.API/Controllers/MetricsController.cs`

### Report workflow

- [Report lifecycle](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/FinancialReportService.cs): `FinReport.Infrastructure/Services/FinancialReportService.cs`
- [Report processor](https://github.com/baophucs/finreport/blob/main/FinReport.Worker/ReportProcessorWorker.cs): `FinReport.Worker/ReportProcessorWorker.cs`
- [Report validation](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/ReportValidationService.cs): `FinReport.Infrastructure/Services/ReportValidationService.cs`

### Analysis and insights

- [Analysis service](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/AnalysisService.cs): `FinReport.Infrastructure/Services/AnalysisService.cs`
- [Financial chat](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/ChatBotService.cs): `FinReport.Infrastructure/Services/ChatBotService.cs`

### Identity and notifications

- [Auth endpoints](https://github.com/baophucs/finreport/blob/main/FinReport.API/Controllers/AuthController.cs): `FinReport.API/Controllers/AuthController.cs`
- [Authentication](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/AuthService.cs): `FinReport.Infrastructure/Services/AuthService.cs`
- [Notifications](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Services/NotificationService.cs): `FinReport.Infrastructure/Services/NotificationService.cs`
- [Live notifications](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Hubs/NotificationHub.cs): `FinReport.Infrastructure/Hubs/NotificationHub.cs`

### Persistence and integrations

- [Domain entities](https://github.com/baophucs/finreport/blob/main/FinReport.Core/Entity/FinancialReport.cs): `FinReport.Core/Entity/FinancialReport.cs`
- [Application database](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Data/FinReportContext.cs): `FinReport.Infrastructure/Data/FinReportContext.cs`
- [Repository layer](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/Data/BaseRepository.cs): `FinReport.Infrastructure/Data/BaseRepository.cs`
- [File storage adapter](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/MinioStorageService.cs): `FinReport.Infrastructure/ExternalServices/MinioStorageService.cs`
- [Azure OCR](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/AzureOcrService.cs): `FinReport.Infrastructure/ExternalServices/AzureOcrService.cs`
- [Gemini analyst](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/GeminiFinancialAnalyst.cs): `FinReport.Infrastructure/ExternalServices/GeminiFinancialAnalyst.cs`
- [Background job queue](https://github.com/baophucs/finreport/blob/main/FinReport.Infrastructure/ExternalServices/RedisBackgroundJobQueue.cs): `FinReport.Infrastructure/ExternalServices/RedisBackgroundJobQueue.cs`

### Other components

- **User**

## Connections

- User → HTTP API: sends requests
- HTTP API → Report endpoints: routes requests
- HTTP API → Company endpoints: routes requests
- HTTP API → Analysis endpoints: routes requests
- HTTP API → Dashboard endpoints: routes requests
- HTTP API → Chat endpoints: routes requests
- HTTP API → Metric endpoints: routes requests
- HTTP API → Auth endpoints: routes requests
- Report lifecycle → File storage adapter: stores files
- Report lifecycle → Background job queue: enqueues analysis
- Report processor → Background job queue: dequeues jobs (evidence: `FinReport.Worker/ReportProcessorWorker.cs`)
- Report processor → File storage adapter: retrieves files (evidence: `FinReport.Worker/ReportProcessorWorker.cs`)
- Report processor → Gemini analyst: requests extraction (evidence: `FinReport.Worker/ReportProcessorWorker.cs`)
- Report processor → Report validation: validates report (evidence: `FinReport.Worker/ReportProcessorWorker.cs`)
- Report processor → Live notifications: sends updates (evidence: `FinReport.Worker/ReportProcessorWorker.cs`)
- Auth endpoints → Authentication: delegates auth
- Report lifecycle → Application database: persists reports
- Report processor → Application database: updates status
- Repository layer → Application database: queries and writes (evidence: `FinReport.Infrastructure/Data/BaseRepository.cs`)
- Application database → Domain entities: maps entities (evidence: `FinReport.Infrastructure/Data/FinReportContext.cs`)
- Analysis endpoints → Analysis service: delegates analysis
- Chat endpoints → Financial chat: delegates chat
- Report processor → Azure OCR: extracts text