# 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