# kimrenny/gmhelper-api architecture

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

- Interactive diagram: https://gitdiagram.com/kimrenny/gmhelper-api
- Repository: https://github.com/kimrenny/gmhelper-api

## Overview

#### Purpose and entry point
GMHelper Backend is a .NET 9 Web API serving the GMHelper application: authentication, user/device management, math/geometry task processing, reporting, mail, security, and administration. Runtime composition and HTTP pipeline begin in `MatHelper.API/Program.cs`; public endpoints are organized under `MatHelper.API/Controllers/`. Swagger is the API discovery surface.

#### Layered backend structure
The repository follows API → business logic → persistence boundaries:
- HTTP controllers accept requests and return normalized responses via `MatHelper.API/Common/ApiResponse.cs`.
- Business services expose interfaces and implement workflows in `MatHelper.BLL/Interfaces/` and `MatHelper.BLL/Services/`.
- EF Core data access is isolated in `MatHelper.DAL/Database/AppDbContext.cs`, repository interfaces, and implementations in `MatHelper.DAL/Repositories/`.
- Shared contracts, enums, options, and DTOs reside in `MatHelper.CORE/Models/` and `MatHelper.CORE/Options/`.

#### Identity, authentication, and token lifecycle
Authentication is a core subsystem supporting registration, login, email-code flows, password recovery, JWT/token management, login-attempt protection, and two-factor authentication. API entry points are `MatHelper.API/Controllers/AuthController.cs` and `MatHelper.API/Controllers/SecurityController.cs`; orchestration is in `MatHelper.BLL/Services/Auth/AuthenticationService.cs`, `MatHelper.BLL/Services/Auth/LoginService.cs`, and `MatHelper.BLL/Services/Auth/TwoFactorAuthService.cs`. Persistent identity/session artifacts include users, login tokens, email codes, recovery tokens, and two-factor sessions under `MatHelper.DAL/Models/`.

#### Request protection, observability, and policy
The inbound pipeline enforces duplicate-request handling, concurrency/request limits, and error logging before or around controller processing. Key boundaries are `MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs`, `MatHelper.API/Middlewares/RequestLimitingMiddleware.cs`, and `MatHelper.API/Middlewares/ErrorLoggingMiddleware.cs`. Request logging also appears as a BLL filter/service path through `MatHelper.BLL/Filters/RequestLoggingFilter.cs` and `MatHelper.BLL/Services/Admin/RequestLogService.cs`. Limit policy is configured in `MatHelper.API/Configuration/security.json`.

#### Domain operations and user-facing services
Task endpoints route computational work to separate math and geometry processing services, while user, owner, mail, and report endpoints provide account operations and operational feedback. Principal boundaries: `MatHelper.API/Controllers/TasksController.cs`, `MatHelper.BLL/Services/MathTaskProcessingService.cs`, `MatHelper.BLL/Services/GeoTaskProcessingService.cs`; `MatHelper.API/Controllers/UserController.cs` and `MatHelper.BLL/Services/UserManagementService.cs`; and `MatHelper.API/Controllers/ReportController.cs` with `MatHelper.BLL/Services/ReportService.cs`. A protobuf contract at `MatHelper.Protos/solution_hub.proto` indicates integration with an external solution-hub service.

#### Administration and persistence
Administrative endpoints manage users, settings, tokens, analytics, and logs through dedicated services and repositories: `MatHelper.API/Controllers/AdminController.cs`, `MatHelper.BLL/Services/Admin/AdminService.cs`, and `MatHelper.BLL/Services/Admin/AnalyticsService.cs`. PostgreSQL is the durable store, evolved by EF migrations in `MatHelper.DAL/Migrations/`; Redis is configured as a cache dependency through `MatHelper.BLL/Services/CacheService.cs`. SMTP supports email delivery via `MatHelper.BLL/Services/MailService.cs` and template providers.

#### Deployment and external configuration
The service runs directly with .NET or in Docker using `Dockerfile` and `docker-compose.yml`. Required environment configuration covers PostgreSQL connection strings, Redis, SMTP, CAPTCHA secret, JWT issuer/audience/signing key, CORS origins, trusted proxies, and ASP.NET environment. CAPTCHA validation is encapsulated by `MatHelper.BLL/Services/CaptchaValidationService.cs`, keeping the external provider behind a service boundary.

