[AdilAzhariOmsan]

Phase 1 of the Nexo 2.0 brief: the product specification and architectural foundation. Documentation only. No application code, migrations, dependencies or config changed.

Summary

 docs/
 ├── README.md                      # start-here links
+├── discovery/
+│   ├── PHASE-0-TECHNICAL-ASSESSMENT.md   # legacy app audit (moved in from old repo)
+│   └── PHASE-1-REVIEW.md                 # what this phase did + open decisions
 ├── product/
+│   ├── product-requirements.md    # PRD
+│   ├── functional-requirements.md # FR-* with acceptance criteria
+│   ├── non-functional-requirements.md
+│   ├── user-journeys.md           # customer / vendor / staff
 │   └── vision, scope, goals, …    # + "Superseded" banner (content untouched)
 └── architecture/
     ├── INVARIANTS.md              # rewritten as INV-1…21
+    ├── system-overview.md
+    ├── domain-context-map.md      # 13 modules + shared kernel
+    ├── dependency-rules.md        # module matrix, no cycles
+    ├── database-design.md
+    ├── security-model.md          # roles + permission matrices
+    ├── financial-model.md         # double-entry ledger, worked examples
+    ├── integration-contracts.md
+    ├── lifecycles/                # checkout+payment, inventory, orders/returns
+    └── adr/0006 … 0021            # 16 new ADRs

The key decisions recorded as ADRs:

ADR	Decision
0008	This repo is the foundation; Vue 3 + Inertia + TS frontend (Accepted)
0010	Modular monolith; cross-module imports via Contracts only, enforced by Pest arch tests
0011	Fail-closed vendor context (fixes the legacy cross-vendor data leak)
0009	MySQL for every DB test (SQLite hid real concurrency bugs)
0014 / 0015	Conditional-update inventory reservations; checkout saga with webhook as payment truth
0016 / 0017	Internal double-entry ledger + simulated payouts; transactional outbox/inbox
0018	TypeScript types generated from PHP data objects

Commits are grouped by area: discovery → product → ADRs → architecture → review status.

Evidence

• Link check: a script resolved all 121 relative Markdown links under docs/. 1 is broken (marketplace-migration.md → ../REDESIGN_BRIEF.md). It was already broken before this PR and sits in a superseded doc, so it was left as is.
• Ledger worked examples were hand-checked to balance (113.00 / 20.00 / 45.00 / 11.11). They become executable tests in Phase 5.
• The module dependency matrix was hand-checked for cycles. Two were found and removed (Ordering↔Finance, Ordering↔Payments).
• CI (ci.yml) runs the existing test suite. Nothing it covers changed.

Merge Danger

Door: two-way

Markdown only. Reverting the merge restores the previous docs.

Blast Radius: none

No runtime impact. ADR-0009…0021 are Proposed, not Accepted. Merging records the specification but does not accept those ADRs. Open owner decisions are listed in docs/discovery/PHASE-1-REVIEW.md §6.