# cpsu25/mamafit-server architecture

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

- Interactive diagram: https://gitdiagram.com/cpsu25/mamafit-server
- Repository: https://github.com/cpsu25/mamafit-server

## Overview

1. MamaFit Server is a .NET 8 ASP.NET Core Web API backend for a maternity fashion platform. It is organized as a layered monolith, with the API host, business/services layer, repository layer, and shared business objects split into separate projects.

2. `MamaFit.API` is the HTTP entrypoint. It hosts REST controllers, middleware, Swagger/OpenAPI, CORS, JWT auth, and startup wiring. The controllers are feature-oriented rather than generic: auth, users, catalog, measurements, appointments, carts, orders, payments, shipping, warranties, chat, notifications, analytics, and AI test endpoints.

3. `MamaFit.Services` contains the main business logic boundary. Service classes implement orchestration for each domain area, while validators enforce request rules with FluentValidation. This is where workflows such as order processing, design requests, measurement generation, appointment handling, and notification dispatch are coordinated.

4. `MamaFit.Repositories` is the persistence layer. It uses a generic repository and unit-of-work pattern over Entity Framework Core, with one repository interface/implementation per aggregate. This layer isolates query and data-access logic from service rules and is the only place that should directly depend on the EF context.

5. `MamaFit.BusinessObjects` holds the shared domain model: EF Core `ApplicationDBContext`, entities, DTOs, enums, seed data, and the design-time context factory. DTOs are heavily used at service/controller boundaries, so the public API contract is defined separately from the persistence entities.

6. The core domain spans several subsystems: catalog management (`Category`, `Style`, `Component`, `MaternityDress`, `Preset`, `AddOn`), customer operations (`Measurement`, `MeasurementDiary`, `Appointment`), commerce (`CartItem`, `Order`, `OrderItem`, `Transaction`, `Voucher*`), and post-purchase flows (`WarrantyRequest`, `WarrantyHistory`, `Feedback`, `Ticket`). These are distinct business areas but share the same data store and service host.

7. Authentication and authorization are central cross-cutting concerns. The repo includes JWT token helpers, refresh tokens, OTP flows, Google login DTOs, role/user entities, and a permission middleware. This indicates the API enforces access control at the HTTP pipeline layer as well as in service logic.

8. Real-time features are handled with SignalR hubs in `MamaFit.Services/Hubs`. Chat and notifications are pushed through dedicated hubs, with connection management utilities to map users to active connections. The API exposes hub endpoints separately from REST controllers, but they share the same auth and user model.

9. External integrations are modeled as first-class services under `MamaFit.Services/ExternalService`. The backend talks to Cloudinary for images, Redis for caching, GHTK for shipping and tracking, Sepay for QR payments and webhooks, Mailgun for email, Contentful for CMS sync, and AI providers via Groq or optional Ollama. These integrations are wrapped behind service interfaces so the domain layer does not depend on provider-specific APIs directly.

10. Background processing is done with Hangfire backed by PostgreSQL storage. Recurring jobs are registered at startup and include appointment reminders and measurement generation. The architecture therefore has both request/response paths and asynchronous scheduled workflows operating on the same database state.

11. The API host also owns cross-cutting infrastructure: exception middleware, permission middleware, logging via NLog, CORS policy constants, endpoint constants, and startup service registration in `ApplicationServiceExtension`. These concerns shape how requests enter the system and how failures, permissions, and diagnostics are handled.

12. Deployment is container-focused. The repo includes a Dockerfile, Compose files, and a GitHub Actions pipeline that restores, builds, tests, creates the Docker image, ships compose files, and deploys to a VPS. There is also filebeat configuration for log shipping, which suggests production logs are collected outside the application container.

13. For diagramming, the main boundaries to show are: external clients calling REST or SignalR endpoints; the API host applying auth/middleware; services orchestrating validation, domain rules, caches, and integrations; repositories persisting through EF Core/PostgreSQL; and external systems such as Redis, Cloudinary, GHTK, Sepay, Mailgun, Contentful, Groq/Ollama, and Hangfire as separate dependencies.

