# tech-armstrong/fp-agentic-prod architecture

> Architecture diagram of the GitHub repository tech-armstrong/fp-agentic-prod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tech-armstrong/fp-agentic-prod
- Repository: https://github.com/tech-armstrong/fp-agentic-prod

## Overview

This is an AI-powered financial-planning dashboard: users browse Airtable client records, inspect portfolio and liability summaries, and ask questions through a Copilot sidebar. They can also run financial plans, review RSU market data, export plans as PowerPoint, and upload policy PDFs for OCR-based summaries. The graph separates the dashboard, API services, planning engine, and assistant/policy workflow. Some service-to-service links are documented; unsampled implementation details are not inferred.

Main entry points: [`components/ClientsDashboard.tsx`](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/ClientsDashboard.tsx) (Client dashboard), [`lib/fastapi-proxy.ts`](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/lib/fastapi-proxy.ts) (FastAPI proxy), [`backend-airtable/main.py`](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend-airtable/main.py) (Airtable API), [`agent/main.py`](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/agent/main.py) (LangGraph agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard UI"]
  node_app["Dashboard shell<br/>[page.tsx]"]
  node_client_ui["Client dashboard"]
  node_plan_ui["Plan panel"]
  node_spouse_ui["Spouse details"]
  node_education_ui["Education planning"]
end

subgraph group_api["Application APIs"]
  node_airtable_routes["Client routes<br/>[route.ts]"]
  node_airtable_api["Airtable API<br/>[main.py]"]
  node_airtable[("Airtable")]
  node_plan_route["Plan run route<br/>[route.ts]"]
  node_ppt_route["Plan export route<br/>[route.ts]"]
  node_proxy["FastAPI proxy<br/>[fastapi-proxy.ts]"]
  node_rsu_market_route["RSU routes<br/>[route.ts]"]
end

subgraph group_planning["Financial Planning"]
  node_plan_runner["Plan runner"]
  node_workflow["Planning workflow<br/>[workflow.py]"]
  node_planning_nodes["Planning calculations"]
  node_client_state["Plan state"]
end

subgraph group_assistant["Assistant and Policy"]
  node_copilot_route["Copilot route<br/>[route.ts]"]
  node_agent["LangGraph agent<br/>[main.py]"]
  node_ocr_route["Policy upload route<br/>[route.ts]"]
  node_ocr_client["OCR service client<br/>[ocrService.ts]"]
  node_ocr_service["Policy OCR service<br/>[main.py]"]
  node_ocr_processor["PDF processor<br/>[processor.py]"]
end

subgraph group_market["RSU and Reporting"]
  node_rsu_api["RSU market API<br/>[rsu_market.py]"]
  node_ppt_endpoint["PPT migration endpoint<br/>[endpoint.py]"]
  node_ppt_deck["PowerPoint deck<br/>[deck.py]"]
end

node_user(("User"))
node_azure["Azure OpenAI"]
node_tavily["Tavily search"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_client_ui
node_user -->|"browses clients"| node_client_ui
node_client_ui -.->|"loads records"| node_airtable_routes
node_airtable_routes -.->|"forwards requests"| node_airtable_api
node_airtable_api -->|"reads and writes"| node_airtable
node_client_ui -->|"shows plan"| node_plan_ui
node_user -->|"requests plan"| node_plan_ui
node_plan_ui -.->|"submits plan"| node_plan_route
node_plan_route -->|"forwards request"| node_proxy
node_proxy -->|"calls API"| node_plan_runner
node_plan_runner -->|"invokes workflow"| node_workflow
node_workflow -.->|"dispatches stages"| node_planning_nodes
node_planning_nodes -->|"updates state"| node_client_state
node_client_ui -->|"renders"| node_spouse_ui
node_client_ui -->|"renders"| node_education_ui
node_user -->|"asks questions"| node_copilot_route
node_copilot_route -->|"routes chat"| node_agent
node_agent -->|"generates responses"| node_azure
node_agent -->|"searches web"| node_tavily
node_user -->|"uploads policy PDF"| node_ocr_route
node_ocr_route -->|"summarizes document"| node_ocr_client
node_ocr_client -->|"posts PDF"| node_ocr_service
node_ocr_service -->|"processes PDF"| node_ocr_processor
node_user -->|"views market data"| node_rsu_market_route
node_rsu_market_route -->|"forwards request"| node_proxy
node_proxy -->|"calls API"| node_rsu_api
node_user -.->|"exports plan"| node_ppt_route
node_ppt_route -->|"forwards export"| node_proxy
node_airtable_api -->|"serves migration endpoint"| node_ppt_endpoint
node_ppt_endpoint -->|"builds deck"| node_ppt_deck

click node_app "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/page.tsx"
click node_client_ui "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/ClientsDashboard.tsx"
click node_plan_ui "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/FinancialPlanPanel.tsx"
click node_spouse_ui "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/SpouseDetailsPanel.tsx"
click node_education_ui "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/EducationPlanningSection.tsx"
click node_airtable_routes "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/airtable/clients/route.ts"
click node_airtable_api "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend-airtable/main.py"
click node_plan_route "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/financial-plan/run/route.ts"
click node_ppt_route "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/financial-plan/ppt/route.ts"
click node_proxy "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/lib/fastapi-proxy.ts"
click node_plan_runner "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend/financial_plan_runner.py"
click node_workflow "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/Workflow/workflow.py"
click node_planning_nodes "https://github.com/tech-armstrong/fp-agentic-prod/tree/main/Financial_Planning/Nodes"
click node_client_state "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/Models/client_data_state.py"
click node_copilot_route "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/copilotkit/route.ts"
click node_agent "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/agent/main.py"
click node_ocr_route "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/parse-policy-document/route.ts"
click node_ocr_client "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/lib/ocrService.ts"
click node_ocr_service "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/ocr-service/main.py"
click node_ocr_processor "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/ocr-service/processor.py"
click node_rsu_api "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend/rsu_market.py"
click node_rsu_market_route "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/rsu/market-data/route.ts"
click node_ppt_endpoint "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/PPTX_Migration/endpoint.py"
click node_ppt_deck "https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/PPTX_Migration/deck.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_client_ui,node_plan_ui,node_spouse_ui,node_education_ui,node_user toneBlue
class node_airtable_routes,node_airtable_api,node_airtable,node_plan_route,node_ppt_route,node_proxy,node_rsu_market_route toneAmber
class node_plan_runner,node_workflow,node_planning_nodes,node_client_state toneMint
class node_copilot_route,node_agent,node_ocr_route,node_ocr_client,node_ocr_service,node_ocr_processor toneRose
class node_rsu_api,node_ppt_endpoint,node_ppt_deck,node_azure,node_tavily toneIndigo
```

## Components

### Dashboard UI

- [Dashboard shell](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/page.tsx): `app/page.tsx`
- [Client dashboard](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/ClientsDashboard.tsx): `components/ClientsDashboard.tsx`
- [Plan panel](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/FinancialPlanPanel.tsx): `components/FinancialPlanPanel.tsx`
- [Spouse details](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/SpouseDetailsPanel.tsx): `components/SpouseDetailsPanel.tsx`
- [Education planning](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/components/EducationPlanningSection.tsx): `components/EducationPlanningSection.tsx`

### Application APIs

- [Client routes](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/airtable/clients/route.ts): `app/api/airtable/clients/route.ts`
- [Airtable API](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend-airtable/main.py): `backend-airtable/main.py`
- **Airtable**
- [Plan run route](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/financial-plan/run/route.ts): `app/api/financial-plan/run/route.ts`
- [Plan export route](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/financial-plan/ppt/route.ts): `app/api/financial-plan/ppt/route.ts`
- [FastAPI proxy](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/lib/fastapi-proxy.ts): `lib/fastapi-proxy.ts`
- [RSU routes](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/rsu/market-data/route.ts): `app/api/rsu/market-data/route.ts`

### Financial Planning

- [Plan runner](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend/financial_plan_runner.py): `backend/financial_plan_runner.py`
- [Planning workflow](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/Workflow/workflow.py): `Financial_Planning/Workflow/workflow.py`
- [Planning calculations](https://github.com/tech-armstrong/fp-agentic-prod/tree/main/Financial_Planning/Nodes): `Financial_Planning/Nodes`
- [Plan state](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/Models/client_data_state.py): `Financial_Planning/Models/client_data_state.py`

### Assistant and Policy

- [Copilot route](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/copilotkit/route.ts): `app/api/copilotkit/route.ts`
- [LangGraph agent](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/agent/main.py): `agent/main.py`
- [Policy upload route](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/app/api/parse-policy-document/route.ts): `app/api/parse-policy-document/route.ts`
- [OCR service client](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/lib/ocrService.ts): `lib/ocrService.ts`
- [Policy OCR service](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/ocr-service/main.py): `ocr-service/main.py`
- [PDF processor](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/ocr-service/processor.py): `ocr-service/processor.py`

### RSU and Reporting

- [RSU market API](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/backend/rsu_market.py): `backend/rsu_market.py`
- [PPT migration endpoint](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/PPTX_Migration/endpoint.py): `Financial_Planning/PPTX_Migration/endpoint.py`
- [PowerPoint deck](https://github.com/tech-armstrong/fp-agentic-prod/blob/main/Financial_Planning/PPTX_Migration/deck.py): `Financial_Planning/PPTX_Migration/deck.py`

### Other components

- **User**
- **Azure OpenAI**
- **Tavily search**

## Connections

- User → Dashboard shell: uses (evidence: `README.md`)
- Dashboard shell → Client dashboard: renders (evidence: `app/page.tsx`)
- User → Client dashboard: browses clients (evidence: `README.md`)
- Client dashboard → Client routes: loads records
- Client routes → Airtable API: forwards requests
- Airtable API → Airtable: reads and writes (evidence: `backend-airtable/main.py`)
- Client dashboard → Plan panel: shows plan (evidence: `components/ClientsDashboard.tsx`)
- User → Plan panel: requests plan (evidence: `README.md`)
- Plan panel → Plan run route: submits plan
- Plan run route → FastAPI proxy: forwards request (evidence: `app/api/financial-plan/run/route.ts`)
- FastAPI proxy → Plan runner: calls API (evidence: `backend/financial_plan_runner.py`)
- Plan runner → Planning workflow: invokes workflow (evidence: `backend/financial_plan_runner.py`)
- Planning workflow → Planning calculations: dispatches stages
- Planning calculations → Plan state: updates state (evidence: `Financial_Planning/Nodes/allocations_nodes.py`)
- Client dashboard → Spouse details: renders (evidence: `components/ClientsDashboard.tsx`)
- Client dashboard → Education planning: renders (evidence: `components/ClientsDashboard.tsx`)
- User → Copilot route: asks questions (evidence: `README.md`)
- Copilot route → LangGraph agent: routes chat (evidence: `app/api/copilotkit/route.ts`)
- LangGraph agent → Azure OpenAI: generates responses (evidence: `README.md`)
- LangGraph agent → Tavily search: searches web (evidence: `README.md`)
- User → Policy upload route: uploads policy PDF (evidence: `app/api/parse-policy-document/route.ts`)
- Policy upload route → OCR service client: summarizes document (evidence: `app/api/parse-policy-document/route.ts`)
- OCR service client → Policy OCR service: posts PDF (evidence: `lib/ocrService.ts`)
- Policy OCR service → PDF processor: processes PDF (evidence: `ocr-service/main.py`)
- User → RSU routes: views market data (evidence: `README.md`)
- RSU routes → FastAPI proxy: forwards request (evidence: `app/api/rsu/market-data/route.ts`)
- FastAPI proxy → RSU market API: calls API (evidence: `backend/rsu_market.py`)
- User → Plan export route: exports plan
- Plan export route → FastAPI proxy: forwards export (evidence: `app/api/financial-plan/ppt/route.ts`)
- Airtable API → PPT migration endpoint: serves migration endpoint (evidence: `backend-airtable/main.py`)
- PPT migration endpoint → PowerPoint deck: builds deck (evidence: `Financial_Planning/PPTX_Migration/endpoint.py`)
