Villa Knowledge Base
Engineering knowledge for Villa Market systems, shared between people and AI agents. If you are an agent, read AGENTS.md in the repo root before writing, and agent-integration for how to search this vault and publish back.
Start here
Something is broken on dev checkout? Read dev-environment first — most “the fix isn’t there” reports turn out to be the service worker serving a stale bundle.
A coupon isn’t discounting? coupon-types explains what each type is supposed to do, and discount-fields maps how a discount travels from VillaCoupon3 through calculatecost2 into the website.
Systems
| System | What it does |
|---|---|
| calculatecost2 | Prices a basket: shipping, discounts, grand total |
| villacoupon3 | Validates coupons and computes discount amounts |
| villa-ecommerce-web | The Vue storefront (cart and checkout) |
| dev-environment | How dev.villamarket.net is wired, and its traps |
Incidents
| Date | What broke |
|---|---|
| 2026-07-25-coupon-90000008-not-applying | Free-shipping coupon did nothing on nationwide orders |
| 2026-07-29-shipping-forced-nationwide | Every address resolved to Nationwide, blocking coupon testing |
| 2026-07-29-coupon-test-sheet-failures | Two-for-X ignored, capped free shipping over-waived |
Runbooks
- deploy-calculatecost2 — ship a backend change to dev
- patch-dev-web-bundle — hot-patch the deployed dev frontend
- invalidate-dev-cloudfront — force clients onto new assets
- run-coupon-test-matrix — re-run every coupon case against dev
- agent-integration — wire an AI agent into this vault
- deploy-knowledge-base — publish this vault
Reference
- aws-accounts — which account owns what
- api-endpoints — CloudFront routes and the APIs behind them
- coupon-types — every coupon type and its expected behaviour
- discount-fields — field-by-field discount contract
- coupon-test-matrix — the standing test cases and their status
Recurring lessons
Three separate bug reports in July 2026 came down to the same class of problem: two components disagreeing about a contract nobody wrote down.
A capped free-shipping coupon was described two ways at once — by a discountType and by a freeShipping boolean — and the two consumers read different ones. A delivery-fee API changed its response shape while its caller still branched on the old one. A discount total was assembled twice, in two places, and one copy forgot a field.
The habit that catches all three: when a value crosses a service boundary, write down which field is authoritative, and make the consumer trust that field instead of re-deriving the answer. discount-fields is that written-down contract for discounts.