# hamc0d3r/real-time-auction-system architecture

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

- Interactive diagram: https://gitdiagram.com/hamc0d3r/real-time-auction-system
- Repository: https://github.com/hamc0d3r/real-time-auction-system

## Overview

1. **Repository shape**
   - This is a monorepo with three main product surfaces: a .NET backend, a Next.js frontend, and separate application/domain tests.
   - The backend is split into `Domain`, `Application`, and `Infrastructure`, with `MazadZone.Api` as the HTTP/real-time entry point.
   - The frontend lives in `src/mazadzone-client` and consumes the backend APIs plus SignalR hubs.

2. **Backend entry point**
   - `MazadZone.Api` is a minimal-API style host exposing feature-based endpoint modules for auth, users, bidders, sellers, auctions, orders, payments, notifications, and categories.
   - It also contains middleware, request binding helpers, OpenAPI customization, and correlation-id support for tracing requests through logs.
   - The API layer is thin: it translates HTTP requests into application commands/queries and returns DTOs/results.

3. **Application layer as the orchestration boundary**
   - `MazadZone.Application` is the main orchestration layer, organized by feature and by CQRS intent: commands, queries, DTOs, validators, and event handlers.
   - Cross-cutting MediatR-style pipeline behaviors handle validation, logging, performance timing, caching, cache invalidation, and unhandled exceptions.
   - The application layer defines service interfaces for things the domain/use-cases need: repositories, cache, email, tokens, password hashing, payment, job scheduling, time, query services, and real-time notifications.

4. **Domain model and business boundaries**
   - `MazadZone.Domain` holds the core business model: auctions, bids, bidders, categories, notifications, orders, payments, sellers, and users.
   - Aggregates are modeled with rich value objects and domain events, such as `AuctionCreated`, `BidPlaced`, `OrderConfirmed`, `UserSuspended`, and `PaymentCompleted`.
   - The domain also defines repository interfaces, policies, error types, and primitive result abstractions, keeping business rules independent of persistence or transport.

5. **Primary business flows**
   - **Auctions**: create, activate, place bids, end/cancel, fetch details, and find similar auctions.
   - **Bidders/Users**: register, verify, activate, suspend, ban, change email/password, and manage profile data.
   - **Orders/Payments**: create an order from a winning bid, authorize/capture holds, confirm/ship/deliver, pay remaining amounts, handle disputes, and collect feedback.
   - **Sellers/Categories/Notifications**: seller onboarding/verification, category tree management, and user-facing notification creation/read/delete flows.

6. **Events drive side effects**
   - Many command handlers raise domain events that fan out into independent handlers in the application layer.
   - Examples: bidding can trigger outbid notifications and payment authorization changes; order completion triggers email/in-app notifications; user suspension can cancel auctions and remove bids.
   - This design separates the core state change from side effects like messaging, email, and downstream state adjustments.

7. **Infrastructure and persistence**
   - `MazadZone.Infrastructure` provides EF Core persistence, migrations, SQL connection factory support, repositories, and unit-of-work implementation.
   - It also contains value-object converters, entity configurations, seeding, and an outbox interceptor for reliable event publication.
   - The persistence model is backed by a relational database; the presence of migrations, configurations, and SQL connection factory indicates a DB-centric architecture.

8. **Reliability and async processing**
   - The outbox pattern is explicit: domain events are captured into `OutboxMessage`, then processed by `ProcessOutboxMessagesJob`.
   - Hangfire is used for background scheduling, with auction and order job schedulers implemented in infrastructure.
   - This lets the system defer non-immediate work such as auction ending, order processing, and event dispatch outside the request thread.

9. **Real-time delivery**
   - SignalR hubs in infrastructure expose live channels for auctions and notifications.
   - The frontend has dedicated SignalR clients and a notification store/hook, so real-time updates can flow from backend domain events to browser UI without polling.
   - Auction bid updates and notification delivery are the clearest real-time boundaries in the system.

10. **External integration points**
   - Email delivery is abstracted behind `IEmailService` and implemented in infrastructure.
   - Authentication uses JWT/token services plus signing-key management and rotation support.
   - Payment processing is abstracted behind a payment service and payment-related domain/application flows, suggesting an external payment provider is involved even though the provider is hidden behind interfaces.

11. **Frontend architecture**
   - `mazadzone-client` is a Next.js app with route groups for main site, auth, admin, seller, and public detail pages.
   - Feature folders mirror backend domains: auctions, bidding, orders, seller, profile, notifications, disputes, admin, and auth.
   - The frontend uses a shared design-system/component layer plus feature-specific UI, validation schemas, and typed API clients.

