rework v2 plan

Caesar v2 rework — working plan / feature backlog

The living list of what we’re building in the Caesar rework. Built in screens/dashboard-v2.html (a duplicate of the live shell) so dashboard.html stays untouched until v2 lands. Sources feeding this: the Osita meeting (direction memo) + the QuickBooks teardown. In the prototype, AI features are designed/mocked (real inference is backend).

North star — Caesar is its own product, not a QB/Zoho clone. We study QuickBooks/Zoho to learn which problems are worth solving, then ship our own answer. No lifting their naming (“Business feed”, “funnel”, “Get things done”), IA, or dashboard composition. What makes Caesar its own: group-first consolidation · operations-fed intake (Polaris requisitions, not bank-plaid + manual invoices) · the Rechaj design system look · AI-forward as identity. Center of gravity = the group + its operations, reconciled to reality across entities. (Osita’s “day one copy, day two make it ours” — we’re at day two.)

Status tags: [done] · [decided] (agreed, not built) · [proposed] (my rec, needs a yes) · [open] (undecided) · [later] (fast-follow).

A. Structure & IA

[done] “Manual Journals” → Journal Entries (“+ New Entry”).
[proposed] Reorganize from flat Zoho tree → 3 tiers led by an entity switcher: Primary daily loop (Dashboard · Transactions · Journal Entries · Banking · Chart of Accounts) / Secondary (Purchases · Sales · Reports) / Admin (Documents · Settings).
[decided] Multi-entity / group accounts — topbar switcher that scopes the whole app; Group = read-only consolidated view. The differentiator.
- [decided] Model = one org tree; “group” and “entity” are node types.
  - Entity (leaf) = a real company; owns the books (own base currency · own bank accounts · own journal sequence); you post here.
  - Group (parent) = a consolidation lens; read-only, has a presentation currency; its numbers are derived by rolling up descendants (translate + eliminate). Nothing is stored “on a group”.
  - Create = add a node under a parent (Add entity = leaf · Add group = branch, e.g. a “West Africa” roll-up). Root (“MocX Group”) is seeded. Can create/switch between many group nodes.
  - Switch = jump the whole app to any node (group = consolidated · entity = transactional).
  - Each node has exactly one parent (strict tree). An entity in two roll-ups at once = a separate lighter “reporting tag”, not the tree.
- Add-entity form: name · country · base currency · tax registration · fiscal-year start · parent group → inherits shared master COA + own banks + own journal seq.
- Add-group form: name · presentation/reporting currency · parent.
- [open] MocX’s real shape — flat (Group → NG/US/CA) vs regional sub-groups · single root vs multiple top groups · any entity needing two roll-ups. Also still open: shared vs per-entity COA · presentation currency ₦ vs $ · consolidation depth in demo · default landing node.
[open] Transactions hub — one “categorize/match here” surface merging bank feed + Polaris- posted activity (QB-style), vs keeping Banking + Journal Entries as separate doors. (The backbone fork.)
[proposed] “+ New / Create” quick-create, grouped money-in / money-out (QB pattern).
[proposed] Task/outcome-named nav language over module labels.

B. Core loop — deepen what already exists

[proposed] Make Transaction Rules actually fire — today ruleForm captures criteria but saveRule only stores a name + toasts; nothing re-scans the feed. Wire criteria → auto-apply.
[proposed] Match names + links the real record — today “Match found” is a cosmetic seeded badge. Make it show + link the specific Invoice / Bill / Journal / Polaris requisition and the amount (“Check 75 · Hicks Hardware −$228.75”).
[proposed] Receipts / OCR capture — snap/upload → extract vendor/date/amount/tax → draft txn.
[proposed] Per-account bank-vs-book + “N to review” cards as the Banking header.
[decided] Currency from source — drop the manual Currency Adjustments page; rate comes from the Polaris requisition (via API) else a live FX API, editable post-reconciliation. (pending Francis.)

C. AI layer — surfaced in the “What needs you” feed

The feed is the approval inbox: every AI output is an approve/dismiss card; AI never posts alone.

[proposed] “What needs you” feed (home band + dedicated Feed screen) — the home for all cards below.
[proposed] AI-suggested rules — “you’ve filed MTN as Telephone 6×, create the rule?” → 1-click.
[proposed] AI reconciliation (hero) — upload statement → auto-match to records/requisitions → surface the deltas (bank charges, WHT, FX) → propose the reconciling entries.
[proposed] Smart categorize — category + confidence for any line no rule covers.
[proposed] Anomaly watchlist — dupes, cost spikes, threshold-splitting, odd-hour postings.
[proposed] Ask-your-books — natural-language query across the (group) data.
[proposed] Dashboard narrative — one plain-English “what changed and why” line.
[later] Period-close assistant · Polaris category → double-entry / COA-default suggester.

