docs/architecture.md

Architecture Documentation

System Overview

Instant SWOT Agent is an AI-powered strategic analysis system that generates comprehensive SWOT analyses for companies with automatic quality improvement through a self-correcting loop.

High-Level Architecture

User Input (Company Name)
         ↓
┌────────────────────────────────────────┐
│           USER INTERFACE               │
│    Streamlit (streamlit_app.py)        │
│    React (frontend/) via FastAPI       │
└────────────────────────────────────────┘
         ↓
┌────────────────────────────────────────┐
│     FastAPI Backend (src/api/app.py)   │
│   Routes: analysis.py, stocks.py       │
└────────────────────────────────────────┘
         ↓
   Workflow Engine (LangGraph)
   src/workflow/graph.py
         ↓
   Node Orchestration
   ↙  ↓  ↓  ↓  ↘
Researcher → Analyzer → Critic → Editor
                 ↘________↗ (loop until score ≥7 or 3 revisions)
         ↓
   Final SWOT Analysis

Directory Structure

src/
├── api/                    # FastAPI backend
│   ├── app.py              # Application factory
│   ├── schemas.py          # Pydantic models
│   └── routes/
│       ├── analysis.py     # Workflow endpoints
│       └── stocks.py       # Stock search endpoint
├── workflow/               # LangGraph workflow
│   ├── graph.py            # Workflow definition
│   └── runner.py           # Execution wrapper
├── nodes/                  # Workflow nodes
├── services/               # Shared services
│   ├── swot_parser.py      # SWOT text parsing
│   ├── confidence.py       # Confidence calculation
│   └── workflow_store.py   # Workflow state management
├── utils/                  # Utilities
└── main.py                 # CLI entry point

Core Components

1. Workflow Engine

Located in src/workflow/graph.py, implements the self-correcting workflow:

• Entry: Researcher node
• Flow: Researcher → Analyzer → Critic → (conditional) Editor
• Exit: Score ≥ 7 OR revision_count ≥ 3

2. Workflow Nodes

Located in src/nodes/:

Node	File	Responsibility
Researcher	researcher.py	Gathers data via MCP servers, summarizes with LLM
Analyzer	analyzer.py	Generates SWOT analysis draft
Critic	critic.py	Evaluates quality (1-10 score) using rubric
Editor	editor.py	Revises draft based on critique

3. MCP Servers

Located in mcp-servers/, providing data aggregation:

Server	Data Source	Output
financials-basket	SEC EDGAR	Financial statements
volatility-basket	Yahoo Finance, FRED	VIX, Beta, IV
macro-basket	FRED	GDP, rates, CPI
valuation-basket	Yahoo Finance, SEC	P/E, P/B, EV/EBITDA
news-basket	Tavily	News articles
sentiment-basket	Finnhub	Sentiment scores

4. State Management

Defined in src/state.py, the workflow state flows through each node:

state = {
    "company_name": str,
    "strategy_focus": str,
    "raw_data": str,
    "draft_report": str,
    "critique": str,
    "score": int,
    "revision_count": int,
    "error": str | None
}

Data Flow

1. Input: User enters company name via Streamlit UI
2. Research: Researcher node queries MCP servers for financial data
3. Analysis: Analyzer generates initial SWOT draft
4. Evaluation: Critic scores draft (1-10) against rubric
5. Improvement: If score < 7 and revisions < 3, Editor revises
6. Output: Final SWOT displayed with quality metrics

Quality Evaluation

The Critic node uses a rubric-based system:

• Completeness (25%): All SWOT sections populated
• Specificity (25%): Concrete, actionable insights with data
• Relevance (25%): Aligned with company context
• Depth (25%): Strategic sophistication

Threshold: Score ≥ 7/10 to pass without revision.

Extending the System

Adding a New Node

1. Create src/nodes/new_node.py:

def new_node(state: dict) -> dict:
    # Process state
    state["new_field"] = result
    return state

2. Register in src/workflow/graph.py:

workflow.add_node("NewNode", RunnableLambda(new_node))
workflow.add_edge("PreviousNode", "NewNode")

Adding a New MCP Server

1. Create directory mcp-servers/new-basket/
2. Implement server with tool registration
3. Update Researcher node to call new server

Observability

• LangSmith: End-to-end workflow tracing (configure via environment variables)
• Logging: Python standard logging at INFO/DEBUG levels

Error Handling

• MCP server failures: Graceful degradation, continue with available data
• LLM failures: Retry with fallback providers
• Quality failures: Maximum 3 revision attempts before accepting result