# adityaa2404/pict-live-mcp architecture

> Architecture diagram of the GitHub repository adityaa2404/pict-live-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adityaa2404/pict-live-mcp
- Repository: https://github.com/adityaa2404/pict-live-mcp

## Overview

PICT Live MCP Server exposes live interview discovery and research tools to MCP clients; its main path runs from stdio tool calls through crawling, extraction, validation, indexing, and search or analysis. It also provides a separate Placed-27 site-crawling capability. The README documents the major workflows, while excerpts show selected call relationships; unsampled tool and graph internals are represented at their exact directory paths, and uncertain links are omitted.

Main entry points: [`app/tools/mcp_tools.py`](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/tools/mcp_tools.py) (MCP tools), [`app/services/live_client.py`](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/live_client.py) (PICT live client), [`app/agent/placed27_graph.py`](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/placed27_graph.py) (Placed-27 crawl graph), [`app/browser/crawl4ai_runtime.py`](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/browser/crawl4ai_runtime.py) (HTTP and browser runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_server["MCP server<br/>[main.py]"]
  node_tools["MCP tools<br/>[mcp_tools.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_pict["PICT live data"]
  node_live["PICT live client<br/>[live_client.py]"]
  node_pict_graph["PICT crawl graph<br/>[pict_live_graph.py]"]
  node_frontier[("Crawl frontier<br/>[crawl_frontier.py]")]
  node_source_index[("Source index<br/>[source_index.py]")]
  node_cache[("TTL cache<br/>[manager.py]")]
end

subgraph group_crawl["Crawling and parsing"]
  node_navigation["Page navigation<br/>[navigation.py]"]
  node_browser["HTTP and browser runtime"]
  node_extractor["Interview extractor<br/>[extractor.py]"]
  node_schemas["Validated records<br/>[schemas.py]"]
end

subgraph group_research["Research tools"]
  node_search["Interview search<br/>[search.py]"]
  node_compare["Company comparison<br/>[compare.py]"]
  node_summarizer["Grounded summaries<br/>[summarizer.py]"]
end

subgraph group_placed["Placed-27 crawling"]
  node_placed_client["Placed-27 client<br/>[placed27_client.py]"]
  node_placed_graph["Placed-27 crawl graph<br/>[placed27_graph.py]"]
  node_site_extractor["Site page extractor<br/>[site_extractor.py]"]
  node_local_llm["Local LLM enrichment<br/>[local_llm.py]"]
end

node_client(("MCP client"))
node_pict_site(("pict.live"))
node_placed_site(("Placed-27 site"))

node_client -->|"sends MCP"| node_server
node_server -->|"loads tools"| node_tools
node_tools -->|"calls"| node_live
node_tools -->|"searches"| node_search
node_tools -->|"compares"| node_compare
node_tools -->|"summarizes"| node_summarizer
node_tools -->|"calls"| node_placed_client
node_live -->|"runs crawl"| node_pict_graph
node_live -->|"reads and writes"| node_cache
node_live -->|"indexes records"| node_source_index
node_live -->|"fetches pages"| node_navigation
node_pict_graph -->|"queues URLs"| node_frontier
node_pict_graph -->|"parses pages"| node_extractor
node_navigation -->|"fetches through"| node_browser
node_browser -->|"requests pages"| node_pict_site
node_extractor -->|"validates records"| node_schemas
node_search -->|"returns records"| node_schemas
node_compare -->|"uses records"| node_schemas
node_summarizer -->|"uses records"| node_schemas
node_tools -->|"searches index"| node_source_index
node_placed_client -->|"runs crawl"| node_placed_graph
node_placed_graph -->|"fetches pages"| node_browser
node_placed_graph -->|"extracts pages"| node_site_extractor
node_placed_graph -->|"enriches pages"| node_local_llm
node_browser -.->|"requests pages"| node_placed_site

click node_server "https://github.com/adityaa2404/pict-live-mcp/blob/main/main.py"
click node_tools "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/tools/mcp_tools.py"
click node_settings "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/config/settings.py"
click node_live "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/live_client.py"
click node_pict_graph "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/pict_live_graph.py"
click node_frontier "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/crawl_frontier.py"
click node_source_index "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/source_index.py"
click node_cache "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/cache/manager.py"
click node_navigation "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/browser/navigation.py"
click node_browser "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/browser/crawl4ai_runtime.py"
click node_extractor "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/parser/extractor.py"
click node_schemas "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/models/schemas.py"
click node_search "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/search.py"
click node_compare "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/compare.py"
click node_summarizer "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/summarizer.py"
click node_placed_client "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/placed27_client.py"
click node_placed_graph "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/placed27_graph.py"
click node_site_extractor "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/parser/site_extractor.py"
click node_local_llm "https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/local_llm.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_server,node_tools,node_settings,node_client toneBlue
class node_live,node_pict_graph,node_frontier,node_source_index,node_cache toneAmber
class node_navigation,node_browser,node_extractor,node_schemas toneMint
class node_search,node_compare,node_summarizer toneRose
class node_placed_client,node_placed_graph,node_site_extractor,node_local_llm,node_pict_site,node_placed_site toneIndigo
```

## Components

### MCP runtime

- [MCP server](https://github.com/adityaa2404/pict-live-mcp/blob/main/main.py): `main.py`
- [MCP tools](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/tools/mcp_tools.py): `app/tools/mcp_tools.py`
- [Runtime settings](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/config/settings.py): `app/config/settings.py`

### PICT live data

- [PICT live client](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/live_client.py): `app/services/live_client.py`
- [PICT crawl graph](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/pict_live_graph.py): `app/agent/pict_live_graph.py`
- [Crawl frontier](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/crawl_frontier.py): `app/crawl_frontier.py`
- [Source index](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/source_index.py): `app/source_index.py`
- [TTL cache](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/cache/manager.py): `app/cache/manager.py`

### Crawling and parsing

- [Page navigation](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/browser/navigation.py): `app/browser/navigation.py`
- [HTTP and browser runtime](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/browser/crawl4ai_runtime.py): `app/browser/crawl4ai_runtime.py`
- [Interview extractor](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/parser/extractor.py): `app/parser/extractor.py`
- [Validated records](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/models/schemas.py): `app/models/schemas.py`

### Research tools

- [Interview search](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/search.py): `app/services/search.py`
- [Company comparison](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/compare.py): `app/services/compare.py`
- [Grounded summaries](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/summarizer.py): `app/services/summarizer.py`

### Placed-27 crawling

- [Placed-27 client](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/services/placed27_client.py): `app/services/placed27_client.py`
- [Placed-27 crawl graph](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/placed27_graph.py): `app/agent/placed27_graph.py`
- [Site page extractor](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/parser/site_extractor.py): `app/parser/site_extractor.py`
- [Local LLM enrichment](https://github.com/adityaa2404/pict-live-mcp/blob/main/app/agent/local_llm.py): `app/agent/local_llm.py`

### Other components

- **MCP client**
- **pict.live**
- **Placed-27 site**

## Connections

- MCP client → MCP server: sends MCP (evidence: `README.md`)
- MCP server → MCP tools: loads tools (evidence: `main.py`)
- MCP tools → PICT live client: calls (evidence: `app/tools/mcp_tools.py`)
- MCP tools → Interview search: searches (evidence: `app/tools/mcp_tools.py`)
- MCP tools → Company comparison: compares (evidence: `app/tools/mcp_tools.py`)
- MCP tools → Grounded summaries: summarizes (evidence: `app/tools/mcp_tools.py`)
- MCP tools → Placed-27 client: calls (evidence: `app/tools/mcp_tools.py`)
- PICT live client → PICT crawl graph: runs crawl (evidence: `app/services/live_client.py`)
- PICT live client → TTL cache: reads and writes (evidence: `app/services/live_client.py`)
- PICT live client → Source index: indexes records (evidence: `app/services/live_client.py`)
- PICT live client → Page navigation: fetches pages (evidence: `README.md`)
- PICT crawl graph → Crawl frontier: queues URLs (evidence: `app/agent/pict_live_graph.py`)
- PICT crawl graph → Interview extractor: parses pages (evidence: `app/agent/pict_live_graph.py`)
- Page navigation → HTTP and browser runtime: fetches through (evidence: `app/browser/navigation.py`)
- HTTP and browser runtime → pict.live: requests pages (evidence: `README.md`)
- Interview extractor → Validated records: validates records (evidence: `app/parser/extractor.py`)
- Interview search → Validated records: returns records (evidence: `app/services/search.py`)
- Company comparison → Validated records: uses records (evidence: `app/services/compare.py`)
- Grounded summaries → Validated records: uses records (evidence: `app/services/summarizer.py`)
- MCP tools → Source index: searches index (evidence: `app/tools/mcp_tools.py`)
- Placed-27 client → Placed-27 crawl graph: runs crawl (evidence: `app/services/placed27_client.py`)
- Placed-27 crawl graph → HTTP and browser runtime: fetches pages (evidence: `app/agent/placed27_graph.py`)
- Placed-27 crawl graph → Site page extractor: extracts pages (evidence: `app/agent/placed27_graph.py`)
- Placed-27 crawl graph → Local LLM enrichment: enriches pages (evidence: `app/agent/placed27_graph.py`)
- HTTP and browser runtime → Placed-27 site: requests pages