# CYDM — Roadmap

> Sequencing and estimates. See [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) for strategy and [PROGRESS.md](PROGRESS.md) for what is actually done.

Estimates assume one focused developer working with AI assistance. They are planning aids, not commitments.

---

## Phase 0 — Environment & scaffolding · ~1 day

| Slice | Deliverable | Est. |
|---|---|---|
| 0.1 | Documentation plan + `docs/` tree | 2h |
| 0.2 | Git repository, baseline commit | 15m |
| 0.3 | MySQL `cydm` database + grants | 15m |
| 0.4 | Nginx site `cydm.test` + `*.cydm.test` | 30m |
| 0.5 | Windows hosts entries | 15m |
| 0.6 | Laravel 13 + React starter kit | 1h |
| 0.7 | `.env` wired to Laradock services | 30m |
| 0.8 | Laravel Boost + AI SDK | 45m |
| 0.9 | Core packages (tenancy, permission, sanctum, horizon, pest) | 1h |
| 0.10 | Vite HMR through Docker | 30m |

**Gate:** `http://cydm.test` renders Laravel; `php artisan about` shows MySQL + Redis connected; test suite green.

---

## Phase 1 — Foundation · ~3 weeks

The first genuinely usable product. Someone can log in and operate a branded, permissioned, audited application.

| Slice | Deliverable | Est. | Depends on |
|---|---|---|---|
| 1.1 | Design system: OKLCH tokens, shadcn components, dark mode | 3d | 0.6 |
| 1.2 | Tenancy core: tenants, domains, `BelongsToTenant`, isolation tests | 3d | 0.9 |
| 1.3 | Auth: login/register/reset/verify, TOTP 2FA, password policy | 3d | 1.2 |
| 1.4 | RBAC: 8 roles, permission matrix, policies | 2d | 1.3 |
| 1.5 | App shell: sidebar, breadcrumbs, dark mode, SW/EN switcher | 3d | 1.1, 1.4 |
| 1.6 | Dashboards: role-aware KPI tiles and charts | 3d | 1.5 |
| 1.7 | Audit log: immutable, before/after, actor/IP/device | 2d | 1.3 |
| 1.8 | Settings: institution profile, numbering, holidays, branding editor | 3d | 1.5 |

**Gate:** register → verify → enrol 2FA → log in → role-appropriate dashboard → switch to Swahili → toggle dark mode → log out. Every action audited. Verified in a real browser.

---

## Phase 2 — Members, savings & the ledger · ~5 weeks

**The posting engine lands first.** Every value movement after this point writes balanced journal entries. Retrofitting double-entry later is the most expensive mistake available in this project.

| Slice | Deliverable | Est. | Notes |
|---|---|---|---|
| 2.1 | Chart of accounts + posting engine | 5d | Tanzanian SACCOS CoA template |
| 2.2 | Member KYC: all Reg-2019 fields, documents, signature | 5d | NIDA/TIN, next of kin |
| 2.3 | Member lifecycle: draft → submitted → verified → approved → active | 3d | Maker-checker |
| 2.4 | Share capital: membership + voluntary, register, certificates | 4d | 24-month progress rule |
| 2.5 | Savings products: compulsory, voluntary, target, fixed deposit | 4d | |
| 2.6 | Transactions: deposit, withdrawal, transfer | 4d | Posts to GL |
| 2.7 | Interest accrual & posting | 4d | Daily balance, Actual/365 |
| 2.8 | Statements & passbook | 3d | PDF, SW/EN |
| 2.9 | Trial balance & financial statements | 4d | Balance sheet, P&L, cash flow |

**Gate:** open a member, buy shares, deposit, withdraw, accrue interest — and the trial balance balances to the cent.

---

## Phase 3 — Loans · ~6 weeks

