<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->

# System Knowledge Base

The catalogue. Maintained by `dj index --write` — entries are generated
from each concept's frontmatter, so descriptions never drift.

## Apps
* [Storefront](</Apps/Storefront/Storefront.md>) - The public web app where buyers browse products and place orders.
* [Checkout Page](</Apps/Storefront/Pages/Checkout Page.md>) - Guides a buyer through paying for the items in their cart and placing the order.
* [Price Tag](</Apps/Storefront/Modules/Price Tag.md>) - Renders a price with currency, discounts and strike-through original price, used on every product surface.
* [Backoffice](</Apps/Backoffice/Backoffice.md>) - The internal app where support and operations manage orders, refunds and disputes.
* [Orders Dashboard](</Apps/Backoffice/Pages/Orders Dashboard.md>) - The support agent's working list of orders — search, inspect, and start refunds.
* [API Client](</Shared/Modules/API Client.md>) - Typed HTTP client shared by all apps — auth headers, retries and error normalization in one place.

## Services & events
* [Payments Service](</Services/Payments Service.md>) - Internal service that charges buyers, records payment attempts and publishes payment outcomes.
* [Stripe](</Services/Stripe.md>) - Third-party payment provider used by the Payments Service for card charges.
* [order-placed](</Events/order-placed.md>) - Published when a charge succeeds and an order becomes real; the async contract between payments and everything downstream.
* [order-refunded](</Events/order-refunded.md>) - Published when a refund succeeds — downstream systems reconcile money and notify the buyer.

## Data
* [Main Database](</Data/main/Main Database.md>) - The primary transactional database — orders, buyers and payment attempts; owned by the Payments Service for writes.
* [orders](</Data/main/Tables/orders.md>) - One row per placed order — the durable record the whole system hangs off.
* [payment_attempts](</Data/main/Tables/payment_attempts.md>) - Every charge or refund attempt against an order, successful or not — the audit trail money leaves behind.
* [order-status](</Data/main/Enums/order-status.md>) - Canonical lifecycle states of an order; stored in the orders.status column.

## Flows & actors
* [Order Placement](</Flows/Order Placement/Order Placement.md>) - How a cart becomes an order — the trunk every path shares, and the scenarios the system must cover.
* [Declined Payment Path](</Flows/Order Placement/Declined Payment Path.md>) - The unhappy branch of Order Placement — what happens when the provider declines the charge.
* [Refund Flow](</Flows/Refund Flow/Refund Flow.md>) - How money goes back — from a support decision in the Backoffice to a confirmed provider refund and its event.
* [Buyer](</Actors/Buyer.md>) - The customer using the Storefront — browses, pays, and receives orders.
* [Support Agent](</Actors/Support Agent.md>) - Internal staff acting on buyers' behalf — inspects orders, issues refunds, resolves disputes.

## Team
Ownership is per FEATURE, so these documents are what a features table's
`Owner` column links to — and the roster the assign picker reads.

* [Robin Cross](</Team/Robin Cross.md>) - Engineer on the buying journey — Storefront, checkout and the payments path.
* [Nadia Ilic](</Team/Nadia Ilic.md>) - Engineer on the operations side — Backoffice, refunds and the support tooling.

## Engineering
* [Testing Conventions](</Engineering/Testing Conventions.md>) - Tests are evidence, not documents — how this vault records test coverage without prose that drifts.
* [0001 Evidence First Testing](</Engineering/Decisions/0001 Evidence First Testing.md>) - Record test coverage as evidence URIs on rows, never as standalone test documentation.
* [Glossary](</Conventions/Glossary.md>) - The domain vocabulary — one meaning per word, so documents and coding agents stop guessing.

## Skills
How developers and coding agents work with this knowledge base — adapted from
[Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/main/skills/engineering).

* [Domain Modeling](</Engineering/Skills/Domain Modeling.md>) - Actively sharpen the system's domain model — in this vault, the model IS the Glossary, the enums and the actors.
* [Docs-First Implementation](</Engineering/Skills/Docs-First Implementation.md>) - Spec, build and close the loop through the knowledge base — feature rows are the spec, evidence is the definition of done.
* [TDD with Scenario Evidence](</Engineering/Skills/TDD with Scenario Evidence.md>) - Red-green-refactor where the red list is the flow's Scenarios table and green means the row cites its test.
* [Diagnosing with the Knowledge Base](</Engineering/Skills/Diagnosing with the Knowledge Base.md>) - A disciplined diagnosis loop that starts from the documented system instead of from grep.
* [Two-Axis Review](</Engineering/Skills/Two-Axis Review.md>) - Review every diff on two axes — Standards (is the code good) and Spec (does it match the documented rows) — and block on the second.
* [E01 Checkout Hardening](</Backlog/E01 Checkout Hardening.md>) - Close the gaps the Order Placement flow already documents — the missing audit write on declines, and the retry affordance a hard decline should not offer.