Skip to content

Architecture

System Overview

Vectis Commerce is a headless commerce platform where the GraphQL API is the platform and the admin/storefront are independent SvelteKit clients.

graph TB
    subgraph clients [Client Applications]
        SF[Storefront - SvelteKit]
        AD[Admin Panel - SvelteKit]
    end

    subgraph bff [BFF Layer]
        SFP["Storefront BFF (SSR + /api/graphql proxy)"]
        ADP["Admin BFF (SSR + /api/graphql proxy)"]
    end

    subgraph backend [Backend Services]
        API["FastAPI + Strawberry GraphQL"]
        TW[Temporal Worker]
        EC[Event Consumer]
    end

    subgraph infra [Infrastructure]
        PG[(PostgreSQL)]
        RD[(Redis)]
        RP[Redpanda]
        TE[Temporal]
        MS[Meilisearch]
        S3[MinIO / S3]
    end

    SF --> SFP
    AD --> ADP
    SFP -->|GraphQL| API
    ADP -->|GraphQL| API
    API --> PG
    API --> RD
    API -->|publish| RP
    API --> MS
    API --> S3
    TW --> PG
    TW --> TE
    EC -->|consume| RP
    EC --> PG

Design Principles

  1. B2B is not an afterthought. Company accounts, multi-tier pricing, approval workflows, large orders, sales reps, and compliance are core — not plugins.

  2. No core modification required. Every business-logic decision point is a strategy interface. Swap implementations; never fork the engine.

  3. Large orders are first-class. Designed for carts with 1,000+ line items. No N+1 queries. Batch loading and virtual rendering throughout.

  4. Admin and storefront are clients, not the platform. The commerce engine is the GraphQL API. Anyone can replace either frontend.

  5. Modules are isolated but composable. Each domain (products, orders, pricing) is a self-contained module communicating through service interfaces.

  6. MIT licensed, no paid gates. Every feature is open source.

Constitution (Immutable Laws)

These 8 articles cannot be violated by any implementation decision:

Article Rule
1 Strategy-Mediated Business Logic — the engine never contains concrete business logic; it flows through abstract strategy interfaces
2 Module Isolation — modules communicate through service interfaces, not cross-module SQL
3 Events as Integration Boundary — inter-service communication uses Redpanda; Redis is cache only
4 Configurable Order State Machine — order states are strategy-defined, not enum-hardcoded
5 Large Orders First-Class — every path handles 1,000+ line items
6 Admin/Storefront Are Clients — GraphQL API is the platform
7 MIT License — no paid gates or commercial tiers
8 Extension Discovery — Python entry points in pyproject.toml

Full constitution with WHY/WHY NOT rationale: see vectis/docs/constitution.md.

Auth Flow (BFF Pattern)

The browser never sees a JWT. Authentication flows through the SvelteKit Backend-for-Frontend:

sequenceDiagram
    participant Browser
    participant SvelteKit as SvelteKit BFF
    participant Redis
    participant API as FastAPI API

    Browser->>SvelteKit: POST /login (email + password)
    SvelteKit->>API: GraphQL login mutation
    API-->>SvelteKit: JWT access token
    SvelteKit->>Redis: Store session (JWT + user data)
    SvelteKit-->>Browser: Set httpOnly session cookie

    Browser->>SvelteKit: GET /orders (with cookie)
    SvelteKit->>Redis: Validate session
    Redis-->>SvelteKit: JWT + user data
    SvelteKit->>API: GraphQL query (Authorization: Bearer JWT)
    API-->>SvelteKit: Order data
    SvelteKit-->>Browser: Rendered HTML

Event Architecture

Two event systems serve different purposes:

System Scope Delivery Use Case
EventBus (in-process) Within a single request Synchronous Audit logging, cache invalidation (<100ms handlers)
Redpanda (inter-service) Across services and processes Async, durable Order events, inventory updates, ERP sync

Topics: vectis.orders, vectis.inventory, vectis.accounts

Ecosystem Context

Vectis Commerce is one service in a broader platform ecosystem. Future services (Inventory Server, Pricing Server, PIM, Vendor Portal) communicate via Redpanda event streams:

graph LR
    INV["Inventory Server (future)"] -->|Redpanda| VB[Vectis Commerce]
    PRC["Pricing Server (future)"] -->|Redpanda| VB
    PIM["PIM (future)"] -->|Redpanda| VB
    VB --> SF[Storefront]
    VB --> AD[Admin]
    VB -->|"ext-odoo"| ERP[Odoo ERP]