12. **Frontend data flow**
   - UI pages call feature API modules, which wrap backend endpoints and feed React Query–style fetching/caching.
   - Global client-side state is used for auth and notifications, while real-time SignalR hooks update live notification/bidding state.
   - This gives a split between server-backed authoritative state and local UI state for interactivity.

13. **Cross-cutting concerns**
   - The backend emphasizes strong typing, validation, caching, and observability through logs and correlation IDs.
   - OpenAPI customization and strongly typed ID transformers improve contract clarity for clients.
   - The frontend uses reusable UI primitives, toast/feedback components, and route-level layouts to keep admin/auth/main experiences separate.

14. **Tests and quality gates**
   - Tests are organized by layer: domain tests for pure business rules, application tests for handlers/validators/event handlers, and an infrastructure test project scaffold.
   - This mirrors the production boundaries closely, which is useful for diagramming: most logic is meant to be testable without the web host.
   - CI is present via GitHub Actions, and Docker/compose files indicate the system is intended to run in containerized environments.

15. **How to draw the architecture**
   - A good diagram would show: browser/Next.js client on one side; API host in the middle; application/use-case layer below it; domain at the core; infrastructure underneath connecting to database, background jobs, email, cache, and SignalR.
   - Then add side channels for outbox/background processing and real-time hubs, because not all business effects happen synchronously inside the HTTP request.

