# CommerceDex System Docs — Overview

## What this document set is

This is the **Phase 3 deliverable** of CommerceDex: System Architecture & Database Design. It turns the Phase 1 domain model (`../architecture/`) and Phase 2 UX flows (`../ux/`) into concrete, buildable technical design:

- Database design principles and the mechanism that enforces module boundaries in practice (`01-database-design-principles.md`)
- Concrete entities/tables for all 20 modules (`02-module-schemas.md`)
- The Postgres-backed event and job system that replaces a message broker (`03-event-and-job-system.md`)
- How modules call each other synchronously in-process (`04-module-interfaces.md`)
- Internal sub-structure for the Automation Engine, the module flagged as highest scope-creep risk (`05-automation-engine-substructure.md`)
- The staff permission model, designed around merchant-legible roles rather than module boundaries (`06-permissions-model.md`)
- Open questions for Phase 4/5+ (`07-open-questions.md`)

## What this document set resolves from earlier phases

| Source | Question | Resolved in |
|---|---|---|
| `../architecture/06-open-questions.md` #2 | Boundary enforcement mechanism | `01-database-design-principles.md` |
| `../architecture/06-open-questions.md` #6 | Automation Engine internal sub-organization | `05-automation-engine-substructure.md` |
| `../ux/04-open-questions.md` #1 | Inventory complexity ceiling | `02-module-schemas.md` (Inventory section) |
| `../ux/04-open-questions.md` #3 | Suggestion density / ranking logic | `05-automation-engine-substructure.md` |
| `../ux/04-open-questions.md` #5 | Staff permission granularity | `06-permissions-model.md` |

## What this document set is NOT

- **Not a full DDL script.** Tables and key columns are specified at a level sufficient to build from; exhaustive column lists, indexes, and constraints are implementation detail decided during actual development, not architecture.
- **Not an API specification.** REST/GraphQL/RPC shape, request/response formats, and versioning belong to implementation, informed by but not dictated by this document.
- **Not a visual design system.** That's Phase 4.

## How to read these docs

Read `01-database-design-principles.md` first — it establishes the schema-per-module convention and enforcement approach that every other document assumes. `02-module-schemas.md` is the long reference document; read the modules relevant to what you're building, not necessarily cover to cover. `03` and `04` are the mechanical rulebook for cross-module communication, extending `../architecture/05-module-interaction-model.md` from principle to implementation. `05` and `06` are focused resolutions of specific carried-forward questions.

## Relationship to other phases

| Phase | Depends on Phase 3 for |
|---|---|
| Phase 4 — Design System & UI Framework | `06-permissions-model.md`'s role definitions inform Settings' staff management screens; the module schemas inform what data is actually available to display. |
| Phase 5+ (Commerce Core, Catalog & Inventory, Orders/Customers/Payments, Automation Engine, etc.) | These are the direct implementation targets of `02-module-schemas.md`, `03-event-and-job-system.md`, and `04-module-interfaces.md`. |