# TANRAIL ONE — Phase Current State Reconciliation ## 1. Executive Summary This document provides a definitive reconciliation between the master roadmap (`docs/12-development-roadmap.md`), the architecture specifications (`docs/03-core-capability-map.md`, `docs/06-data-architecture.md`, `docs/08-workflow-and-transaction-specification.md`), and the actual implemented codebase in `app/Domains/Core/`. It resolves the phase-numbering ambiguity that occurred when execution prompts designated Core modules as Phase 3 sub-phases (3.1, 3.2.x, 3.3.x, 3.4), whereas the Phase 0 roadmap originally designated Sales and Invoicing as Phase 4. --- ## 2. Phase Reconciliation Matrix | Planned Phase (Roadmap) | Implementation Sub-Phase | Actual Status | Evidence in Codebase | Missing / Incomplete Scope | |---|---|---|---|---| | **Phase 1 — Platform Foundation** | Phase 1 | **COMPLETE** | Laravel 11 setup, PostgreSQL/SQLite, base directory layout. | None. | | **Phase 2 — Auth, RBAC & Organization** | Phase 2 | **COMPLETE** | `User`, `Role`, `Permission`, `Organization`, `BusinessUnit`, `Branch`, `ContextManager`, `EnsureActiveContext`. | Frontend context switcher UI (Framework pending ADR-004). | | **Phase 3 — Master Data & Inventory** | Phase 3.1 & 3.2.2 | **COMPLETE (Foundational)** | `Item`, `Unit`, `Customer`, `Supplier`, `TaxCategory`, `InventoryLocation`, `StockBalance`, `StockMovement`, `StockTransfer`, `InventoryService`. | Inventory financial valuation (FIFO/Weighted Avg), Stocktake/Cycle count workflows, Batch/Lot tracking. | | **Phase 4 — Sales, Invoicing & Payments** | Phase 3.2.3 & 3.2.4 (Partial) | **PARTIALLY COMPLETE** | `Order`, `OrderLine`, `Payment`, `OrderService`, `PurchaseOrder`, `PurchaseOrderLine`, `PurchaseReceipt`, `SupplierPayment`, `PurchaseService`. | **Formal `Invoice` entity**, **Vendor Bills (`SupplierInvoice`)**, **Credit Notes**, **Accounts Receivable sub-ledger**, **Accounts Payable sub-ledger**, **Expense vouchers**. | | **Financial Core (Ledger Engine)** | Phase 3.3 & 3.3.1 | **COMPLETE (General Ledger)** | `Account`, `FiscalPeriod`, `Journal`, `JournalEntry`, `FinancialSettings`, `JournalType`, `FinancialService`, `AccountResolver`. | AR/AP sub-ledger automation, Revenue recognition on order confirmation, COGS posting on fulfillment, Financial statements generator, Bank reconciliation (deferred). | | **Cross-Module Integration** | Phase 3.4 | **COMPLETE** | `ProcessedEvent` table, synchronous atomic listeners, pessimistic locking concurrency verification, end-to-end integration tests (142 tests). | Event hooks for invoice generation, COGS recognition, and 3-way matching. | | **Phase 5 — Reusable Capabilities** | Not Started | **NOT STARTED** | None. | Production / BOM, Event Booking, Fleet & Delivery. | | **Phase 6 — Restaurant Extension** | Not Started | **NOT STARTED** | None. | Table management, KDS, POS UI. | | **Phase 7 — Catering Extension** | Not Started | **NOT STARTED** | None. | Catering packages, event costing. | --- ## 3. Analysis of Phase-Numbering Inconsistency ### 3.1 Why the Previous Recommendation Jumped to Phase 5.1 1. **The Roadmap Plan (Phase 0)**: In `docs/12-development-roadmap.md`, Phase 3 covered Master Data & Inventory, Phase 4 covered Sales, Invoicing & Payments, and Phase 5 covered Reusable Capabilities (BOM/Production). 2. **The Execution Reality (Phases 3.1 – 3.4)**: - When implementation was prompted, the prompt sequence organized the entire Core platform development under the umbrella of **"Phase 3"**: - Phase 3.1: Core Data Foundation - Phase 3.2.2: Inventory Foundation - Phase 3.2.3: Core Sales Engine - Phase 3.2.4: Core Procurement Engine - Phase 3.3 / 3.3.1: Financial Core Engine & Hardening - Phase 3.4: Core Integration & Verification - Because Sales, Procurement, and Financial Journals were built under these "Phase 3.x" labels, the subsequent analysis made the erroneous assumption that roadmap Phase 4 ("Sales, Invoicing & Payments") was already finished under Phase 3.2.3 and 3.3. - Consequently, the assistant looked ahead to Phase 5 in `docs/12-development-roadmap.md` and recommended Phase 5.1 (Production/BOM). ### 3.2 Why That Assumption Was Flawed While Phase 3.2.3 built `Order` and `Payment`, and Phase 3.3 built `Journal` and `JournalEntry`: - **Phase 4 (Invoicing, Bills, AR/AP Sub-Ledgers, Credit Notes) was never actually built.** - In the current code, `Payment` links directly to `Order`. There is NO `Invoice` model! - In accounting reality, receiving a customer payment credits Accounts Receivable (`AR`), but AR was never debited because there is no invoicing or sales recognition event! - In procurement reality, paying a supplier debits Accounts Payable (`AP`), but AP was never credited because there is no vendor bill or purchase receipt posting! - Jumping to Phase 5 (Production) before the Core Financial loop (Invoicing, Bills, AR/AP lifecycles) is reconciled creates an architectural void in the transaction engine. --- ## 4. What Has Actually Been Completed 1. **Core Identity & Scoping**: `OrganizationScope`, `BusinessUnitScope`, RBAC policies, context switching. 2. **Core Master Data**: `Item` (with track inventory and base price), `Unit`, `TaxCategory`, `Customer`, `Supplier`, `Branch`, `BusinessUnit`, `Organization`. 3. **Core Inventory Engine**: Physical stock tracking by `InventoryLocation`, atomic stock balances, immutable `StockMovement` ledger, inter-branch `StockTransfer`, pessimistic locking against negative stock. 4. **Core Sales Engine**: `Order`, `OrderLine`, `Payment`, state machine (`DRAFT` → `CONFIRMED` → `CANCELLED`), inventory reservation/issue on confirmation. 5. **Core Procurement Engine**: `PurchaseOrder`, `PurchaseOrderLine`, `PurchaseReceipt`, `PurchaseReceiptLine`, `SupplierPayment`, partial receiving, approval lifecycle. 6. **Core General Ledger Engine**: `Account` with tree hierarchy and loop detection, `FiscalPeriod` with closed-period protection, `Journal` with `JournalType` and immutability, `JournalEntry` with debit=credit validation, `FinancialSettings` with deterministic BU-to-Org fallback, `AccountResolver`. 7. **Core Event Idempotency**: `ProcessedEvent` wrapper guaranteeing exactly-once execution of cross-domain listeners. --- ## 5. What Is Incomplete Inside Phase 3 / Core Foundation The Core currently has specific missing generic transactional primitives: 1. **Formal Invoicing Architecture**: - `Invoice` entity (`id`, `business_unit_id`, `branch_id`, `order_id`, `invoice_number`, `issue_date`, `due_date`, `status: DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED`). - Connecting `Payment` to `Invoice` rather than bare `Order`. - `CreditNote` entity for auditable reversals of issued invoices. 2. **Accounts Receivable (AR) Recognition**: - When an Order is fulfilled or Invoice is issued: - `DEBIT Accounts Receivable` - `CREDIT Sales Revenue` - `CREDIT Tax Liability` - Currently, `RecordSalesPaymentListener` credits AR when money is received, without AR ever having been established. 3. **Accounts Payable (AP) Recognition**: - When Goods are Received or Vendor Bill is recorded: - `DEBIT Inventory / Expense` - `CREDIT Accounts Payable` - Currently, `RecordSupplierPaymentListener` debits AP when money is disbursed, without AP ever having been established. 4. **Vendor Bills (`SupplierInvoice`)**: - Formal bill entry for supplier claims, matching Purchase Orders and Receipts. 5. **Inventory Financial Valuation & COGS Recognition**: - Currently, inventory issues only update quantity. No COGS journal is posted: - `DEBIT Cost of Goods Sold` - `CREDIT Inventory Asset` --- ## 6. Verdict on Current Platform State The platform is currently at the completion of **Phase 3 Core Foundation & Hardening** (specifically sub-phases 3.1 through 3.4). Phase 4 (Invoicing, Vendor Bills, AR/AP Recognition & Lifecycle) has NOT been built. Phase 5 (Reusable Capabilities) has NOT been started. The jump to Phase 5.1 was premature and must be halted until Phase 4 (Core Invoicing & AR/AP Lifecycle) is either explicitly authorized or architectural decisions are ratified.