Commerce
Architecture
Modular architecture overview for Hanzo Commerce
Hanzo Commerce is built as a set of composable modules in Go, fronted by a TypeScript SDK and an admin dashboard. Each module owns its data model, business logic, and API surface.
System Overview
┌─────────────────────────────────────────────────────┐
│ Clients │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │Storefront│ │ Admin │ │ Mobile / CLI │ │
│ │ (Next.js)│ │Dashboard │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────────┬──────────┘ │
└───────┼──────────────┼─────────────────┼─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────┐
│ TypeScript SDK │
│ @hanzo/commerce · @hanzo/commerce-admin │
└──────────────────────┬──────────────────────────────┘
│ REST / WebSocket
▼
┌─────────────────────────────────────────────────────┐
│ Go API Gateway (commerce) │
│ ┌─────────┐ ┌──────┐ ┌────────┐ ┌──────────────┐ │
│ │ Auth │ │ Rate │ │ CORS │ │ Idempotency │ │
│ │Middleware│ │Limit │ │ │ │ │ │
│ └─────────┘ └──────┘ └────────┘ └──────────────┘ │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────┴──────────────────────────────┐
│ Module Layer │
│ ┌────────┐ ┌───────┐ ┌─────┐ ┌────────┐ ┌───────┐ │
│ │Product │ │ Order │ │Cart │ │Payment │ │Region │ │
│ ├────────┤ ├───────┤ ├─────┤ ├────────┤ ├───────┤ │
│ │Customer│ │Fulfill│ │ Tax │ │Pricing │ │Promo │ │
│ ├────────┤ ├───────┤ ├─────┤ ├────────┤ ├───────┤ │
│ │Inventory│ │Subscr.│ │Analyt│ │Webhook │ │Search │ │
│ └────────┘ └───────┘ └─────┘ └────────┘ └───────┘ │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────┴──────────────────────────────┐
│ Data Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │PostgreSQL│ │ Redis │ │ ClickHouse │ │
│ │(primary) │ │ (cache) │ │ (analytics) │ │
│ └──────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────┘Module Design
Each module follows a consistent internal structure:
module/
├── handler.go # HTTP handlers
├── service.go # Business logic
├── repository.go # Data access
├── model.go # Domain types
├── events.go # Event definitions
└── module.go # Registration and wiringModules communicate via an internal event bus. For example, when the Order module transitions an order to confirmed, the Inventory module receives a reservation event and the Analytics module records the conversion.
Data Flow
Storefront Purchase
Browser ──► SDK.cart.addItem()
│
▼
POST /cart/:id/item ──► Cart Module
│ │
│ Pricing Module (price calc)
│ Tax Module (tax calc)
│ Promotion Module (discounts)
│ │
▼ ▼
POST /checkout/authorize ──► Payment Module
│ │
│ Stripe / PayPal / Crypto
│ │
▼ ▼
Order created ──► Fulfillment Module
Inventory Module
Analytics ModuleTech Stack
| Layer | Technology | Purpose |
|---|---|---|
| API | Go 1.21+ | HTTP handlers, business logic |
| Database | PostgreSQL 15+ | Primary data store |
| Cache | Redis 7+ | Sessions, cart state, rate limiting |
| Analytics | ClickHouse | Event storage, dashboards |
| Search | PostgreSQL FTS / Meilisearch | Product search |
| SDK | TypeScript | Client libraries |
| Admin | Next.js + @hanzo/ui | Admin dashboard |
| Auth | Hanzo ID (OAuth2) | Authentication and authorization |
Key Principles
- Module isolation -- each module can be developed, tested, and scaled independently
- Event-driven -- modules react to domain events rather than direct calls where possible
- Idempotent APIs -- every mutating endpoint accepts an
Idempotency-Keyheader - Multi-tenant -- a single deployment can serve multiple stores via organization scoping
- Prices in minor units -- all monetary values are integers in the smallest currency unit (e.g. cents)
Next Steps
How is this guide?
Last updated on