Engineering Wiki

What this covers / who it's for. The index and onboarding path for engineers (and AI agents) working on stables-core-app: how the system is built, how it behaves at runtime, and how to change it safely. This page absorbs the old docs/DEVELOPER_GUIDE.md.

Stables is a Laravel 13 modular monolith: a multi-tenant stablecoin banking platform where tenant isolation is enforced by Postgres Row-Level Security, every domain read/write goes through a CQRS bus, and all money movement is executed by an external finance rail (Conduit) that the app mirrors asynchronously. The pages below are the system-wide views; the per-module specifics live in each module's app-modules/<module>/README.md, and the agent-facing patterns live in the skills package (entry point: the stables-app-development skill — mandatory context before feature work).

Onboarding path (read in this order)

1. Architecture & runtime flows — the whole-app map. The module fleet, the tenant request path, the bus gate order, webhook mirror ingest, the async platforms, and the audit/DLP seams. Everything else hangs off this.
2. Tenancy & RLS — the load-bearing invariant. Central vs tenant context, the stables.current_tenant session variable, and how isolation is verified.
3. The CQRS bus — the only path to domain data, and every cross-cutting seam (authorization, audit, DLP, freeze gates, feature checks, idempotency) that rides it.
4. Auth & RBAC — the two guards, the per-module permission registry, and roles-as-UX.
5. API conventions — JSON:API envelope, bigint-internal/UUIDv7-public ids, idempotency keys, OpenAPI generation.
6. Data model — schema conventions (identifiers, soft-delete, blamable) and the cross-module domain map.
7. Module catalog — every module at a glance, linking to its README.
8. Async platforms and Provider integration — the background-work toolbox and the Conduit seam (outbound rails, inbound webhooks, mirrors, reconciliation).
9. Testing & the gates, Local development, Observability & ops — how you verify, run, and operate it.
10. How a change ships — branch → gates → multi-persona review → docs+wiki sync → PR. Read before your first PR.
11. The decision log (ADRs) — the D-numbered ADR log (currently through D93), one file per decision. Check it before reversing anything that looks deliberate — it usually is; new ADRs are recorded here.

All pages

Page	One-line scope
architecture-flow.md	Whole-app runtime map: modules, request lifecycle, mirror ingest, async, audit/DLP
module-catalog.md	Per-module purpose, surface, seams, README links
tenancy-and-rls.md	Single-DB RLS tenancy deep map
cqrs-bus.md	Bus lifecycle, markers, middleware seams
auth-and-rbac.md	Guards, permission registry, roles
api-conventions.md	JSON:API, ids, idempotency, OpenAPI
data-model.md	Schema conventions + domain map
async-platforms.md	Queues/Horizon, task-runner, async-requests
provider-integration.md	Rails seam, webhooks, mirrors, reconciliation
testing-and-gates.md	Test suite, arch guards, the four gates
local-development.md	Docker stack, make targets, ports
observability-and-ops.md	Horizon, schedules, pruning, failure surfaces
decisions/README.md	The D-numbered decision log — index + one file per ADR
how-a-change-ships.md	The delivery pipeline for every change

The other documentation layers (defer to them)

• Per-module specifics → app-modules/<module>/README.md (the current map of that module's surface, data model, and gotchas — read it before touching the module).
• Agent patterns & workflows → the skills package, packages/stables/skills/; the published copies under .claude/skills/, .agents/skills/, .cursor/skills/ are regenerated by php artisan boost:update — never edit those mirrors.
• Decision rationale → the decision log (in this wiki); deferred work → docs/tracking/.
• Generated catalogs → docs/EVENTS.md (php artisan events:catalog), the OpenAPI exports (php artisan scramble:export).
• The product view → wiki/product/, including the capability → module map bridge back into this wiki.

---

← Wiki charter & master index