docs/ARCHITECTURE.md

Production Architecture

How the demo engine would run against live Addepar and iCapital data.

Data flow

iCapital ──(positions, activity, NAV / contract values)──┐
                                                          ├─► Staging ─► Mapping ─► Reconcile ─► Rules
Addepar  ──(positions, transactions, valuations)─────────┘                                         │
                                                       ┌───────────────────────────────────────────┤
                                                       ▼                                           ▼
                                            Addepar import file                          Exception queue
                                            (adds, reclasses, marks)                     (ops review + sign-off)
                                                       │                                           │
                                                       └──────────────► Audit log ◄────────────────┘

1. Ingest. Pull the iCapital extracts and Addepar exports for the same as-of date into a staging schema. Store raw files unchanged for audit.
2. Map. Resolve iCapital fund, share class, and contract IDs to Addepar security IDs through a maintained security master. Unmapped items stop at this step and go to the queue; nothing downstream guesses.
3. Reconcile. Run the three layers (reference, commitment and activity, valuation) per account and holding. Activity ties on the iCapital event ID, never on amount.
4. Apply rules. Rule-based, reversible fixes are written to the Addepar import file. Everything else becomes an exception with evidence and a suggested fix.
5. Review. Ops works the queue. Approved fixes join the next import; rejected ones carry a reason code that feeds rule tuning.
6. Report. Cycle metrics: auto-resolution rate, exceptions by type, aging, and hours.

Cadence

Run	Scope
Daily	Activity: new calls, distributions, premiums. Capital calls surface before their due date.
Monthly	Full reconciliation, including evergreen fund NAVs and insurance contract values
Quarterly	Drawdown fund NAVs as GP statements post; stale-mark sweep

Controls

• Four-eyes on destructive changes: deletes, commitment edits, and new securities.
• Tolerances in config: rounding ($1.00) and staleness (120 days) live in config, not code, and changes are logged.
• Idempotent imports: every row carries its source reference, so re-running a cycle never double-books.
• Insurance values: tie out to the carrier statement; surrender value and death benefit can be added as further checks per product.
• Answer-key testing: the generator injects known breaks, and the tests require 100% detection with zero false positives before a rule change ships.

Extending

• Unfunded commitment and pacing checks against iCapital capital account statements
• Recallable distribution tracking
• K-1 and 1099 status per position for tax season
• CRM task creation (for example in Salesforce) for exceptions that need client or GP outreach