param20h/ai-investment-planner

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.