Main entry points: [`src/MazadZone.Application`](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application) (Application), [`src/MazadZone.Infrastructure/Services`](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Services) (Integrations), [`src/mazadzone-client`](https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client) (Next.js Client), [`src/MazadZone.Api`](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api) (API Host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_client_app["Next.js Client<br/>nextjs app"]
  node_client_api["API Clients<br/>typed fetch"]
  node_client_state["Client State<br/>react state"]
  node_client_realtime["Realtime Hooks<br/>signalr clients"]
end

subgraph group_backend["Backend"]
  node_api_host["API Host<br/>[MazadZone.Api]"]
  node_api_endpoints["Endpoints<br/>feature routes<br/>[Endpoints]"]
  node_api_crosscutting["API Middleware<br/>http plumbing<br/>[Middlewares]"]
  node_app_layer["Application<br/>orchestration layer"]
  node_app_behaviors["Pipeline Behaviors<br/>MediatR cross-cutting<br/>[Behaviors]"]
  node_app_features["Feature Use Cases<br/>commands/queries<br/>[Features]"]
  node_app_events["Domain Event Handlers<br/>side effects<br/>[Features]"]
  node_app_services["Service Ports<br/>interfaces<br/>[Services]"]
  node_domain_core{{"Domain Model<br/>business core<br/>[MazadZone.Domain]"}}
  node_domain_repos["Repository Ports<br/>persistence interfaces<br/>[Repositories]"]
  node_infra_persistence[("Persistence<br/>ef core<br/>[Persistence]")]
  node_infra_outbox["Outbox Worker<br/>reliable dispatch<br/>[Outbox]"]
  node_infra_jobs["Job Scheduling<br/>hangfire jobs<br/>[Scheduling]"]
  node_infra_realtime["SignalR Hubs<br/>realtime delivery<br/>[RealTime]"]
  node_infra_services["Integrations<br/>infrastructure services<br/>[Services]"]
end

subgraph group_tests["Tests"]
  node_tests_domain["Domain Tests<br/>xunit tests<br/>[Tests.Domain]"]
  node_tests_application["Application Tests<br/>xunit tests<br/>[Tests.Application]"]
  node_tests_infra["Infrastructure Tests<br/>test scaffold"]
end

subgraph group_external["External"]
  node_db[("Relational DB<br/>sql database")]
  node_email_provider["Email Provider<br/>smtp/api"]
  node_payment_provider["Payment Provider<br/>external gateway"]
  node_cache_store["Cache Store<br/>redis cache"]
end

node_client_app -->|"calls"| node_client_api
node_client_app -->|"uses"| node_client_state
node_client_app -->|"subscribes"| node_client_realtime
node_client_api -->|"requests"| node_api_host
node_client_realtime -->|"connects"| node_infra_realtime
node_api_host -->|"routes"| node_api_endpoints
node_api_host -->|"applies"| node_api_crosscutting
node_api_endpoints -->|"dispatches"| node_app_layer
node_app_layer -->|"passes through"| node_app_behaviors
node_app_layer -->|"implements"| node_app_features
node_app_layer -->|"publishes"| node_app_events
node_app_layer -->|"depends on"| node_app_services
node_app_features -->|"executes rules"| node_domain_core
node_app_events -->|"uses"| node_infra_services
node_domain_core -->|"declares ports"| node_domain_repos
node_infra_persistence -->|"implements"| node_domain_repos
node_infra_persistence -->|"persists to"| node_db
node_infra_outbox -->|"reads/writes"| node_db
node_infra_outbox -->|"dispatches"| node_infra_realtime
node_infra_jobs -->|"schedules"| node_infra_outbox
node_infra_jobs -->|"runs use cases"| node_app_layer
node_infra_realtime -->|"implements"| node_app_services
node_infra_services -->|"sends mail"| node_email_provider
node_infra_services -->|"charges"| node_payment_provider
node_infra_services -->|"caches"| node_cache_store
node_tests_domain -.->|"verifies"| node_domain_core
node_tests_application -.->|"verifies"| node_app_layer
node_tests_infra -.->|"targets"| node_infra_persistence

click node_client_app "https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client"
click node_client_api "https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/lib/api"
click node_client_state "https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/stores"
click node_client_realtime "https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/lib/signalr"
click node_api_host "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api"
click node_api_endpoints "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api/Endpoints"
click node_api_crosscutting "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api/Middlewares"
click node_app_layer "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application"
click node_app_behaviors "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Common/Behaviors"
click node_app_features "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Features"
click node_app_events "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Features"
click node_app_services "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Services"
click node_domain_core "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Domain"
click node_domain_repos "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Domain/Repositories"
click node_infra_persistence "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Persistence"
click node_infra_outbox "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Outbox"
click node_infra_jobs "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Scheduling"
click node_infra_realtime "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/RealTime"
click node_infra_services "https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Services"
click node_tests_domain "https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Domain"
click node_tests_application "https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Application"
click node_tests_infra "https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Infrastructure"

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_client_app,node_client_api,node_client_state,node_client_realtime toneBlue
class node_api_host,node_api_endpoints,node_api_crosscutting,node_app_layer,node_app_behaviors,node_app_features,node_app_events,node_app_services,node_domain_core,node_domain_repos,node_infra_persistence,node_infra_outbox,node_infra_jobs,node_infra_realtime,node_infra_services toneAmber
class node_tests_domain,node_tests_application,node_tests_infra toneMint
class node_db,node_email_provider,node_payment_provider,node_cache_store toneRose
```

## Components

### Frontend

Next.js client and browser-side state

- [Next.js Client](https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client): nextjs app · Browser-facing UI with routed product surfaces and feature modules · `src/mazadzone-client`
- [API Clients](https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/lib/api): typed fetch · Feature API wrappers used by pages and hooks · `src/mazadzone-client/src/lib/api`
- [Client State](https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/stores): react state · Auth and notification stores plus query caching · `src/mazadzone-client/src/stores`
- [Realtime Hooks](https://github.com/hamc0d3r/real-time-auction-system/tree/main/src/mazadzone-client/src/lib/signalr): signalr clients · Browser SignalR connections for live bidding and notifications · `src/mazadzone-client/src/lib/signalr`

### Backend

.NET API, application, domain, and infrastructure

- [API Host](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api): minimal API host · HTTP entry point, endpoint modules, middleware, binding, and OpenAPI · `src/MazadZone.Api`
- [Endpoints](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api/Endpoints): feature routes · Thin HTTP modules for auth, users, auctions, orders, payments, notifications, categories, and sellers · `src/MazadZone.Api/Endpoints`
- [API Middleware](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Api/Middlewares): http plumbing · Correlation IDs, request helpers, claims/problem extensions, and OpenAPI transformers · `src/MazadZone.Api/Middlewares`
- [Application](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application): orchestration layer · CQRS use cases, validators, DTOs, pipeline behaviors, and event handlers · `src/MazadZone.Application`
- [Pipeline Behaviors](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Common/Behaviors): MediatR cross-cutting · Validation, logging, performance, caching, cache invalidation, and exception handling · `src/MazadZone.Application/Common/Behaviors`
- [Feature Use Cases](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Features): commands/queries · Auction, auth, bidder, category, notification, order, payment, seller, and user flows · `src/MazadZone.Application/Features`
- [Domain Event Handlers](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Features): side effects · Email, notifications, order/payment coordination, and state adjustments triggered by events · `src/MazadZone.Application/Features`
- [Service Ports](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Application/Services): interfaces · Abstractions for repositories, cache, email, tokens, hashing, payments, schedulers, time, queries, and realtime · `src/MazadZone.Application/Services`
- [Domain Model](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Domain): business core · Aggregates, value objects, policies, errors, and domain events for auctions, bids, users, sellers, orders, payments, notifications, and categories · `src/MazadZone.Domain`
- [Repository Ports](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Domain/Repositories): persistence interfaces · Unit of work and repository contracts defined by the domain · `src/MazadZone.Domain/Repositories`
- [Persistence](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Persistence): ef core · DbContext, configurations, converters, migrations, seeding, and SQL connection factory · `src/MazadZone.Infrastructure/Persistence`
- [Outbox Worker](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Outbox): reliable dispatch · Outbox capture and background processing for domain events · `src/MazadZone.Infrastructure/Outbox`
- [Job Scheduling](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Scheduling): hangfire jobs · Background scheduling for auction and order workflows · `src/MazadZone.Infrastructure/Scheduling`
- [SignalR Hubs](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/RealTime): realtime delivery · Auction and notification hubs plus stream/notifier services · `src/MazadZone.Infrastructure/RealTime`
- [Integrations](https://github.com/hamc0d3r/real-time-auction-system/blob/main/src/MazadZone.Infrastructure/Services): infrastructure services · Email, JWT/token handling, password hashing, cache, payment, date/time, and signing-key management · `src/MazadZone.Infrastructure/Services`

### Tests

Layered test projects

- [Domain Tests](https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Domain): xunit tests · Pure business-rule tests for aggregates and value objects · `tests/Tests.Domain`
- [Application Tests](https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Application): xunit tests · Handler, validator, and event-handler tests across feature boundaries · `tests/Tests.Application`
- [Infrastructure Tests](https://github.com/hamc0d3r/real-time-auction-system/blob/main/tests/Tests.Infrastructure): test scaffold · Infrastructure test project scaffold · `tests/Tests.Infrastructure`

### External

Infrastructure dependencies

- **Relational DB**: sql database · Primary persistence store behind EF Core and migrations
- **Email Provider**: smtp/api · External delivery target hidden behind the email service abstraction
- **Payment Provider**: external gateway · External payment system hidden behind payment abstractions
- **Cache Store**: redis cache · Shared cache used by application caching and invalidation

## Connections

- Next.js Client → API Clients: calls · Pages and feature components use typed API modules
- Next.js Client → Client State: uses · Client state and query caching support UI flows
- Next.js Client → Realtime Hooks: subscribes · Live auction and notification updates reach the browser
- API Clients → API Host: requests · Feature clients call backend endpoints
- Realtime Hooks → SignalR Hubs: connects · Browser SignalR clients connect to hubs
- API Host → Endpoints: routes · Host wires feature endpoint modules
- API Host → API Middleware: applies · Middleware and OpenAPI plumbing run around requests
- Endpoints → Application: dispatches · HTTP handlers translate requests into commands and queries
- Application → Pipeline Behaviors: passes through · CQRS requests flow through pipeline behaviors
- Application → Feature Use Cases: implements · Feature-specific commands and queries live here
- Application → Domain Event Handlers: publishes · Handlers and event handlers coordinate side effects
- Application → Service Ports: depends on · Use cases call abstractions instead of concrete infrastructure
- Feature Use Cases → Domain Model: executes rules · Commands and queries operate on the business model
- Domain Event Handlers → Integrations: uses · Side effects are implemented by infrastructure services
- Domain Model → Repository Ports: declares ports · Domain owns repository and unit-of-work contracts
- Persistence → Repository Ports: implements · EF Core repositories and unit of work fulfill domain ports
- Persistence → Relational DB: persists to · Database schema is managed by migrations and configurations
- Outbox Worker → Relational DB: reads/writes · Outbox messages are stored and processed from the database
- Outbox Worker → SignalR Hubs: dispatches · Captured events can fan out to live updates
- Job Scheduling → Outbox Worker: schedules · Background jobs process deferred work and event dispatch
- Job Scheduling → Application: runs use cases · Auction and order jobs execute application logic outside requests
- SignalR Hubs → Service Ports: implements · Realtime delivery fulfills application service contracts
- Integrations → Email Provider: sends mail · Email integration is delegated to an external provider
- Integrations → Payment Provider: charges · Payment flows are delegated to an external gateway
- Integrations → Cache Store: caches · Caching and invalidation use a shared cache backend
- Domain Tests → Domain Model: verifies · Domain tests cover core business invariants
- Application Tests → Application: verifies · Application tests cover handlers, validators, and event handlers
- Infrastructure Tests → Persistence: targets · Infrastructure tests are scaffolded around persistence concerns
