# david01px2018/mcp-hackathon architecture

> Architecture diagram of the GitHub repository david01px2018/mcp-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/david01px2018/mcp-hackathon
- Repository: https://github.com/david01px2018/mcp-hackathon

## Overview

##### Project type and purpose
- This is a full-stack analytics application consisting of:
- A React/Next.js frontend (under `frontend/`)
- A Python FastAPI backend (`app.py`)
- Vector databases (Pinecone) and LLM services (OpenAI)
- Ingestion script (`import_data.py`) to populate Pinecone

##### File structure
- Top level:
- `app.py` – the FastAPI server exposing `/` and `/chat` endpoints
- `import_data.py` – CLI script to create/populate Pinecone indexes
- `.env` & `requirements.txt` – backend config
- `frontend/` – Next.js app directory with `app/`, `components/`, `hooks/`, `lib/`, config files (Tailwind, PostCSS, tsconfig)
- Notice patterns:
- Frontend is organized with UI component library and custom hooks
- Backend separates ingestion (import_data) from runtime API (app.py)

##### README for architectural insights
- Agents: User Researcher, Market Analyst, Competitor Analyst, Strategic Advisor, Orchestrator
- External services: OpenAI API, Pinecone (with two indexes)
- Data flow: User query → Orchestrator → Agent(s) → Pinecone/OpenAI → Aggregate → JSON response

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Frontend (React/Next.js)" 
        direction TB
        Browser["Browser / React UI"]:::ui
        NextjsServer["Next.js Server (port 3000)"]:::ui
        Components["UI Components"]:::ui
        Hooks["Custom Hooks"]:::ui
        APIUtils["API & Utilities"]:::ui
        Configs["Config Files"]:::ui
    end

    %% Application Layer
    subgraph "Backend (FastAPI)" 
        direction TB
        FastAPI["FastAPI API (port 8000)"]:::backend
        AppPy["app.py"]:::backend
        Env[".env"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% Agent Layer
    subgraph "Orchestrator & Agents" 
        direction TB
        Orchestrator["Orchestrator Agent"]:::backend
        UserResearch["User Researcher Agent"]:::backend
        MarketAnalyst["Market Analyst Agent"]:::backend
        CompetitorAnalyst["Competitor Analyst Agent"]:::backend
        StrategicAdvisor["Strategic Advisor Agent"]:::backend
    end

    %% Data Layer
    subgraph "Data Stores" 
        direction TB
        Pinecone1["reddit-reviews Index"]:::data
        Pinecone2["perplexity-research Index"]:::data
        OpenAI["OpenAI API"]:::external
    end

    %% Ingestion Workflow
    ImportScript["import_data.py"]:::script

    %% Connections
    Browser -->|"HTTP/WebSocket"| NextjsServer
    NextjsServer -->|"POST /chat, GET /"| FastAPI
    FastAPI -->|"route query"| Orchestrator
    Orchestrator -->|"delegates"| UserResearch
    Orchestrator -->|"delegates"| MarketAnalyst
    Orchestrator -->|"delegates"| CompetitorAnalyst
    Orchestrator -->|"delegates"| StrategicAdvisor
    UserResearch -->|"embedding lookup"| Pinecone1
    MarketAnalyst -->|"embedding lookup"| Pinecone1
    CompetitorAnalyst -->|"embedding lookup"| Pinecone2
    StrategicAdvisor -->|"LLM calls"| OpenAI
    ImportScript -.->|"initial load"| Pinecone1
    ImportScript -.->|"initial load"| Pinecone2
    FastAPI -->|"calls OpenAI"| OpenAI

    %% Sub-connections in Frontend
    Browser --> Components
    Browser --> Hooks
    Browser --> APIUtils
    Browser --> Configs

    %% Click Events
    click Components "https://github.com/david01px2018/mcp-hackathon/tree/master/frontend/components/"
    click Hooks "https://github.com/david01px2018/mcp-hackathon/tree/master/frontend/hooks/"
    click APIUtils "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/lib/api.ts"
    click APIUtils "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/lib/utils.ts"
    click Configs "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/next.config.mjs"
    click Configs "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/tailwind.config.ts"
    click Configs "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/tsconfig.json"
    click Configs "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/postcss.config.mjs"
    click NextjsServer "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/package.json"
    click NextjsServer "https://github.com/david01px2018/mcp-hackathon/blob/master/frontend/pnpm-lock.yaml"
    click AppPy "https://github.com/david01px2018/mcp-hackathon/blob/master/app.py"
    click Env "https://github.com/david01px2018/mcp-hackathon/blob/master/.env"
    click Requirements "https://github.com/david01px2018/mcp-hackathon/blob/master/requirements.txt"
    click ImportScript "https://github.com/david01px2018/mcp-hackathon/blob/master/import_data.py"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000
    classDef backend fill:#d4edda,stroke:#28a745,color:#000
    classDef data fill:#fff3cd,stroke:#ffcc00,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef script fill:#f8d7da,stroke:#dc3545,color:#000
```
