annuities-platform

Retirement Services & Annuities — Combined Monorepo Built for the Claude Certified Architect Foundations (CCAF) exam study lab.

annuities-platform/
├── flask_app/          ← RetireWise web UI  (Flask, port 5000)
├── mcp_server/         ← FastMCP server     (Claude Code, stdio)
├── data/               ← Shared 500-row annuities dataset
├── scripts/setup.sh    ← One-command first-time setup
├── Makefile            ← All common tasks
├── CLAUDE.md           ← Root context for Claude Code
└── .vscode/            ← launch.json  mcp.json  settings.json

---

Quick start

# 1. Unzip and enter the project
cd ~/annuities-platform

# 2. One-command setup  (venv + deps + data + MCP registration + tests)
bash scripts/setup.sh
# — or —
make setup

# 3. Open in VS Code
code .

# 4. Start Flask web app
make flask
# → http://localhost:5000

---

Day-to-day commands

Task	Command
Start Flask web app	make flask
Run all 38 tests	make test
Test MCP server standalone	make mcp-test
Re-register MCP with Claude Code	make mcp-add
Regenerate dataset	make data
Install / update deps	make install

---

Flask web app — pages

URL	What you see
http://localhost:5000/	Portfolio dashboard — stat cards, product/risk/state breakdowns
/clients	Paginated, sortable, filterable list of all 500 clients
/client/CLIENT_0001	Full contract detail + suitability assessment + payout projection
/search	Multi-field search form (product, risk, state, rider, premium range)
/api/portfolio	JSON portfolio summary
/api/client/CLIENT_0001	JSON single contract
/api/clients?risk_profile=Aggressive	JSON filtered list

---

MCP server — tools

Tool	What it does
get_client(client_id)	Full contract for one client
search_clients(...)	Filter by product/risk/state/premium
portfolio_summary(group_by)	Aggregate stats by any column
calculate_payout(principal, rate, years)	Amortized monthly payout
calculate_percentage(value, pct)	Simple percentage utility

Prompts: annuity_review, client_summary, portfolio_report Resource: annuities://dataset

---

Claude Code integration

After make setup or make mcp-add:

claude           # launch Claude Code in this project
/mcp             # → annuities-server ✔ Connected
/memory          # → shows all 3 CLAUDE.md files loaded

# Try it:
"Use the annuities-server to look up CLIENT_0001"
"Give me a portfolio summary grouped by risk_profile"
"Use the annuity_review prompt for CLIENT_0050"

---

Project structure — full

annuities-platform/
│
├── .env.example               ← Copy to .env and add ANTHROPIC_API_KEY
├── .gitignore
├── Makefile                   ← make setup | flask | test | mcp-test
├── requirements.txt           ← Flask + mcp[cli] + pydantic + pytest
├── CLAUDE.md                  ← Root context (all subfolders inherit)
│
├── .vscode/
│   ├── launch.json            ← F5 to run Flask; also test + data configs
│   ├── mcp.json               ← Wires MCP server into Claude Code / VS Code
│   └── settings.json          ← Python interpreter = .venv, pytest config
│
├── data/
│   ├── annuities.csv          ← 500 synthetic rows (seed=42, reproducible)
│   └── generate_data.py       ← Regenerate: python data/generate_data.py
│
├── scripts/
│   └── setup.sh               ← One-shot: venv + pip + data + MCP + tests
│
├── flask_app/
│   ├── CLAUDE.md              ← Flask-specific rules (inherits root)
│   ├── src/
│   │   ├── app.py             ← create_app() factory + entry point
│   │   ├── models.py          ← AnnuityContract dataclass, load/filter/aggregate
│   │   ├── views.py           ← All routes (HTML + /api/* JSON)
│   │   ├── templates/
│   │   │   ├── layout.html    ← Base: header, nav, footer
│   │   │   ├── index.html     ← Dashboard
│   │   │   ├── clients.html   ← Paginated sortable list
│   │   │   ├── client.html    ← Contract detail + suitability
│   │   │   └── search.html    ← Search/filter form
│   │   └── static/css/
│   │       └── styles.css     ← Responsive dark-header design
│   └── tests/
│       └── test_app.py        ← 38 pytest tests (HTML routes + JSON API + models)
│
└── mcp_server/
    ├── CLAUDE.md              ← MCP-specific rules (inherits root)
    ├── server.py              ← FastMCP server (5 tools + 1 resource + 3 prompts)
    ├── test_client.py         ← Standalone MCP protocol test (no Claude needed)
    └── templates/
        ├── annuity_review/    ← config.yaml + template.md
        ├── client_summary/    ← config.yaml + template.md
        └── portfolio_report/  ← config.yaml + template.md

---

CCAF exam coverage

File / feature	Domain
mcp_server/server.py — 5 tools, 1 resource, 3 prompts	Domain 2
stdio transport, claude mcp add with venv path	Domain 2
3-level CLAUDE.md hierarchy (root / flask_app / mcp_server)	Domain 3
.vscode/mcp.json + slash commands	Domain 3
flask_app/src/models.py — Pydantic-style typed dataclass	Domain 4
JSON API endpoints with structured output	Domain 4
mcp_server/templates/ — YAML-driven prompt templates	Domain 4
Shared data/ — single source of truth across both apps	Domain 5

---

Environment variables

Variable	Default	Description
ANTHROPIC_API_KEY	—	Required for Claude Code / Python scripts calling the API
DATA_FILE	data/annuities.csv	Override path to dataset
SECRET_KEY	dev-annuities-key	Flask session key — change in production
FLASK_DEBUG	1 (in .env)	Enable Flask debug mode