kimrenny/gmhelper-api

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.