# 05 — TechTitans Development Roadmap

**Principle:** extend the NH/Cacart core. Do not rebuild what works. Every new module reuses:
- tenancy and location scoping;
- RBAC (`PermissionCatalog`);
- the idempotent, locked write pattern;
- the append-only audit log;
- minor-unit money;
- the existing frontend design system.

---

## Phase 0 — Environment isolation and rebrand (prerequisite)

All steps need owner approval. See `01` §8.

1. Re-point git remotes to new TechTitans repositories.
2. Set a new `APP_NAME` and explicit `REDIS_PREFIX`/`CACHE_PREFIX`/session cookie (or separate Redis DB indexes), and generate a new `APP_KEY`.
3. Change `phpunit.xml` to `techpos_test`, create that database, and run the full backend suite to get a baseline.
4. Decide the database strategy. **Recommended:** a fresh `techpos` built by `migrate`, then `cacart:provision-tenant` for TechTitans, instead of the NH dump. That removes NH customer PII, tokens and orders. Keep the dump only as a reference.
5. Give TechTitans its own ports/vhost, storage disk and mail sender.
6. Rebrand:
   - frontend: title, logos (`public/brand`), `src/components/brand/*`, login and dashboard copy, `VITE_APP_NAME`;
   - backend: `APP_NAME`, mail templates, `DevBootstrap` seed;
   - keep `cacart.*` storage keys and `cacart:*` commands for now, with an optional rename later.
7. Retail terminology layer:
   - hide restaurant features (KDS, stations, modifiers, combos, menu state, dayparts, dine-in/takeout);
   - rename "Menu" to "Catalogue" in the UI;
   - add retail role templates (Owner, Store Manager, Sales Associate, Technician, Inventory Clerk, Accountant).

## Phase 1 — Retail inventory foundation (first development priority)

See `03` and `06` for detail.

- Fix the four confirmed defects.
- Extend the item and stock model: tracking mode, cost, reserved quantity, wider units, barcode on variants, scan lookup.
- Serialized units (IMEI/serial, condition, grade, acquisition cost, status) with per-unit history.
- Suppliers, purchase orders and goods receiving (with serial capture), then transfers.
- Reservations.
- Cost snapshot on sale (COGS) plus valuation and margin reports.
- Inventory UI moved to `/inventory`, with a unit picker and scanner.

## Phase 2 — Retail POS completion

- Walk-in sale order type; retail checkout (tender screen, split tender, change due).
- Expose the discount and price-override endpoints (services exist) behind manager approval (the `manager.approval` middleware already exists).
- Refunds and returns (provider `refund()` exists on every adapter) with restock and re-grade.
- Cash drawer and register sessions, shift close and Z-report.
- Receipt and label printing (extend `app/Printers`).
- Trade-in / buy-from-customer intake creating used units with acquisition cost.
- Sales, tax, payment and end-of-day reports; audit-log viewer.
- Card-present terminal integration (Moneris/Bambora/Stripe Terminal). Production-validate the gateway adapters.

## Phase 3 — Unified customer CRM extensions

- Build on `app/Customers` (already strong).
- Add a **customer timeline** aggregating sales, repairs, devices, subscriptions, plans, invoices and payments.
- Add `customer_devices` (owned devices, linked to sold units).
- Add store credit / account balance and outstanding-balance tracking (ledger pattern like `payment_events`).

## Phase 4 — Repair management

- Repair tickets: intake, device (customer_device or unit), diagnosis, quote/approval, parts reservation and consumption via the inventory movement service, labour, technician assignment (reuse Workforce employees), status workflow, customer notifications (reuse the mail/notification pattern), and warranty.
- Invoiced through the existing order, invoice and payment pipeline (a `repair` order type).

## Phase 5 — Services: IPTV accounts and phone plans

- Service products (`product_type=service`, no stock).
- Subscription records per customer (provider, account id, plan, start/renewal dates, status).
- Renewal reminders (scheduled job).
- Recurring or renewal orders and outstanding balances.
- Phone plan activations linked to a sold device unit (IMEI) and carrier.

## Phase 6 — Payments and outstanding balances

- Customer account statements, partial payments across documents, payment plans/layaway (reuse reservations), and reconciliation scheduling (`payments:reconcile`).

## Phase 7 — WordPress online selling

- Obtain or build the connector; consider WooCommerce compatibility.
- Delta and push sync (outbox and signed webhooks), reservations at checkout, condition-aware listings, image sync.

## Cross-cutting backlog

| Item | Status |
|---|---|
| Schedule `payments:reconcile` | Not scheduled |
| Stock-alert reconcile sweep (after a baseline run) | Not scheduled by design |
| Realtime updates via Reverb (POS, KDS replacement for repair board) | Not started |
| Offline POS (Dexie) | Not started |
| Real AI provider (optional) | Not started |
| Re-run Pint and the e2e suite on TechTitans data | Pending |
| Production-validate gateway adapters | Pending |

## Architecture guardrails for future modules

- **One customer** (`customers.id`) is the hub. Every new record carries `customer_id` with composite `(tenant_id, customer_id)` foreign keys:
  - repairs, customer devices, subscriptions and plans;
  - balances and invoices.
- **One money pipeline.** Every chargeable event becomes an order, then an invoice, then payments, so financial history stays unified (this already works for sales).
- **One stock engine.** Any module that touches stock (repairs, transfers, receiving, returns) posts through `InventoryMovementService`, never by writing tables directly.
- **Per-unit identity:**
  - `inventory_units` covers devices TechTitans owns;
  - `customer_devices` covers devices the customer owns;
  - a sale links the two.