0Launch
cd C:\Users\bsumi\ConsBook
python run.py
Open http://127.0.0.1:8477. The book of record is the single file
data\consbook.db — to back up, stop the app and copy that file; to restore, put it back.
The database currently holds the accepted demo quarters (FY2026-Q2 and Q3, both FINAL), so every screen
has data to explore. The period selector in the header (top right) controls which quarter every
screen shows; the fiscal year runs Oct 1 – Sep 30.
1The pipeline at a glance
Each quarter flows left to right. A stage cannot be skipped: the gates below the diagram are enforced
by the app, not by convention.
A · INGEST
Import TBs
- Upload each entity's trial balance (CSV/XLSX)
- Source profile decodes the preparer's layout & sign convention
- Staging screen: row count, Dr/Cr totals, balance check, period detected
- You approve with initials before anything posts
Imports
B · MAP
Map accounts
- Source account → consolidated account, per entity
- New/unknown accounts land in the work queue
- Mappings are versioned; remaps supersede, never edit
Mapping
COA
C · ELIMINATE & ADJUST
IC, JEs, rollforwards
- Register proposes eliminations; preview both sides
- Typed JEs with initials + supporting note
- Investment rollforwards tie to administrator reports
Intercompany
Journal Entries
Investments
D · CONSOLIDATE
Run
- Numbered, immutable runs per fund + period
- Re-runnable; diff any two runs — "what changed and why"
Consolidation Runs
E · REVIEW
Package Review
- BS, IS (qtr + FYTD), changes in net assets, schedules
- Click any number → drill to its composition
- Fix via pre-scoped JE, never direct edits
- Inline variance commentary
- Checklist gates FINAL
Package Review
Periods
F · EXPORT
Deliver
- Excel workbook — tab per statement, live formulas
- PDF — cover, TOC, page numbers, DRAFT/FINAL watermark
Exports
Hard gates: an unbalanced TB cannot post · an unmapped account blocks that
fund's consolidation · an intercompany pair that doesn't tie parks its difference in a highlighted
suspense line on the face of the package — never buried · the checklist must be all green before a
period can be marked FINAL · a FINAL period rejects every mutation.
2Your quarterly close, step by step
- Confirm the working quarter is OPEN.Periods
Set it in the header period selector. All screens follow it.
- Import every entity's trial balance.Imports
Pick entity + source profile (Hoku Accounting for the property books, Mainland Admin for
the fund reports); the period is detected from the filename (e.g. KCC_TB_FY2026-Q3.csv).
Review the staging screen and Approve & post. Resending a corrected TB later is fine —
approving it supersedes the old one with an audit entry.
- Clear the mapping work queue.Mapping
Any account the preparers added this quarter appears here. Map it once ("apply to future imports" on)
and it never asks again.
- Enter investment rollforwards.Investments
From each administrator report: beginning, contributions, distributions of income,
return of capital (both required — enter 0 explicitly), earnings, fair-value adjustment,
and the report's ending balance. The tie-out panel compares computed ending vs the report vs the books
and offers a pre-scoped correcting JE when they disagree.
- Review the intercompany preview.Intercompany
Shows exactly what the next run will eliminate, both sides of each pair, and any difference.
- Run consolidation for each fund.Package Review
The package renders as it will be delivered. Click any number to drill; anything wrong gets fixed by a
pre-scoped JE from the drill screen, then re-run. Runs are cheap and numbered — diff them freely.
- Write variance commentary.Package Review
Type directly in the commentary column and press Enter. Lines with a QoQ variance over $25,000 are
required; last quarter's text carries forward as a draft to edit.
- Checklist green → Mark FINAL.Periods
Six checks per fund: TBs posted & balanced, no unmapped accounts, run current, intercompany ties,
rollforwards tie, commentary complete. Finalizing locks the quarter permanently.
- Export.Exports
One click produces the Excel workbook and the PDF, stamped with period, run numbers, and FINAL.
Files land in exports\.
3Concepts you'll meet on screen
| Term | What it means here |
|---|
| Source profile |
A preparer's file format: column layout and sign convention. Files matching a profile import with
zero reconfiguration. Two are seeded: coded TB with Debit/Credit columns, and the fund report with
one signed Balance column (credits positive). |
| Sign convention |
Internally debits are positive, credits negative; a balanced TB sums to zero. Statements render
in natural presentation — liabilities, capital and income positive, contra amounts in (parentheses). |
| Quarter vs fiscal YTD |
TBs carry as-of balances; income-statement accounts arrive as fiscal-YTD. The quarter column is
computed as this TB minus last quarter's TB. |
| Consolidation run |
An immutable numbered snapshot: mapped TB lines + journal entries + register eliminations.
Re-running never overwrites; identical inputs produce a zero diff (that's the proof the pipeline is
deterministic). |
| Suspense lines (2999 / 4999) |
When an intercompany pair doesn't tie, the app eliminates at the lower of the two amounts
and parks the difference here — rendered highlighted on the package face until a correcting JE
clears it. 2999 catches balance-sheet pairs, 4999 income-statement pairs. |
| JE types |
ELIMINATION · RECLASS · TOP-SIDE · INVESTMENT ROLLFORWARD · OTHER. Every JE carries preparer
initials and a supporting note. JEs are voided (with reason), never deleted. |
| Distribution of income vs return of capital |
Two separate required rollforward fields. A return of capital reduces the investment;
booked as income it overstates both earnings and the asset — the tie-out exists to catch exactly
this (it has happened at seven figures). |
| Period lock |
FINAL periods reject imports, JEs, rollforward edits, mapping-driven changes and commentary.
Corrections go in the next open quarter as labeled adjustments. |
4When something doesn't tie
"Consolidation BLOCKED: unmapped accounts"
A preparer added a new account. Open Mapping, the work queue names it; pick the consolidated
account, leave "apply to future imports" checked, Map. Re-run.
Suspense line on the balance sheet
A due-to/from (or fee) pair is off — the intercompany summary shows both sides and the exact
difference. Click the suspense number to drill, find which side is missing the entry, and post the
pre-scoped JE from that screen. Re-run: the suspense line disappears when the pair ties.
"Books differ from the rollforward by …"
Usual suspects: a distribution misclassified on the fund books (return of capital recorded as income),
or a fair-value adjustment the administrator reported but the books never got. The Investments screen
quantifies the gap and pre-scopes the correcting JE.
Found an error in a FINAL quarter
The quarter stays locked — that's by design. Post the correction in the current open quarter as a
labeled adjustment (TOP-SIDE or RECLASS with a note referencing the prior period). The audit trail keeps
the full story.
Sanity habits
- The staging screen's balance check and the run's control total must always be 0.00.
- After any fix, re-run and diff — the diff page lists every account that moved and the JEs/imports that moved it.
- Before finalizing, skim the drill on the two or three largest numbers; composition beats intuition.
- Back up
data\consbook.db after each close (copy to C:\TAS_Data_Archive\ConsBook\).
5Try it right now (demo data)
The loaded demo already contains the full story of a messy quarter, cleaned up:
- Journal Entries →
JE-FY2026-Q3-001: the $25,000 intercompany break fixed from Package Review.
- Investments → PRAF: the $1.2M return-of-capital-booked-as-income catch, and its reclass (
JE-…-002).
- Consolidation Runs: diff HIF run #1 vs #2 to watch the suspense line clear, with the causing JE listed.
- Exports: open the FINAL workbook and click any Total cell — it's a live formula over its detail.
To rebuild this demo state from scratch: python scripts/replay_acceptance.py
(resets the database — never run it once real quarters are in).
Full test suite: python -m pytest tests/ -q.