Atlas AI Wealth — MVP

AI-native wealth intelligence platform implementing TRD.md vertical slice: Excel upload → parse → classify → portfolio analytics → dashboard.

Original onboarding doc: README.korabayev.md

---

Stack

Layer	Tech
Backend	Python 3.12, FastAPI, SQLAlchemy 2, SQLite (dev)
Parser	pandas, openpyxl — multi-sheet XLSX/CSV, fuzzy headers
Analytics	Modified Dietz TWR, Newton IRR, moving-avg cost, allocation
AI Copilot	Rule-based templated insights (LLM plug-in stub)
Frontend	Next.js 14, React 18, TypeScript, Tailwind, SWR

---

TRD Coverage

TRD §	Component	Status
§3	Frontend (Next/TS/Tailwind)	Dashboard, Portfolio, Tx, CashFlow, Upload
§4	FastAPI REST + OpenAPI + JWT auth	REST + OpenAPI ✓, auth = stub user
§5	PostgreSQL / Redis	SQLite (swap via DATABASE_URL)
§6	Core data models	User, Account, Transaction, Position ✓
§7	File processing (XLSX/CSV/PDF)	XLSX + CSV ✓, PDF deferred
§8	Classification (rule + AI)	Rule layer ✓, AI layer = stub
§9	Portfolio analytics	TWR, IRR, PnL, allocation ✓
§10	Market data (Yahoo/Polygon/…)	Stub prices (wire yfinance later)
§11	Forecasting (ARIMA/XGB/LSTM)	Deferred
§12	AI Copilot (OpenAI/Anthropic + RAG)	Rule-based stub answers ✓
§13–18	Security/Infra/DevOps/Tests	Phase 2

---

Run It

1. Backend

cd backend
/opt/homebrew/bin/python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt

# Generate a sample broker statement (optional)
.venv/bin/python -m scripts.generate_sample

# Start API
.venv/bin/uvicorn app.main:app --reload --port 8000

API: http://localhost:8000 · OpenAPI docs: http://localhost:8000/docs

2. Frontend

cd frontend
npm install
cp .env.example .env.local   # adjust NEXT_PUBLIC_API_BASE if needed
npm run dev

App: http://localhost:3000

3. End-to-End Demo

1. Open http://localhost:3000/upload.
2. Upload backend/sample_broker_statement.xlsx.
3. Visit Dashboard → Portfolio → Cash Flow → Transactions.
4. Ask AI Copilot from the Dashboard: "what is my performance?", "how much did I spend?", "what is my concentration risk?"

---

API Endpoints

GET  /health
POST /upload                            multipart/form-data file=<xlsx|csv>
GET  /accounts
GET  /transactions?transaction_type=...&asset=...&q=...
GET  /portfolio/metrics
GET  /cashflow/summary?year=2026
GET  /cashflow/spending?year=2026
GET  /cashflow/dividends?year=2026
GET  /dashboard
POST /copilot/ask                       { "question": "..." }

---

Repository Layout

backend/
  app/
    main.py              FastAPI app + CORS + router registration
    config.py            Pydantic settings (env-driven)
    db.py                SQLAlchemy engine/session
    models.py            User, Account, Transaction, Position
    schemas.py           Pydantic response models
    parser.py            XLSX/CSV multi-sheet broker parser
    classifier.py        Rule-based tx type + spending category
    analytics.py         TWR (Mod. Dietz), IRR, PnL, allocation, cashflow
    market_data.py       Price stub (fallback dict)
    services.py          Parser+classifier+persistence orchestration
    deps.py              FastAPI deps (current_user stub)
    routes/
      upload.py
      accounts.py
      transactions.py
      portfolio.py
      cashflow.py
      dashboard.py
      copilot.py
  scripts/
    generate_sample.py   Produces sample_broker_statement.xlsx
  requirements.txt
  .env.example
frontend/
  app/                   Next.js App Router pages
    page.tsx                  Dashboard
    portfolio/page.tsx
    transactions/page.tsx
    cashflow/page.tsx
    upload/page.tsx
    layout.tsx
    globals.css
  components/
    Nav.tsx
    Copilot.tsx
    AllocationBar.tsx
  lib/
    api.ts               fetcher + formatters
    types.ts             API response types
  package.json
  tailwind.config.js
  tsconfig.json
  next.config.js
PRD.md
TRD.md
README.md                (this file)

---

What's Stubbed (Phase 2+)

• Auth: single demo user. JWT/OAuth2/MFA → TRD §13.
• Market data: in-memory fallback prices. Wire yfinance or Polygon in market_data.py.
• AI Copilot LLM: templated insights. Replace routes/copilot.py:ask with OpenAI/Anthropic + RAG (TRD §12).
• PDF parsing: only XLSX/CSV today.
• Forecasting engine: TRD §11 not implemented.
• Postgres: SQLite in dev. Set DATABASE_URL=postgresql://... to switch.
• Redis/Celery/S3/CloudFront: TRD §14 infra deferred.