Global Portfolio Assistant

Personal project repository for:

• Multi-broker portfolio aggregation (Yochaa, Bamboo, Moomoo, Fidelity via API/CSV adapters)
• 95% capital-protection optimization rules
• Dividend intelligence and monthly income planning
• Web dashboard for consolidated portfolio tracking

MVP Architecture

1. app/connectors/: broker adapters and CSV ingestion
2. app/core/: canonical schemas and unified ledger building
3. app/risk/: high-watermark preservation and de-risking logic
4. app/dividends/: dividend event ingestion and forecasting
5. app/web/: FastAPI dashboard
6. app/reports/: monthly summary generation

Quick Start

cd global-portfolio-assistant
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Build unified holdings from sample CSVs
python app/core/build_unified_ledger.py

# Run risk/dividend engines and reports
python app/reports/run_monthly_pipeline.py
python app/reports/validate_broker_sync.py

# Optional: continuous automation loop
python app/reports/auto_sync_loop.py

# Start dashboard API
python3 -m uvicorn app.web.main:app --app-dir . --reload --port 8001

Open these in browser:

• http://127.0.0.1:8001/dashboard (visible tables for summary + Yochaa + Bamboo + validation)
• http://127.0.0.1:8001/portfolio/broker/yochaa
• http://127.0.0.1:8001/portfolio/broker/bamboo
• http://127.0.0.1:8001/portfolio/bamboo/account
• http://127.0.0.1:8001/sync/status
• http://127.0.0.1:8001/validation/brokers

Connector Strategy

• Priority order per platform:
  1. Official API adapter
  2. CSV import adapter
  3. Manual statement parser fallback

For Yochaa and Bamboo, MVP starts with CSV-first ingestion to avoid API blockers.

See live API onboarding guide: docs/broker_api_onboarding.md.