D. Dashboard & insights (next build focus, with group accounts)

[proposed] Tiles, not a number-wall — each with its own period picker + trend arrow + “to review”.
[proposed] Money-in / money-out funnel (repointed at MocX AR / requisition states).
[proposed] Cash-flow projection + threshold line (planner, not just history).
[proposed] Per-entity contribution tile (stacked — sells the group story; QB can’t do this).
[proposed] Revenue by line of business — swap vs retrofit.
[proposed] Spend-by-category donut · AR/AP aging buckets · currency exposure (NGN/USD/CAD) · reconciliation health tiles.
Chart discipline: consolidated in presentation currency, or index-rebased when scales differ.

E. Reports & Chart of Accounts

[proposed] Reports: favorites (starred) · categories/library · Audit Log · Business Snapshot one-pager · Budgets (vs actual) · Cash flow planner.
[proposed] COA: seeded default accounts · sub-account nesting · per-account register.

F. Deferred / skip

[later] Recurring Journals (Osita: fast-follow).
[skip] Payroll · Team · Time · Mileage · Contractors / 1099s (US-specific) · full Inventory (lives in the Rechaj inventory app) · Lending / Marketing / financing upsells.
[proposed] Sales demoted to secondary (MocX barely invoices; revenue is API-fed).

Build sequence (progressive)

This is the design-prototype order (what we build in dashboard-v2.html), sequenced by dependency

the demo cadence. Osita’s functional order (COA → Journals → Polaris API → Banking → Dashboard) is the backend/integration track; ours leads with the group foundation + dashboard because that’s the near-term design focus and the layer everything else renders inside.

In progress — dashboard-v2.html: Phase 1 shell (3-tier Caesar-native nav · topbar entity/group switcher that rescopes the app · create-entity + create-group modals) and the Phase 2 Dashboard (scope-aware header + KPIs · What needs you feed · Entity contribution roll-up) are built & verified — canon lint 0 errors, console clean, switcher + routing working. Next down the menu: Transactions. Known small follow-ups: breadcrumb parent still says “Accountant” for Journal Entries; KPI bar/foot detail + the lower charts (cash flow / income-expense / top-expenses) not yet rescoped or Caesar-relabelled.

Phase 0 · Lock these first (they gate the build)

Transactions: unified hub vs separate Banking/Journals doors.
MocX shape: flat 3 entities vs a country as a sub-group (the sub-company question).
Shared vs per-entity COA · presentation currency ₦ vs $ · consolidation depth in demo · default landing node.

Phase 1 · Foundation — group model + Caesar-native shell → ~Thu entity-switching demo

Org-tree model (group nodes + entity nodes).
Topbar switcher (scopes the whole app; group = consolidated, entity = transactional).
Settings → Organisation: create group / create entity flows.
Reworked nav: our 3-tier IA + our naming (not QB/Zoho labels).

Phase 2 · Dashboard → ~Fri demo (chosen focus)

Tiles in our composition: per-tile period + trend + “to review”.
Money-in / money-out in our language · cash-flow forecast + threshold.
Per-entity contribution · swap-vs-retrofit revenue · currency exposure.
The “What needs you” feed (AI approval inbox) lives here.

Phase 3 · Core loop — Transactions hub (after the ② fork is locked)

Intake (Polaris requisitions + bank) → for-review queue.
Categorize + match that names/links the real record.
Rules that actually fire + AI-suggested rules → feed.
AI smart-categorize · anomalies · deltas → feed.

Phase 4 · Ledger + Chart of Accounts

Journal Entries as the posting target (rename done; wire postings).
COA: seeded defaults · sub-accounts · per-account register.

Phase 5 · Banking + AI reconciliation (the hero)

Bank-vs-book + to-review cards.
Statement upload → AI match → delta detection → proposed entries · guided reconcile.

Phase 6 · Reports & insights

Consolidated + per-entity P&L / Balance Sheet / Cash Flow.
Favorites · categories · Audit Log · Business Snapshot · Budgets · Cash-flow planner.
Ask-your-books · dashboard narrative.

Phase 7 · Fast-follows / cleanup

Currency-from-source wiring · demote Sales · Recurring (fast-follow) · Receipts/OCR · period-close assistant.

Parked (built, uncommitted, batched — not pushed): Journal Entries rename · bundled-transaction detail (+ balance-revert fix).

Built so far this session (uncommitted, in dashboard-v2.html):

