Velora is a self-hosted, headless commerce engine built in Go. It is designed as a modular monolith compiled into a single static binary that runs with zero required external services (no Redis, no message broker, no background sidecars).
Unlike enterprise commerce backends designed to scale to massive global traffic, Velora is optimized for operational economics and maintenance simplicity at scale of instances. It is built for agencies, platform teams, and independent developers who need to run and operate many isolated tenant stores on minimal infrastructure footprint (e.g., twenty client stores sharing a single modest VM).
Velora implements a strict Hexagonal Architecture (Ports and Adapters) inside a Modular Monolith. Business logic is entirely decoupled from database engines, transport protocols, and third-party APIs.
graph TB
Client[Storefront / Admin UI / API Client] -->|HTTPS| Proxy[Reverse Proxy e.g. Caddy/Nginx]
Proxy --> API
subgraph Binary["Single Static Go Binary"]
API[API Layer<br/>routing · auth · validation] --> App[Application Layer<br/>use cases / orchestration]
App --> Domain[Domain Layer<br/>Catalog · Customer · Cart<br/>Order · Inventory]
Domain -->|emits| Events[Internal Event Bus]
Events -->|sync dispatch| Jobs[Async Job Runner]
Events -->|outbound| Webhooks[Webhook Dispatcher]
Domain -->|Port Interfaces| Repo[Persistence Repositories]
end
Repo --> SQLite[("SQLite<br/>(local db file)")]
Repo --> Postgres[("PostgreSQL<br/>(production db)")]
Jobs --> DBJobs[("Job Queue Tables")]
style Binary fill:#f9f9f9,stroke:#333,stroke-width:2px
style Domain fill:#d4e6f1,stroke:#2980b9,stroke-width:1px
style Repo fill:#d5f5e3,stroke:#27ae60,stroke-width:1px
sequenceDiagram
participant Client as API Client
participant API as API Layer (HTTP)
participant App as Application Use Cases
participant Domain as Domain Entities
participant DB as DB (Postgres/SQLite)
participant Bus as Event Bus (In-Process)
participant Runner as Async Job Runner
Client->>API: HTTP POST /v1/store/checkout
API->>API: Authenticate & Validate Request
API->>App: Invoke PlaceOrder() Use Case
App->>Domain: Execute Checkout Business Logic
Domain->>DB: Atomic Reserve Stock & Create Order (Transaction)
DB-->>Domain: Success
Domain->>Bus: Publish event "order.placed"
Domain-->>App: Order Entity
App-->>API: Response Payload
API-->>Client: HTTP 201 Created (Fast Response)
Note over Bus,Runner: Event handled asynchronously out of the request path
Bus->>Runner: Enqueue async jobs (e.g. email, webhooks, payments)
Runner->>DB: Persist job metadata for execution and retry
- Zero External Runtime Dependencies: Velora replaces Redis and RabbitMQ with an in-process, memory-efficient synchronous/asynchronous Event Bus and a database-backed, transactional background Job Runner (
platform/jobs) supporting exponential backoff. - Strict Boundary Enforcements: The codebase contains a custom boundary checker script (
scripts/check_imports.go) executed on every commit. Thedomain/package has zero imports fromapi/orplatform/, preventing infrastructure concerns from leaking into core commerce rules. - Persisted Stateless Carts: Unlike systems that store carts in session caches, Velora persists carts directly in SQLite/PostgreSQL. This ensures process crashes never lose user items and supports asynchronous abandoned-cart recovery.
- Dual DB Migration Engine: The platform supports both SQLite (for zero-install development/micro-stores) and PostgreSQL (for standard production environments). SQL schema migrations are embedded directly inside the binary and executed automatically at startup.
├── api/ # HTTP transport layer (router, middleware, response serializers)
│ └── handler/ # Controller handlers (separated by /admin and /customer concerns)
├── application/ # Orchestration layer coordinating domain use cases and infrastructure ports
├── cmd/
│ ├── server/ # Main entry point for the HTTP commerce server
│ └── cli/ # Command-line utility for administrative tasks and diagnostics
├── docs/ # Architecture blueprints, vision document, and 10 detailed ADRs
├── domain/ # Pure business logic, aggregates, and DB repository Port interfaces
│ ├── catalog/ # Product entities, variants, catalog repository definitions
│ ├── customer/ # User accounts, addresses, hashing logic (Argon2id)
│ ├── cart/ # Cart aggregations and mutations
│ ├── order/ # Checkout flow and Order state machines
│ └── inventory/ # Stock levels and atomic reservations
├── events/ # Standardized event formats and structures
├── platform/ # Adapter implementations for database, cryptography, jobs, and mailers
│ ├── sqlite/ # SQLite repository implementations and local schema migrations
│ ├── postgres/ # PostgreSQL repository implementations and production schema migrations
│ ├── jobs/ # Background queue execution engine
│ └── auth/ # JWT issuing and token verification
└── tests/ # Full-stack integration and concurrency race test suites
- Go: 1.25.x or higher installed.
Copy the default environment configuration:
cp .env.example .envStart the HTTP server. It will compile, run database schema migrations automatically, start the background job runner, and listen on the configured port:
make runYou should see output similar to:
Starting Velora Headless Commerce Engine...
Configuration loaded {"port": "8080", "db_driver": "sqlite"}
Database connection established
Migrations executed successfully
Background job runner started
Server listening {"port": "8080"}
Velora is built with a heavy emphasis on test reliability, validating entire business flows rather than mocking everything at the layer boundary.
╱ Integration (tests/integration) ╲ — Full API flows using in-memory SQLite
╱ Repository (platform/sqlite) ╲ — SQL query verification on real db schema
╱ Application (application) ╲ — Use case orchestration with in-memory mocks
╱ Domain Unit (domain) ╲ — Pure business rule invariants (no IO)
To run all tests including integration flow suites:
make testVelora includes explicit tests designed to detect race conditions in inventory allocations (e.g. two users checking out the last available item simultaneously). You can run tests under the Go race detector:
go test -race -v ./...Velora splits its endpoints into public-facing storefront endpoints (/v1/store) and credentialed admin endpoints (/v1/admin).
Documentation: The complete formal API specification is available in the OpenAPI 3.0 Document.
Register a new customer account (passwords are hashed using resource-bounded Argon2id):
curl -X POST http://localhost:8080/v1/store/register \
-H "Content-Type: application/json" \
-d '{
"email": "shopper@example.com",
"password": "strongPassword123",
"name": "Mohamed Kamal"
}'Admin endpoints support authentication via JWT bearer tokens or secure machine-to-machine API keys using X-API-Key headers (tokens are verified using high-performance bcrypt).
To list products as an admin:
curl -H "X-API-Key: <your-api-key>" http://localhost:8080/v1/admin/productsVelora was designed and built by Mohamed Kamal as a showcase of Go modular monolith architecture, domain-driven design principles, and strict software craftsmanship.
- LinkedIn: Mohamed Kamal
- Design Philosophy: Boring, predictable, highly testable code that runs on minimal infrastructure.
If you are an engineer or recruiter evaluating this project, check out:
- The 10 Architecture Decision Records to read the technical justifications for database, search, and job-runner designs.
- The Testing Guide to understand the integration flow validation strategy.
- The Import Boundary Script which guarantees that domain business models are never polluted by REST routers or DB engines.