How hamc0d3r/real-time-auction-system works
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: MazadZone.Application Application · Services Integrations · mazadzone-client Next.js Client · MazadZone.Api API Host
Components 26
Frontend
Next.js client and browser-side state
- Next.js Client · Browser-facing UI with routed product surfaces and feature modules
src/mazadzone-client - API Clients · Feature API wrappers used by pages and hooks
src/mazadzone-client/src/lib/api - Client State · Auth and notification stores plus query caching
src/mazadzone-client/src/stores - Realtime Hooks · Browser SignalR connections for live bidding and notifications
src/mazadzone-client/src/lib/signalr
Backend
.NET API, application, domain, and infrastructure
- API Host · HTTP entry point, endpoint modules, middleware, binding, and OpenAPI
src/MazadZone.Api - Endpoints · Thin HTTP modules for auth, users, auctions, orders, payments, notifications, categories, and sellers
src/MazadZone.Api/Endpoints - API Middleware · Correlation IDs, request helpers, claims/problem extensions, and OpenAPI transformers
src/MazadZone.Api/Middlewares - Application · CQRS use cases, validators, DTOs, pipeline behaviors, and event handlers
src/MazadZone.Application - Pipeline Behaviors · Validation, logging, performance, caching, cache invalidation, and exception handling
src/MazadZone.Application/Common/Behaviors - Feature Use Cases · Auction, auth, bidder, category, notification, order, payment, seller, and user flows
src/MazadZone.Application/Features - Domain Event Handlers · Email, notifications, order/payment coordination, and state adjustments triggered by events
src/MazadZone.Application/Features - Service Ports · Abstractions for repositories, cache, email, tokens, hashing, payments, schedulers, time, queries, and realtime
src/MazadZone.Application/Services - Domain Model · Aggregates, value objects, policies, errors, and domain events for auctions, bids, users, sellers, orders, payments, notifications, and categories
src/MazadZone.Domain - Repository Ports · Unit of work and repository contracts defined by the domain
src/MazadZone.Domain/Repositories - Persistence · DbContext, configurations, converters, migrations, seeding, and SQL connection factory
src/MazadZone.Infrastructure/Persistence - Outbox Worker · Outbox capture and background processing for domain events
src/MazadZone.Infrastructure/Outbox - Job Scheduling · Background scheduling for auction and order workflows
src/MazadZone.Infrastructure/Scheduling - SignalR Hubs · Auction and notification hubs plus stream/notifier services
src/MazadZone.Infrastructure/RealTime - Integrations · Email, JWT/token handling, password hashing, cache, payment, date/time, and signing-key management
src/MazadZone.Infrastructure/Services
Tests
Layered test projects
- Domain Tests · Pure business-rule tests for aggregates and value objects
tests/Tests.Domain - Application Tests · Handler, validator, and event-handler tests across feature boundaries
tests/Tests.Application - Infrastructure Tests · Infrastructure test project scaffold
tests/Tests.Infrastructure
External
Infrastructure dependencies
- Relational DB · Primary persistence store behind EF Core and migrations
- Email Provider · External delivery target hidden behind the email service abstraction
- Payment Provider · External payment system hidden behind payment abstractions
- Cache Store · Shared cache used by application caching and invalidation
Connections 28
- 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