| Slice | Deliverable | Est. | Notes |
|---|---|---|---|
| 3.1 | Loan products & fee structures | 3d | |
| 3.2 | Loan calculator: reducing balance, flat, EIR | 4d | Heavily tested |
| 3.3 | Application workflow: 4-stage maker-checker | 5d | Configurable approval matrix |
| 3.4 | Collateral & guarantors, with locking | 4d | Reg 33 limits |
| 3.5 | Disbursement | 3d | Multi-channel |
| 3.6 | Schedules & repayment allocation | 5d | Fees → penalties → interest → principal |
| 3.7 | Arrears, PAR ageing, collections | 5d | 1-30/31-60/61-90/91-180/180+ |
| 3.8 | Classification & provisioning | 4d | 5-tier, automated daily |
| 3.9 | Restructuring, write-off, recovery | 4d | Board approval trail |

**Gate:** a loan goes application → approval → disbursement → repayment → arrears → classification, with correct GL postings at every step and schedules matching hand calculations.

---

## Phase 4 — Money movement & regulatory reporting · ~5 weeks

| Slice | Deliverable | Est. | Notes |
|---|---|---|---|
| 4.1 | Gateway abstraction + fake driver | 3d | Unblocks work before credentials arrive |
| 4.2 | M-Pesa driver (C2B, B2C) | 4d | |
| 4.3 | Airtel, Mixx, HaloPesa, Tigo drivers | 5d | |
| 4.4 | Webhook reconciliation & settlement | 4d | Idempotent |
| 4.5 | SMS gateway + templates (SW/EN) | 3d | |
| 4.6 | WhatsApp Business API | 3d | |
| 4.7 | BoT MSP forms 1–10 | 8d | Generated from live data |
| 4.8 | CRB submission & report pull | 4d | |
| 4.9 | AML monitoring, CTR/STR | 4d | Thresholds, sanctions screening |

**Gate:** a real sandbox payment reconciles automatically; MSP forms generate from live data and tie to the trial balance.

---

## Phase 5 — Platform & scale · ~8 weeks

| Slice | Deliverable | Est. |
|---|---|---|
| 5.1 | Self-service tenant onboarding wizard | 5d |
| 5.2 | Billing, plans, usage limits | 5d |
| 5.3 | Super-admin console + impersonation | 4d |
| 5.4 | Member self-service portal | 8d |
| 5.5 | Group lending | 6d |
| 5.6 | HR & payroll (PAYE, NSSF, NHIF, SDL, WCF) | 6d |
| 5.7 | Fixed assets & depreciation | 4d |
| 5.8 | Dividends & AGM pack | 4d |
| 5.9 | Custom report builder | 5d |
| 5.10 | Public API + webhooks | 4d |
| 5.11 | USSD gateway | 4d |

---

## Deliberately deferred

| Item | Why | Revisit when |
|---|---|---|
| PostgreSQL migration | MySQL covers current needs; Laradock php-fpm lacks the driver | RLS or vector search becomes required |
| `pgvector` semantic search | Depends on Postgres | Document search becomes a real user need |
| Mobile app (React Native) | Web portal serves the need first | Portal adoption proves demand |
| Kubernetes deployment | Single VPS is sufficient early | Multi-region or >100 tenants |
| Biometric capture | Hardware dependency | A tenant requires it |
| E-signature integration | Provider selection needed | Legal review completes |

---

## Critical path

```
0.6 Laravel ──▶ 1.2 Tenancy ──▶ 1.3 Auth ──▶ 1.4 RBAC ──▶ 1.5 Shell
                                                              │
                                    2.1 Posting engine ◀───────┘
                                          │
                          ┌───────────────┼───────────────┐
                          ▼               ▼               ▼
                   2.2 Members     2.5 Savings      3.1 Loan products
                          │               │               │
                          └───────────────┼───────────────┘
                                          ▼
                                   3.6 Repayments
                                          │
                                          ▼
                                   4.7 MSP reports
```

**The two hard blockers:** tenancy (1.2) gates everything, and the posting engine (2.1) gates every money feature. Both are worth doing slowly and correctly.