Vectis Commerce Platform¶
Vectis is a B2B-first headless commerce platform built with Python (FastAPI), SvelteKit, PostgreSQL, Redpanda, and Temporal. It replaces a legacy WooCommerce stack with a purpose-built system for wholesale and hybrid B2B/B2C commerce.
Key Capabilities¶
- B2B + B2C in one platform — channel-based commerce modes (wholesale, retail, hybrid)
- Four-phase B2B approval workflow — cart submitted → cart approved → payment composed → payment approved → place order, with durable Temporal execution and a workflow-fault inbox
- Five-level pricing — managed prices, location, account, group, and default tiers with multi-currency support
- Packaging + MMOQ — global package ladders (
each,case-of-24), per-customer min/max enforced at the cart aggregate, channel-timezone-aware 30-day windows - Inventory state machine — reservation lifecycle (
HELD → CONFIRMED → RELEASED / EXPIRED),pushExternalStockfor ERP feeds, external fulfillment handoff with internal-hold release - Configurable order state machine — transitions, guards, and side-effects defined per deployment
- Extension system — strategy-mediated business logic with self-registration (Cmd-K, nav, GraphQL, models, schedules, search) and channel-scoped activation; CI enforces zero-extension-imports
- Refund approval workflow — async, durable, per-tender progress tracking with idempotent retry
- Event-driven architecture — in-process EventBus + Redpanda for inter-service communication, JSON-Schema-validated payloads, dedicated workflow-fault topic
- Durable workflows — Temporal for order lifecycle, recurring orders, approvals, refunds, and all background tasks
- Observability baseline —
/metrics(Prometheus) +/ready(parallel dependency probe) with a seeded Grafana dashboard
Quick Links¶
| I want to... | Go to... |
|---|---|
| Set up a local dev environment | Quick Start |
| Understand the architecture | Architecture |
| Add a backend module | Modules Guide |
| Build an extension | Extensions Guide |
| Work with the GraphQL API | API Overview |
| Understand the order flow | Orders |
| Set up pricing and currencies | Pricing |
| Run a referral/affiliate program | Affiliates |
| Configure a points program | Loyalty |
| Pull revenue & campaign reports | Analytics |
| Deploy to production | Deployment |
Tech Stack¶
| Layer | Technology |
|---|---|
| Backend API | Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Strawberry GraphQL |
| Storefront | SvelteKit 2, Tailwind CSS, Lucide icons |
| Admin Panel | SvelteKit 2, Tailwind CSS, Lucide icons |
| Database | PostgreSQL 16 |
| Cache / Sessions | Redis 7 |
| Event Streaming | Redpanda (Kafka-compatible) |
| Workflows | Temporal |
| Search | Meilisearch |
| Object Storage | S3-compatible (MinIO in dev) |
Project Status¶
The platform is in active development. All 14 strategy interfaces are implemented, ~40 core modules are built, ~45 extensions ship with the platform, and the end-to-end checkout pipeline (tax, shipping, payment, promotions, approvals) is wired with the four-phase B2B workflow. The admin/storefront are fully migrated to Houdini for GraphQL, and make check (~25s, ~1,670 tests + ruff + mypy + AST guards + schema drift) is the single source of truth for "is this branch safe to push?".
GitHub Actions CI is currently disabled (2026-05-18) in favour of the local gate. See the Changelog for the per-phase status, including the latest Phase 15 — B2B Workflow, Inventory Lifecycle, Refund Approvals wave.