Home

VINDOR engineering handbook

For current priorities and acceptance, read the canonical portfolio plan. VIN-155 retains the completed demo evidence; VIN-288 is the delivered catalog release. VIN-293, return after sign-in, is delivered. VIN-295 is the deferred catalog-administration roadmap. The board separates Customer features and Technical improvements, using shared issue cards. The corresponding plan update merged in PR #301.

VINDOR is a fictional desk-accessories shop built as a senior software engineering portfolio. It demonstrates clear service responsibilities, precise money handling, an explicit API contract, reproducible setup, and automated verification.

Implemented shopping journey: catalog, accounts, cart, owned GBP order drafts and atomic order placement are implemented. PR #181 delivered placement; PR #187 delivered browser-fixture/recovery-test corrections. Placement claims inventory but does not collect payment. PR #188 delivered VIN-120 checkout, confirmation and history; VIN-30 implements hosted sandbox payments, expiry and exactly-once inventory release in PR #194, merged as 0e89efd. Hosted development acceptance passed on 8685cc1: paid checkout/history, cancellation, expiry and duplicate expiry delivery with no second stock release. Development Sentry monitoring and joined-trace verification are complete; production activation remains outside that rollout. New signals require privacy tests and hosted verification. Existing Vercel/Neon deployments do not establish hosted acceptance of every merged feature. See the canonical plan for acceptance gates.

Cart persistence, disconnected-action recovery and account isolation are now verified on hosted development for PR #252. The cart handbook explains the recovery contract and retained limits.

Demo guide: The hosted shopping walkthrough and five-minute script now include the final 4 October rehearsal: a new fictional development purchase reached server-confirmed paid status and persisted in history. A clean isolated local bootstrap/account flow also passed. VIN-262 retains the evidence and limits; the canonical plan owns completion status.

Open the delivery Kanban board to see current tickets, dependencies and PR progress.

Parent epics now have [EPIC] titles, with distinct category labels for epics, stories, bugs and tasks. Reading the issue cards explains the hierarchy without changing delivery status or priority.

Open the production storefront · Production Swagger docs

Try the development storefront · Explore the development API

Read the handbook

1. Architecture and tools — components, responsibilities, and how a request flows.
2. Developer onboarding — run the stack, browse Swagger, and use Postman.
3. Testing and delivery — CI stages, evidence, and PR workflow.
4. Engineering decisions and interviews — tradeoffs and a five-minute walkthrough.
5. Delivery roadmap — completed milestones and remaining work.

Design system — VINDOR tokens, shadcn components, accessibility and form conventions.

System at a glance

flowchart LR
    U[Browser] --> N[Next.js storefront]
    N --> F[FastAPI backend]
    S[Swagger or Postman] --> F
    F --> P[(PostgreSQL)]

Loading

The browser renders the storefront; Next.js fetches catalog data from FastAPI. FastAPI validates requests and owns permissions, product prices and stock. PostgreSQL persists users, products, carts and orders.

The repository's versioned documentation is the source of truth for commands and implementation details. This Wiki is the explanatory handbook; update its status alongside significant feature changes.

The storefront was renamed from FORME to VINDOR in PR #59. New VINDOR domains are available; the original FORME URLs remain available for compatibility. Photography sources and licences document the locally served WebP assets.

The storefront footer now explicitly states sandbox-only payments, no real charges and no shipping (PR #197, merged). Use development for the verified sandbox payment journey; production payments remain disabled. See the demo limitations.