# param20h/ai-investment-planner architecture

> Architecture diagram of the GitHub repository param20h/ai-investment-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/param20h/ai-investment-planner
- Repository: https://github.com/param20h/ai-investment-planner

## Overview

1. This repository is a single Next.js App Router application, not a multi-service backend. The architecture is centered on one user-facing dashboard page plus one server API endpoint that executes the research workflow.

2. The presentation layer lives under `src/app`. `src/app/page.tsx` is the main entry screen where a user enters a company name and views the research result. `src/app/layout.tsx` provides the shared app shell, and `src/app/globals.css` holds the global styling for the premium dashboard look described in the README.

3. The client-to-server boundary is the API route at `src/app/api/research/route.ts`. That endpoint is the main orchestration entrypoint: it receives the company name from the UI, runs the research pipeline, and streams intermediate progress back to the browser.

4. The core business logic is isolated in `src/lib/agent.ts`. This is where the LangGraph-based investment research agent is defined, including the 3-node workflow: research, analyze, and decide. Keeping this logic in `src/lib` separates agent orchestration from the React UI and route handler.

5. The research node is the external-data ingestion layer. It resolves a company name into a ticker and gathers fundamentals plus sentiment/news data from third-party services, primarily FMP for financials and Tavily for search/news. The README also notes a Gemini-based fallback path when those data sources are unavailable.

6. The analyze node is the structured synthesis layer. It takes the raw research output and uses Google Gemini to extract a bounded set of investment signals such as sentiment summary, growth trends, key risks, and competitive advantages. This stage converts unstructured source material into a compact decision-ready state.

7. The decide node is the final reasoning boundary. It does not inspect the original raw articles or search text; it only consumes the structured signals from the analyze step. Its output is the final thesis: Invest, Pass, or Watch, along with confidence and pros/cons. That restriction is a major architectural control against hallucinated claims.

8. Data flows in one direction: user input in the page, request to `/api/research`, execution through the graph in `agent.ts`, then streamed state updates back to the page. The README’s NDJSON streaming means the UI can show step-by-step progress rather than waiting for a single final payload.

9. The repo includes a lightweight visualization layer in the UI, with custom SVG charts rather than a third-party charting library. Architecturally, that matters because chart rendering is kept client-side and compile-safe inside the Next.js/React 19 environment, while the financial data itself is still sourced on the server.

10. The runtime and dependency boundary is a modern TypeScript/Next.js stack with Tailwind/PostCSS for styling and ESLint/tsconfig for code quality and compilation. The only materially important external services are Google Gemini, Tavily, and optionally FMP; the rest of the repo is focused on presentation and orchestration rather than infrastructure.

11. `public/` is the static asset boundary for any images or icons used by the interface. Everything else is application code, so there is no separate database, job queue, or worker process visible in this repository.

12. For an architecture diagram, the key boxes are: Browser UI, Next.js page/layout layer, `/api/research` streaming endpoint, LangGraph agent orchestration, third-party research services, and Gemini reasoning. The important arrows are request/response from UI to API, streamed progress back to UI, and outbound calls from the agent to the external data/LLM providers.

