A modular, high-performance headless e-commerce backend written in Rust, API-compatible with MedusaJS v2.

Implements the core Browse → Cart → Checkout flow with 49 endpoint methods across 7 domain modules, backed by PostgreSQL (primary) or SQLite (optional).

See docs/p1_additions.md for a full compliance comparison against Medusa v2 — which endpoints match, which are toko-rs additions, and what is deferred to future phases.

# Start PostgreSQL
docker compose up -d

# Copy config
cp .env.example .env

# Seed sample data (3 products + 1 customer)
cargo run -- --seed

# Start server
cargo run

# Verify
curl http://localhost:3000/health

# Browse products
curl http://localhost:3000/store/products | jq '.products[].title'

Single-binary modular monolith. Each domain module (product/, cart/, customer/, order/, payment/, invoice/) follows the same internal structure:

src/
  main.rs              Entry point, config, graceful shutdown
  lib.rs               AppState, router composition, health check
  config.rs            Environment-based configuration (envy + dotenvy)
  db.rs                Database pool, migrations, constraint helpers
  error.rs             AppError enum → Medusa-compatible JSON errors
  extract.rs           Custom JSON extractor with clean error mapping
  types.rs             Shared: ULID generation, slugify, pagination
  seed.rs              Idempotent seed data

  product/
    routes.rs          Axum handlers (admin + store)
    types.rs           Request/response DTOs
    models.rs          Database row structs (FromRow)
    repository.rs      SQL queries, business logic
  cart/                (same structure)
  customer/            (same structure)
  order/               (same structure)
  payment/             (internal only — no routes in P1)
  invoice/             (admin only — config + on-the-fly generation)

Layers: Routes → Types → Repository → Database. No service layer in P1 — handlers call repositories directly.

• ULID-prefixed IDs: prod_01KQ..., cart_01KQ..., order_01KQ..., cus_01KQ...
• Soft deletes: deleted_at column with partial unique indexes (WHERE deleted_at IS NULL)
• Cart completion: Atomic SQL transaction with SELECT ... FOR UPDATE (PostgreSQL) — creates order + payment record + idempotency key in one commit
• Line item merging: Same variant + same price + same metadata merges quantity; different metadata creates separate line items
• Snapshot pattern: Cart line items store a JSON snapshot of variant data at add-time
• POST for updates: Follows Medusa convention — both create and update use POST
• Error format: Medusa OAS-compatible 3-field JSON: {"code", "type", "message"}

8 migrations, 15 tables:

Invoice config is stored as environment variables (not a DB table): INVOICE_COMPANY_NAME, INVOICE_COMPANY_ADDRESS, INVOICE_COMPANY_PHONE, INVOICE_COMPANY_EMAIL, INVOICE_COMPANY_LOGO, INVOICE_NOTES.

PostgreSQL is the default. SQLite is available behind a feature flag:

cargo run --features sqlite --no-default-features

make docker-up                        # Start PostgreSQL

# Integration tests (297 tests, requires PostgreSQL)
DATABASE_URL=postgres://postgres:postgres@localhost:5432/toko_test \
  cargo test -- --test-threads=1

# SQLite tests
DATABASE_URL="sqlite::memory:" \
  cargo test --features sqlite --no-default-features -- --test-threads=1

# E2E tests (spawns live HTTP server)
E2E_DATABASE_URL=postgres://postgres:postgres@localhost:5432/toko_e2e \
  cargo test --test e2e -- --test-threads=1

# Coverage (requires cargo-llvm-cov)
make cov

Tests run single-threaded (--test-threads=1) for database isolation. Each test cleans its own tables via clean_all_tables().

tests/
  common/mod.rs           Shared test helpers (setup_test_app, clean_all_tables)
  product_test.rs         Product admin + store integration tests
  cart_test.rs            Cart lifecycle tests
  order_test.rs           Order + payment tests
  order_export_test.rs    Order CSV export tests
  customer_test.rs        Customer registration + profile tests
  invoice_test.rs         Invoice config + generation tests
  event_test.rs           Event outbox integration tests
  webhook_test.rs         Webhook subscription CRUD + HMAC delivery tests
  contract_test.rs        Response shape validation against Medusa OAS
  e2e/                    End-to-end tests against live HTTP server

Configured via environment variables or .env file:

make dev          # cargo run
make test         # cargo test
make lint         # cargo clippy -- -D warnings
make fmt          # cargo fmt
make seed         # cargo run -- --seed
make docker-up    # docker compose up -d
make docker-down  # docker compose down
make test-pg      # Test against PostgreSQL
make test-sqlite  # Test against SQLite
make test-all     # Both databases
make cov          # cargo llvm-cov

P1 (Core MVP) — Complete. 290 tests, clippy-clean, 46 endpoint methods, 15 tables, 8 migrations.

The following are out of scope for P1 and planned for future phases:

• Admin authentication / RBAC
• Regions, multi-currency, tax calculation
• Shipping providers and fulfillment
• Payment provider integrations
• Inventory management
• Promotions / discounts
• Product collections
• File/image upload service
• Order edits and returns

MIT