Main entry points: [`MatHelper.BLL/Services/Auth/AuthenticationService.cs`](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/AuthenticationService.cs) (Authentication workflow), [`MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs`](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs) (Request protection), [`MatHelper.DAL/Database/AppDbContext.cs`](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.DAL/Database/AppDbContext.cs) (EF Core persistence), [`MatHelper.API/Program.cs`](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Program.cs) (Runtime composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_program{{"Runtime composition<br/>.NET host<br/>[Program.cs]"}}
  node_middleware["Request protection<br/>middleware"]
  node_security_policy["Limit policy<br/>security config<br/>[security.json]"]
  node_controllers["Public endpoints<br/>controllers"]
  node_api_response["Normalized responses<br/>response contract<br/>[ApiResponse.cs]"]
  node_auth_controller["Auth and security endpoints<br/>controllers<br/>[AuthController.cs]"]
  node_task_controller["Task endpoints<br/>controller<br/>[TasksController.cs]"]
  node_admin_controller["Admin endpoints<br/>controller<br/>[AdminController.cs]"]
end

subgraph group_business["Business services"]
  node_auth_service["Authentication workflow<br/>auth service"]
  node_login_service["Login protection<br/>auth service<br/>[LoginService.cs]"]
  node_two_factor["Two-factor auth<br/>auth service"]
  node_task_services["Math and geometry processing<br/>task services"]
  node_user_service["User management<br/>user service"]
  node_report_service["Reports<br/>report service<br/>[ReportService.cs]"]
  node_admin_services["Administration and analytics<br/>admin services<br/>[AdminService.cs]"]
  node_cache_service["Cache service<br/>[CacheService.cs]"]
  node_mail_service["Mail delivery<br/>mail service<br/>[MailService.cs]"]
  node_captcha_service["CAPTCHA validation<br/>external adapter"]
  node_contracts["Shared contracts<br/>models and options"]
end

subgraph group_data["Data and integrations"]
  node_db_context[("EF Core persistence<br/>DbContext<br/>[AppDbContext.cs]")]
  node_identity_artifacts[("Identity and session data<br/>persistent models")]
  node_repositories["Repositories<br/>data access"]
  node_solution_hub["Solution hub contract<br/>protobuf integration<br/>[solution_hub.proto]"]
end

node_program -->|"installs"| node_middleware
node_program -->|"routes to"| node_controllers
node_middleware -->|"uses"| node_security_policy
node_middleware -->|"protects"| node_controllers
node_controllers -->|"returns"| node_api_response
node_auth_controller -->|"authenticates via"| node_auth_service
node_auth_service -->|"uses"| node_login_service
node_auth_service -->|"uses"| node_two_factor
node_auth_service -->|"manages"| node_identity_artifacts
node_task_controller -->|"submits tasks"| node_task_services
node_task_services -.->|"integrates with"| node_solution_hub
node_controllers -->|"invokes"| node_user_service
node_controllers -->|"invokes"| node_report_service
node_admin_controller -->|"administers via"| node_admin_services
node_auth_service -->|"validates"| node_captcha_service
node_auth_service -->|"sends codes through"| node_mail_service
node_user_service -->|"persists through"| node_repositories
node_admin_services -->|"queries through"| node_repositories
node_report_service -->|"reads through"| node_repositories
node_repositories -->|"uses"| node_db_context
node_db_context -->|"stores"| node_identity_artifacts
node_cache_service -.->|"backs application data"| node_db_context
node_auth_service -->|"uses"| node_contracts

click node_program "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Program.cs"
click node_middleware "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs"
click node_security_policy "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Configuration/security.json"
click node_api_response "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Common/ApiResponse.cs"
click node_auth_controller "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/AuthController.cs"
click node_task_controller "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/TasksController.cs"
click node_admin_controller "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/AdminController.cs"
click node_auth_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/AuthenticationService.cs"
click node_login_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/LoginService.cs"
click node_two_factor "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/TwoFactorAuthService.cs"
click node_task_services "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/MathTaskProcessingService.cs"
click node_user_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/UserManagementService.cs"
click node_report_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/ReportService.cs"
click node_admin_services "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Admin/AdminService.cs"
click node_cache_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/CacheService.cs"
click node_mail_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/MailService.cs"
click node_captcha_service "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/CaptchaValidationService.cs"
click node_db_context "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.DAL/Database/AppDbContext.cs"
click node_solution_hub "https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.Protos/solution_hub.proto"

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_program,node_middleware,node_security_policy,node_controllers,node_api_response,node_auth_controller,node_task_controller,node_admin_controller toneBlue
class node_auth_service,node_login_service,node_two_factor,node_task_services,node_user_service,node_report_service,node_admin_services,node_cache_service,node_mail_service,node_captcha_service,node_contracts toneAmber
class node_db_context,node_identity_artifacts,node_repositories,node_solution_hub toneMint
```

## Components

### HTTP API

ASP.NET entry point, pipeline, and endpoints.

- [Runtime composition](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Program.cs): .NET host · Configures dependency injection, middleware, and HTTP pipeline. · `MatHelper.API/Program.cs`
- [Request protection](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs): middleware · Duplicate request handling, limits, and error logging. · `MatHelper.API/Middlewares/DuplicateRequestMiddleware.cs`
- [Limit policy](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Configuration/security.json): security config · `MatHelper.API/Configuration/security.json`
- **Public endpoints**: controllers · HTTP endpoints return normalized API responses.
- [Normalized responses](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Common/ApiResponse.cs): response contract · `MatHelper.API/Common/ApiResponse.cs`
- [Auth and security endpoints](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/AuthController.cs): controllers · Registration, login, recovery, token, and 2FA entry points. · `MatHelper.API/Controllers/AuthController.cs`
- [Task endpoints](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/TasksController.cs): controller · `MatHelper.API/Controllers/TasksController.cs`
- [Admin endpoints](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.API/Controllers/AdminController.cs): controller · `MatHelper.API/Controllers/AdminController.cs`

### Business services

Application workflows and domain processing.

- [Authentication workflow](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/AuthenticationService.cs): auth service · Orchestrates account and token lifecycle flows. · `MatHelper.BLL/Services/Auth/AuthenticationService.cs`
- [Login protection](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/LoginService.cs): auth service · Handles login attempts and credentials. · `MatHelper.BLL/Services/Auth/LoginService.cs`
- [Two-factor auth](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Auth/TwoFactorAuthService.cs): auth service · `MatHelper.BLL/Services/Auth/TwoFactorAuthService.cs`
- [Math and geometry processing](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/MathTaskProcessingService.cs): task services · Processes computational task requests. · `MatHelper.BLL/Services/MathTaskProcessingService.cs`
- [User management](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/UserManagementService.cs): user service · `MatHelper.BLL/Services/UserManagementService.cs`
- [Reports](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/ReportService.cs): report service · `MatHelper.BLL/Services/ReportService.cs`
- [Administration and analytics](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/Admin/AdminService.cs): admin services · Manages users, settings, tokens, logs, and analytics. · `MatHelper.BLL/Services/Admin/AdminService.cs`
- [Cache service](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/CacheService.cs): cache service · `MatHelper.BLL/Services/CacheService.cs`
- [Mail delivery](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/MailService.cs): mail service · `MatHelper.BLL/Services/MailService.cs`
- [CAPTCHA validation](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.BLL/Services/CaptchaValidationService.cs): external adapter · Encapsulates CAPTCHA provider validation. · `MatHelper.BLL/Services/CaptchaValidationService.cs`
- **Shared contracts**: models and options · DTOs, enums, options, and shared contracts.

### Data and integrations

Persistence and external service boundaries.

- [EF Core persistence](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.DAL/Database/AppDbContext.cs): DbContext · Data access boundary for PostgreSQL-backed entities. · `MatHelper.DAL/Database/AppDbContext.cs`
- **Identity and session data**: persistent models · Users, tokens, email codes, recovery tokens, and 2FA sessions.
- **Repositories**: data access
- [Solution hub contract](https://github.com/kimrenny/gmhelper-api/blob/main/MatHelper.Protos/solution_hub.proto): protobuf integration · Contract for external solution processing. · `MatHelper.Protos/solution_hub.proto`

## Connections

- Runtime composition → Request protection: installs
- Runtime composition → Public endpoints: routes to
- Request protection → Limit policy: uses
- Request protection → Public endpoints: protects
- Public endpoints → Normalized responses: returns
- Auth and security endpoints → Authentication workflow: authenticates via
- Authentication workflow → Login protection: uses
- Authentication workflow → Two-factor auth: uses
- Authentication workflow → Identity and session data: manages
- Task endpoints → Math and geometry processing: submits tasks
- Math and geometry processing → Solution hub contract: integrates with
- Public endpoints → User management: invokes
- Public endpoints → Reports: invokes
- Admin endpoints → Administration and analytics: administers via
- Authentication workflow → CAPTCHA validation: validates
- Authentication workflow → Mail delivery: sends codes through
- User management → Repositories: persists through
- Administration and analytics → Repositories: queries through
- Reports → Repositories: reads through
- Repositories → EF Core persistence: uses
- EF Core persistence → Identity and session data: stores
- Cache service → EF Core persistence: backs application data
- Authentication workflow → Shared contracts: uses