Main entry points: [`src/app/page.tsx`](https://github.com/param20h/ai-investment-planner/blob/main/src/app/page.tsx) (Dashboard), [`src/lib/agent.ts`](https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts) (Agent Graph), [`src/app/api/research/route.ts`](https://github.com/param20h/ai-investment-planner/blob/main/src/app/api/research/route.ts) (Research API), [`src/app/layout.tsx`](https://github.com/param20h/ai-investment-planner/blob/main/src/app/layout.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser UI<br/>client"))
  node_page["Dashboard<br/>page<br/>[page.tsx]"]
  node_layout["App Shell<br/>layout<br/>[layout.tsx]"]
  node_styles["Global CSS<br/>styling<br/>[globals.css]"]
  node_charts["SVG Charts<br/>visualization"]
  node_static["Public Assets"]
end

subgraph group_api["API"]
  node_research_api["Research API<br/>route<br/>[route.ts]"]
  node_ndjson["Streamed State"]
end

subgraph group_core["Core logic"]
  node_agent{{"Agent Graph<br/>orchestrator<br/>[agent.ts]"}}
  node_research_node["Research<br/>workflow step<br/>[agent.ts]"]
  node_analyze_node["Analyze<br/>workflow step<br/>[agent.ts]"]
  node_decide_node["Decide<br/>workflow step<br/>[agent.ts]"]
end

subgraph group_external["External services"]
  node_gemini(("Gemini<br/>llm"))
  node_tavily(("Tavily<br/>search api"))
  node_fmp(("FMP<br/>market data api"))
end

node_browser -->|"uses"| node_page
node_page -->|"rendered in"| node_layout
node_layout -->|"loads"| node_styles
node_page -->|"request"| node_research_api
node_research_api -->|"streams"| node_ndjson
node_ndjson -->|"updates"| node_page
node_page -->|"renders"| node_charts
node_page -->|"uses"| node_static
node_research_api -->|"delegates"| node_agent
node_agent -->|"executes"| node_research_node
node_agent -->|"executes"| node_analyze_node
node_agent -->|"executes"| node_decide_node
node_research_node -->|"fetches"| node_fmp
node_research_node -->|"searches"| node_tavily
node_research_node -.->|"fallback"| node_gemini
node_analyze_node -->|"analyzes with"| node_gemini
node_decide_node -->|"reasons with"| node_gemini

click node_page "https://github.com/param20h/ai-investment-planner/blob/main/src/app/page.tsx"
click node_layout "https://github.com/param20h/ai-investment-planner/blob/main/src/app/layout.tsx"
click node_styles "https://github.com/param20h/ai-investment-planner/blob/main/src/app/globals.css"
click node_research_api "https://github.com/param20h/ai-investment-planner/blob/main/src/app/api/research/route.ts"
click node_agent "https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts"
click node_research_node "https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts"
click node_analyze_node "https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts"
click node_decide_node "https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts"
click node_static "https://github.com/param20h/ai-investment-planner/tree/main/public"

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_browser,node_page,node_layout,node_styles,node_charts,node_static toneBlue
class node_research_api,node_ndjson toneAmber
class node_agent,node_research_node,node_analyze_node,node_decide_node toneMint
class node_gemini,node_tavily,node_fmp toneRose
```

## Components

### Frontend

User-facing Next.js app and client-side rendering

- **Browser UI**: client · Company input and research results view
- [Dashboard](https://github.com/param20h/ai-investment-planner/blob/main/src/app/page.tsx): page · Main entry screen for company research · `src/app/page.tsx`
- [App Shell](https://github.com/param20h/ai-investment-planner/blob/main/src/app/layout.tsx): layout · Shared application frame and metadata · `src/app/layout.tsx`
- [Global CSS](https://github.com/param20h/ai-investment-planner/blob/main/src/app/globals.css): styling · Premium dashboard styling and theme layer · `src/app/globals.css`
- **SVG Charts**: visualization · Client-side custom chart rendering
- [Public Assets](https://github.com/param20h/ai-investment-planner/tree/main/public): assets · Static images and icons for the interface · `public`

### API

Server route that orchestrates research requests

- [Research API](https://github.com/param20h/ai-investment-planner/blob/main/src/app/api/research/route.ts): route · Streaming endpoint for research requests · `src/app/api/research/route.ts`
- **Streamed State**: stream · Intermediate progress events back to the browser

### Core logic

LangGraph agent and decision workflow

- [Agent Graph](https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts): orchestrator · LangGraph investment research workflow · `src/lib/agent.ts`
- [Research](https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts): workflow step · Resolves company and gathers financial and sentiment data · `src/lib/agent.ts`
- [Analyze](https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts): workflow step · Synthesizes signals into structured investment factors · `src/lib/agent.ts`
- [Decide](https://github.com/param20h/ai-investment-planner/blob/main/src/lib/agent.ts): workflow step · Produces final thesis from structured signals only · `src/lib/agent.ts`

### External services

Third-party data and reasoning providers

- **Gemini**: llm · Used for synthesis and fallback reasoning
- **Tavily**: search api · Search and news ingestion source
- **FMP**: market data api · Financial fundamentals and ticker lookup source

## Connections

- Browser UI → Dashboard: uses · User interacts with the dashboard page
- Dashboard → App Shell: rendered in · Page is hosted inside the shared app shell
- App Shell → Global CSS: loads · Global styling shapes the app shell and page
- Dashboard → Research API: request · Submits company name to the research endpoint
- Research API → Streamed State: streams · Emits incremental progress and final state
- Streamed State → Dashboard: updates · Progressively updates the UI
- Dashboard → SVG Charts: renders · Shows the research output with custom charts
- Dashboard → Public Assets: uses · Loads icons or other static interface assets
- Research API → Agent Graph: delegates · Hands orchestration to the LangGraph agent
- Agent Graph → Research: executes · First workflow stage
- Agent Graph → Analyze: executes · Second workflow stage
- Agent Graph → Decide: executes · Final workflow stage
- Research → FMP: fetches · Looks up ticker and fundamentals
- Research → Tavily: searches · Collects news and sentiment context
- Research → Gemini: fallback · Uses Gemini when primary data sources are unavailable
- Analyze → Gemini: analyzes with · Extracts bounded investment signals
- Decide → Gemini: reasons with · Consumes only structured signals for the thesis