Main entry points: [`MamaFit.API/DependencyInjection/ApplicationServiceExtension.cs`](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/DependencyInjection/ApplicationServiceExtension.cs) (Startup DI), [`MamaFit.API/Program.cs`](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Program.cs) (Program), [`MamaFit.Repositories/Repository/OrderRepository.cs`](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Repository/OrderRepository.cs) (Repositories), [`MamaFit.Services/Validator/ValidatorAssemblyReference.cs`](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Validator/ValidatorAssemblyReference.cs) (Validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Host"]
  node_api_program["Program<br/>ASP.NET host<br/>[Program.cs]"]
  node_api_di["Startup DI<br/>service registration"]
  node_api_mw["Middleware<br/>request pipeline"]
  node_api_auth["Auth API<br/>REST controllers<br/>[AuthController.cs]"]
  node_api_catalog["Catalog API<br/>REST controllers"]
  node_api_commerce["Commerce API<br/>REST controllers<br/>[OrderController.cs]"]
  node_api_customer["Customer API<br/>REST controllers"]
  node_api_realtime(("Realtime API<br/>SignalR hubs<br/>[ChatHub.cs]"))
end

subgraph group_services["Business Services"]
  node_svc_auth["Identity<br/>auth services<br/>[AuthService.cs]"]
  node_svc_catalog["Catalog<br/>domain services<br/>[CategoryService.cs]"]
  node_svc_commerce["Commerce<br/>workflow services<br/>[OrderService.cs]"]
  node_svc_customer["Customer Ops<br/>workflow services"]
  node_svc_realtime(("Realtime<br/>signalr services<br/>[NotificationHub.cs]"))
  node_svc_infra["Integrations<br/>external adapters<br/>[GhtkService.cs]"]
  node_svc_jobs["Jobs<br/>background processing"]
  node_svc_validation["Validation<br/>fluent validators"]
end

subgraph group_data["Domain Model"]
  node_domain_ctx[("DB Context<br/>ef core context")]
  node_domain_model["Entities<br/>[Order.cs]"]
  node_domain_dto["DTOs<br/>contract models<br/>[OrderRequestDto.cs]"]
end

subgraph group_repo["Persistence"]
  node_repo_uow["Unit of Work<br/>repository core<br/>[UnitOfWork.cs]"]
  node_repo_access["Repositories<br/>[OrderRepository.cs]"]
  node_repo_helpers["Repo Helpers<br/>shared infra<br/>[JwtTokenHelper.cs]"]
end

subgraph group_ops["Delivery & Ops"]
  node_ops_ci["CI Pipeline<br/>github actions<br/>[main.yml]"]
  node_ops_deploy["Deployment<br/>container ops"]
end

node_api_program -->|"registers"| node_api_di
node_api_program -->|"uses"| node_api_mw
node_api_program -->|"hosts"| node_api_auth
node_api_program -->|"hosts"| node_api_catalog
node_api_program -->|"hosts"| node_api_commerce
node_api_program -->|"hosts"| node_api_customer
node_api_program -->|"maps"| node_api_realtime
node_api_di -->|"injects"| node_svc_auth
node_api_di -->|"injects"| node_svc_catalog
node_api_di -->|"injects"| node_svc_commerce
node_api_di -->|"injects"| node_svc_customer
node_api_di -->|"injects"| node_svc_realtime
node_api_di -->|"injects"| node_svc_infra
node_api_di -->|"schedules"| node_svc_jobs
node_api_di -->|"adds"| node_svc_validation
node_api_auth -->|"calls"| node_svc_auth
node_api_catalog -->|"calls"| node_svc_catalog
node_api_commerce -->|"calls"| node_svc_commerce
node_api_customer -->|"calls"| node_svc_customer
node_api_realtime -->|"pushes"| node_svc_realtime
node_svc_auth -->|"validates"| node_svc_validation
node_svc_catalog -->|"validates"| node_svc_validation
node_svc_commerce -->|"validates"| node_svc_validation
node_svc_customer -->|"validates"| node_svc_validation
node_svc_auth -->|"persists"| node_repo_access
node_svc_catalog -->|"persists"| node_repo_access
node_svc_commerce -->|"persists"| node_repo_access
node_svc_customer -->|"persists"| node_repo_access
node_svc_realtime -->|"reads"| node_repo_access
node_svc_infra -.->|"supports"| node_repo_access
node_svc_jobs -->|"operates on"| node_repo_access
node_repo_access -->|"coordinates"| node_repo_uow
node_repo_uow -->|"uses"| node_domain_ctx
node_repo_access -->|"queries"| node_domain_ctx
node_domain_ctx -->|"maps"| node_domain_model
node_svc_validation -->|"checks"| node_domain_dto
node_api_auth -->|"accepts"| node_domain_dto
node_api_catalog -->|"accepts"| node_domain_dto
node_api_commerce -->|"accepts"| node_domain_dto
node_api_customer -->|"accepts"| node_domain_dto
node_ops_ci -->|"packages"| node_ops_deploy
node_ops_deploy -->|"runs"| node_api_program

click node_api_program "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Program.cs"
click node_api_di "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/DependencyInjection/ApplicationServiceExtension.cs"
click node_api_mw "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Middlewares/ExceptionMiddleware.cs"
click node_api_auth "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/AuthController.cs"
click node_api_catalog "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/CategoryController.cs"
click node_api_commerce "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/OrderController.cs"
click node_api_customer "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/MeasurementController.cs"
click node_api_realtime "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Hubs/ChatHub.cs"
click node_svc_auth "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/AuthService.cs"
click node_svc_catalog "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/CategoryService.cs"
click node_svc_commerce "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/OrderService.cs"
click node_svc_customer "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/MeasurementService.cs"
click node_svc_realtime "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Hubs/NotificationHub.cs"
click node_svc_infra "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/ExternalService/Ghtk/GhtkService.cs"
click node_svc_jobs "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/ExternalService/CronJob/RecurringJobScheduler.cs"
click node_svc_validation "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Validator/ValidatorAssemblyReference.cs"
click node_domain_ctx "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/DBContext/ApplicationDBContext.cs"
click node_domain_model "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/Entity/Order.cs"
click node_domain_dto "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/DTO/OrderDto/OrderRequestDto.cs"
click node_repo_uow "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Implement/UnitOfWork.cs"
click node_repo_access "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Repository/OrderRepository.cs"
click node_repo_helpers "https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Helper/JwtTokenHelper.cs"
click node_ops_ci "https://github.com/cpsu25/mamafit-server/blob/main/.github/workflows/main.yml"
click node_ops_deploy "https://github.com/cpsu25/mamafit-server/tree/main/Dockerfile"

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_program,node_api_di,node_api_mw,node_api_auth,node_api_catalog,node_api_commerce,node_api_customer,node_api_realtime toneBlue
class node_svc_auth,node_svc_catalog,node_svc_commerce,node_svc_customer,node_svc_realtime,node_svc_infra,node_svc_jobs,node_svc_validation toneAmber
class node_domain_ctx,node_domain_model,node_domain_dto toneMint
class node_repo_uow,node_repo_access,node_repo_helpers toneRose
class node_ops_ci,node_ops_deploy toneIndigo
```

## Components

### API Host

HTTP entrypoint, middleware, controllers, and startup wiring.

- [Program](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Program.cs): ASP.NET host · Bootstraps the Web API, middleware, auth, Swagger, CORS, and DI. · `MamaFit.API/Program.cs`
- [Startup DI](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/DependencyInjection/ApplicationServiceExtension.cs): service registration · Registers application services and cross-cutting API configuration. · `MamaFit.API/DependencyInjection/ApplicationServiceExtension.cs`
- [Middleware](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Middlewares/ExceptionMiddleware.cs): request pipeline · Exception handling and permission enforcement at the HTTP layer. · `MamaFit.API/Middlewares/ExceptionMiddleware.cs`
- [Auth API](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/AuthController.cs): REST controllers · Login, token, OTP, roles, and user-facing identity endpoints. · `MamaFit.API/Controllers/AuthController.cs`
- [Catalog API](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/CategoryController.cs): REST controllers · Category, style, component, dress, add-on, branch, and size endpoints. · `MamaFit.API/Controllers/CategoryController.cs`
- [Commerce API](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/OrderController.cs): REST controllers · Cart, order, payment, shipping, voucher, and transaction endpoints. · `MamaFit.API/Controllers/OrderController.cs`
- [Customer API](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.API/Controllers/MeasurementController.cs): REST controllers · Measurements, appointments, design requests, feedback, and support endpoints. · `MamaFit.API/Controllers/MeasurementController.cs`
- [Realtime API](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Hubs/ChatHub.cs): SignalR hubs · Chat and notification hub endpoints for push-style interaction. · `MamaFit.Services/Hubs/ChatHub.cs`

### Business Services

Orchestration, validation, hubs, and external adapters.

- [Identity](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/AuthService.cs): auth services · JWT, refresh token, OTP, roles, permissions, and user workflows. · `MamaFit.Services/Service/AuthService.cs`
- [Catalog](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/CategoryService.cs): domain services · Manages product taxonomy, styles, components, presets, and dress data. · `MamaFit.Services/Service/CategoryService.cs`
- [Commerce](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/OrderService.cs): workflow services · Coordinates cart, order, payment, shipment, voucher, and transaction flows. · `MamaFit.Services/Service/OrderService.cs`
- [Customer Ops](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Service/MeasurementService.cs): workflow services · Handles measurements, appointments, design requests, feedback, and support. · `MamaFit.Services/Service/MeasurementService.cs`
- [Realtime](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Hubs/NotificationHub.cs): signalr services · Chat and notification delivery plus connection management. · `MamaFit.Services/Hubs/NotificationHub.cs`
- [Integrations](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/ExternalService/Ghtk/GhtkService.cs): external adapters · Cloudinary, Redis cache, GHTK shipping, Sepay payments, Mailgun email, Contentful CMS, and AI providers. · `MamaFit.Services/ExternalService/Ghtk/GhtkService.cs`
- [Jobs](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/ExternalService/CronJob/RecurringJobScheduler.cs): background processing · Recurring jobs for reminders and measurement generation via Hangfire scheduling. · `MamaFit.Services/ExternalService/CronJob/RecurringJobScheduler.cs`
- [Validation](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Services/Validator/ValidatorAssemblyReference.cs): fluent validators · Request validation rules for API and service boundary DTOs. · `MamaFit.Services/Validator/ValidatorAssemblyReference.cs`

### Domain Model

Shared entities, DTOs, enums, and EF Core context.

- [DB Context](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/DBContext/ApplicationDBContext.cs): ef core context · ApplicationDbContext and design-time factory defining the database model. · `MamaFit.BusinessObjects/DBContext/ApplicationDBContext.cs`
- [Entities](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/Entity/Order.cs): domain entities · Core persistence model for users, catalog, commerce, and post-purchase workflows. · `MamaFit.BusinessObjects/Entity/Order.cs`
- [DTOs](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.BusinessObjects/DTO/OrderDto/OrderRequestDto.cs): contract models · Boundary models used by controllers and services for requests and responses. · `MamaFit.BusinessObjects/DTO/OrderDto/OrderRequestDto.cs`

### Persistence

Repositories and unit-of-work over EF Core.

- [Unit of Work](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Implement/UnitOfWork.cs): repository core · Generic repository and transaction boundary for persistence coordination. · `MamaFit.Repositories/Implement/UnitOfWork.cs`
- [Repositories](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Repository/OrderRepository.cs): ef repositories · Aggregate-specific repositories encapsulating queries and persistence details. · `MamaFit.Repositories/Repository/OrderRepository.cs`
- [Repo Helpers](https://github.com/cpsu25/mamafit-server/blob/main/MamaFit.Repositories/Helper/JwtTokenHelper.cs): shared infra · Persistence-related helpers such as JWT, hashing, ordering, paging, and response models. · `MamaFit.Repositories/Helper/JwtTokenHelper.cs`

### Delivery & Ops

Container and CI/CD artifacts.

- [CI Pipeline](https://github.com/cpsu25/mamafit-server/blob/main/.github/workflows/main.yml): github actions · Build, test, image, compose packaging, and deployment workflow. · `.github/workflows/main.yml`
- [Deployment](https://github.com/cpsu25/mamafit-server/tree/main/Dockerfile): container ops · Docker, compose, and log shipping configuration for containerized release. · `Dockerfile`

## Connections

- Program → Startup DI: registers · Program wires the application services and infrastructure setup.
- Program → Middleware: uses · HTTP requests flow through exception and permission middleware.
- Program → Auth API: hosts · API exposes authentication controllers.
- Program → Catalog API: hosts · API exposes catalog and product controllers.
- Program → Commerce API: hosts · API exposes commerce controllers.
- Program → Customer API: hosts · API exposes customer-operation controllers.
- Program → Realtime API: maps · Program maps SignalR hub endpoints.
- Startup DI → Identity: injects · Registers identity and auth services.
- Startup DI → Catalog: injects · Registers catalog services.
- Startup DI → Commerce: injects · Registers commerce services.
- Startup DI → Customer Ops: injects · Registers customer workflow services.
- Startup DI → Realtime: injects · Registers hubs and connection services.
- Startup DI → Integrations: injects · Registers external adapters and caching/payment/email services.
- Startup DI → Jobs: schedules · Registers recurring background jobs.
- Startup DI → Validation: adds · Registers validator assembly and request validation.
- Auth API → Identity: calls · Auth controllers delegate identity workflows to services.
- Catalog API → Catalog: calls · Catalog controllers delegate to domain services.
- Commerce API → Commerce: calls · Commerce controllers delegate to order/payment workflows.
- Customer API → Customer Ops: calls · Customer controllers delegate to measurement and appointment workflows.
- Realtime API → Realtime: pushes · Hubs use realtime services to manage messaging and notifications.
- Identity → Validation: validates · Identity requests are validated before execution.
- Catalog → Validation: validates · Catalog requests are validated before mutations.
- Commerce → Validation: validates · Commerce workflows validate incoming commands.
- Customer Ops → Validation: validates · Customer workflows validate measurement and appointment input.
- Identity → Repositories: persists · Identity services read and write through repositories.
- Catalog → Repositories: persists · Catalog services persist through repositories.
- Commerce → Repositories: persists · Commerce services persist through repositories.
- Customer Ops → Repositories: persists · Customer services persist through repositories.
- Realtime → Repositories: reads · Realtime features resolve users and chat state from persistence.
- Integrations → Repositories: supports · Adapters support shipping, payment, cache, and storage workflows.
- Jobs → Repositories: operates on · Scheduled jobs act on persisted appointments and measurements.
- Repositories → Unit of Work: coordinates · Repositories operate under a unit-of-work boundary.
- Unit of Work → DB Context: uses · Unit of work depends on the EF Core context.
- Repositories → DB Context: queries · Repositories query the application database context.
- DB Context → Entities: maps · The DbContext maps entities to the database schema.
- Validation → DTOs: checks · Validators target DTOs exchanged across boundaries.
- Auth API → DTOs: accepts · Controllers bind request/response DTOs.
- Catalog API → DTOs: accepts · Controllers bind request/response DTOs.
- Commerce API → DTOs: accepts · Controllers bind request/response DTOs.
- Customer API → DTOs: accepts · Controllers bind request/response DTOs.
- CI Pipeline → Deployment: packages · Pipeline builds container and deployment artifacts.
- Deployment → Program: runs · Containerized deployment hosts the API entrypoint.