Phase 1 shell — 3-tier Caesar-native nav · topbar entity/group switcher · create-entity/group modals ✓
Phase 2 Dashboard — fully scope-aware: currency + KPIs, per-entity bank cards (Canada re-cast to RBC · C$), show/hide of the group-only Entity-contribution tile, entity-scoped What-needs-you feed, solo full-width layout when one card, AND the lower charts (Cash Flow summary+axis, Top Expenses) rescoped per currency. AI items carry the DS sparkle marker. ✓
Phase 3 Transactions hub — unified review of Polaris requisitions + bank lines · source badges (Bank / Polaris) · AI match/categorize suggestions with confidence % · Match/Post actions (move to Posted) · Needs-review/Posted/All tabs · scope-aware · multi-currency. (Fork resolved: unified hub.) ✓
Phase 4 Journal Entries — scope-aware (per-entity filter · informative empty state for entities with none, “postings land here”) · new Source column (Manual / Polaris / Bank) framing it as the ledger destination · sub reframed · breadcrumb fixed to just “Journal Entries” (dropped the “Accountant ›” Zoho-ism). Seeded journals tagged to Nigeria; no fabricated foreign-currency journals (avoids the ×1000 scaler). ✓
Phase 5 Banking — scope-aware: accounts table filters to the active entity (US → Mercury, Canada → RBC, Nigeria → 4, Group → 6) · stat row + “cash position” footer + sub rescope per entity/currency · jpmorgan reconciled to RBC · Reserve (CAD) across the BANK data + account row (clears review finding #3) · re-renders on nav + scope change. Deferred: the multi-series cash-flow chart still shows all series + the old “JPMorgan” legend (illustrative, like the dashboard charts). ✓
Phase 4 Chart of Accounts — the shared master chart model (chosen over per-entity charts / group-only): one chart every entity inherits · bank/cash accounts are entity-owned (Group → all 5 incl. Mercury·US + RBC·CA; Nigeria → its 3; US → Mercury only; Canada → RBC only) · structural accounts are shared, shown at every scope · per-entity balances in the entity’s own currency (₦ / $ / C$), sourced from the same SCOPES figures the dashboard uses (as strings, so the ×1000 scaler can’t touch them) · inherited-but-unused accounts read “—” · sub reframes per scope with an “N active of M” count · breadcrumb de-Zoho’d (dropped “Accountant ›”). Re-renders on nav + scope change. ✓
- Per-entity account applicability ✓ (built later this session): each COA account carries an optional ents list — absent = universal (applies to every entity), ['ng'] = Nigeria-only, etc. coaVisible hides non-applicable accounts at entity scope (Group still sees all). The New/Edit Account form has an “Applies to” control (All entities / per-entity checkboxes) defaulting to the current entity when scoped to one. Tagged the Nigeria-specific seeds (WHT Receivable/Payable, VAT Payable, Rider’s Loan, Corporate Card) ents:['ng'] → US chart dropped 22→17 accounts; a US-created “Sales Tax” shows at US + Group but not Nigeria. Keeps the shared master spine while removing cross-entity clutter.
Records tier · Purchases — all seven screens (Vendors · Bills · Payments Made · Expenses · Recurring Bills · Recurring Expenses · Vendor Credits) made scope-aware: every list filters to the active entity, subs carry the entity name, foreign entities (US/CA) show a tailored empty state (“No bills yet for MocX US · this entity keeps its own books · recorded here once posted”). Built via a one-line bulk entity-tagger (all seed records → ng, plus the Sales arrays pre-tagged for the next phase) + a shared scopeEmpty() helper + a scope filter in each *Filtered() + a setScope re-render hook. Seed data is Nigeria’s, so NG ≈ Group; US/CA start empty pending their own books (consistent with Journal Entries). ✓
Records tier · Sales — all six screens (Customers · Invoices · Payments Received · Estimates · Credit Notes · Recurring Invoices) made scope-aware with the same pattern (scope filter per *Filtered(), scopeEmpty() empty states, entity-named subs, setScope re-render hook). Group/NG show data; US/CA empty pending own books. ✓ Records tier complete.
Reports — scope-aware in the shape that fits statements (not row-filtering): Group/Nigeria compute the full financial statements (P&L, Balance Sheet, Trial Balance, AR/AP aging, etc.) in ₦ consolidated; US/Canada show a unified “No posted activity for MocX US yet · switch to MocX Group for the consolidated view” state, labelled in the entity’s currency, since those entities have no posted books yet. Report header + doc caption + Reports Center sub all carry the entity name + currency; live scope-switch on an open report re-renders. Never shows NG’s numbers mislabelled as a foreign entity’s. ✓
Documents — scope-aware: file list + folder counts (All / Files / Bank Statements / Trash) filter to the active entity, sub carries the entity name, foreign entities show “No documents yet for MocX US · this entity keeps its own files”. Live scope-switch re-renders. Tagged via the bulk-tagger (DOCUMENTS added). ✓
✅ Scope-awareness is a complete end-to-end pass across the entire menu: Dashboard · Transactions · Journal Entries · Banking · Chart of Accounts · Purchases (7 screens) · Sales (6 screens) · Reports · Documents. The entity/group switcher rescopes every surface, with consistent per-entity currency + tailored empty states for entities without their own books yet.

Post-scope build (user chose: do all three, in order)

① Seed MocX US as a real 2nd entity — IN PROGRESS

Currency infra: usd() now renders the active scope’s symbol (₦ / $ / C$ via CURSYM); the ×1000 seed scaler now skips non-ng records so USD/CAD seeds aren’t corrupted. Hardcoded ₦0 balance cells → scope-aware usd(0). ✓
US dataset (all ent:'us', USD): 2 customers (Cloudline, Beacon), 2 vendors (AWS, WeWork), 3 invoices, 3 bills, 1 payment received + 1 made, 1 journal, 2 documents. Balances tie to SCOPES.us (AR $45,200, AP $21,760) so dashboard/COA/reports agree. ✓
Reports for US: transaction-based reports (AR/AP aging, sales/purchases by X, expenses, balances) scope-filter via scopeArr() and compute for US ($45,200 AR / $21,760 AP verified); pure-ledger reports (P&L, Balance Sheet, Trial Balance, etc.) show “No ledger for MocX US yet” (no per-entity numeric ledger). ✓
Verified: US shows populated lists in $, Group consolidates NG+US (11 bills / 12 invoices), group P&L still ₦1.33B (scaler intact), lint 0, console clean.
1d create-entity/group wiring: addEntity() / addGroup() now mint a real node — new SCOPES stub (zeroed KPIs in the chosen currency), CURSYM/NEEDS/BANK_STAT entries, a live switcher item, then switches to it. Generalized every us/ca-specific check (empty states, Documents, Reports ledger, COA sub, currency caption) to “any non-ng, non-group entity”. setScope treats group nodes as consolidated (relabelled). Verified: created “MocX Ghana” (₵ GHS → empty books, ₵0 KPIs, tailored empty states, inherited COA) + “West Africa” group (consolidated), no regression to NG/US/CA/Group. Nodes are runtime-only (reset on reload, like any prototype create). ✓ Task ① complete.

② Deepen the core loop — IN PROGRESS

(a) Rules that fire ✓ — saveRule now reads the real criteria (field · operator · value, all/any, withdrawals/deposits) + target account, then fireRule() scans the account’s feed, auto-categorizes every matching line (posts via _feedApply, drops the uncat count, refreshes the view). Verified: manual rule “TELPO → COGS” categorized the TELPO line; the AI-suggested-rule card in “What needs you” now calls approveAISuggestedRule() → creates a real firing rule (MTN → Telephone Expense categorized the MTN line + posted it). Non-matching lines untouched.
(b) Match links the real record ✓ — hub match text + bank-feed “Match found” render the record number via a broadened linkifyDocs (handles INV-2231 AND alphanumeric INV-US-02), clickable → opens the Bill/Invoice; confirming Match calls reconcileDoc() → marks the linked record Paid (verified INV-2231 + INV-US-02 Overdue→Paid). US Documents linked column clickable too.
(c) Receipts / OCR capture ✓ — “Scan receipt” on the Expenses header → receiptModal() → mock-extracts vendor·date·amount·tax + AI-suggested category w/ confidence chip (scope-aware currency ₦ / $) → posts a Draft expense tagged to the active entity. Verified NG (Ikeja Electric ₦185,000) + US (Uber $42.5).
✓ Task ② complete — the mocked core loop is now working behavior. Lint 0, console clean.

③ AI “What needs you” feed — ✓ COMPLETE

The dashboard band is now a real approve/dismiss inbox: every card has an action + a dismiss ×; both remove the card and update the count (needsResolve / needsDismiss), scope-aware (group 6 · US 3 · CA 2 · new entity empty → “You’re all caught up”).
Card types with real effects: AI-suggested rule (→ creates a firing rule), smart-categorize w/ confidence % (→ aiCategorize scans + posts the matching feed lines), reconciliation delta (→ postReconcileEntry), anomaly / duplicate flag (→ opens the record), plus review/close nav cards. Verified: approving “Auto-categorize Telpo” categorized the feed line (4→3) and removed the card (6→5).
Optional fast-follow: a dedicated full-screen Feed (the band already shows the full list, so deferred).

✅ Post-scope build COMPLETE — Tasks ①②③ all done (uncommitted in `dashboard-v2.html`)

Real 2nd entity (US in $) + live create-entity/group · working core loop (rules fire · match reconciles · receipts→draft) · AI approval-inbox feed. Lint 0, console clean throughout. Not committed/pushed. Suggested next: a /design-review pass + commit.

Known consolidation limitation: at Group scope, foreign-entity amounts render with the ₦ symbol on their untranslated native number (no FX translation) — real consolidation needs a rates layer (backend). Entity-scope views are currency-correct. Nothing committed/pushed yet — all rework uncommitted in dashboard-v2.html.