# clive0707/citewise-2 architecture

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

- Interactive diagram: https://gitdiagram.com/clive0707/citewise-2
- Repository: https://github.com/clive0707/citewise-2

## Overview

CiteLabs evaluates how likely a site is to appear in AI-generated answers. A user submits a target URL in the dashboard; the frontend starts a run through the Fastify API, which dispatches work to the Python worker. The evaluation crawls and summarizes the target, infers intent and category, generates queries, discovers competitors, indexes content, and runs RAG simulations to produce scores and recommendations. The backend persists run and event data and exposes progress and analytics to the dashboard. The README documents the end-to-end stages; sampled excerpts do not show every worker implementation detail, so uncertain internal call wiring is omitted.

Main entry points: [`citelabs/cl-backend/src/routes/sandbox.ts`](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/routes/sandbox.ts) (Sandbox Routes), [`citelabs/cl-workers/app/crawl.py`](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/crawl.py) (Target Crawl), [`citelabs/cl-workers/app/sandbox.py`](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py) (Competitor Crawl), [`citelabs/cl-workers/app/vector_store.py`](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/vector_store.py) (Vector Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_launch["Run Launchpad<br/>[index.tsx]"]
  node_dashboard["Run Dashboard<br/>[&#91;runId&#93;.tsx]"]
end

subgraph group_api["Backend API"]
  node_api_server["Fastify API<br/>[server.ts]"]
  node_sandbox_routes["Sandbox Routes<br/>[sandbox.ts]"]
  node_worker_client["Worker Client<br/>[pythonClient.ts]"]
end

subgraph group_evaluation["Evaluation Worker"]
  node_worker_api["Worker API<br/>[main.py]"]
  node_target_crawl["Target Crawl<br/>[crawl.py]"]
  node_intent_analysis["Intent Analysis<br/>[sandbox.py]"]
  node_query_generation["Query Generation<br/>[sandbox.py]"]
  node_competitor_discovery["Competitor Discovery<br/>[sandbox.py]"]
  node_competitor_crawl["Competitor Crawl<br/>[sandbox.py]"]
  node_rag_scoring["RAG and Scoring<br/>[sandbox.py]"]
end

subgraph group_retrieval["Retrieval and Models"]
  node_chunking["Content Chunking<br/>[factory.py]"]
  node_embedding["Text Embeddings<br/>[embeddings.py]"]
  node_vector_store["Vector Store<br/>[vector_store.py]"]
  node_llm["LLM Providers<br/>[llm_provider.py]"]
end

subgraph group_state["Evaluation State"]
  node_state_store[("Run and Event Store<br/>[sandbox.ts]")]
end

node_user(("Analyst"))
node_site(("Target and Competitor Sites"))
node_model_service(("Model Services"))
node_vector_database[("Vector Database")]

node_user -->|"submits URL"| node_launch
node_launch -->|"starts run"| node_api_server
node_api_server -->|"dispatches request"| node_sandbox_routes
node_sandbox_routes -->|"starts evaluation"| node_worker_client
node_worker_client -->|"HTTP request"| node_worker_api
node_worker_api -->|"calls crawl"| node_target_crawl
node_target_crawl -->|"fetches page"| node_site
node_target_crawl -->|"provides content"| node_intent_analysis
node_intent_analysis -->|"provides intent"| node_query_generation
node_query_generation -->|"provides queries"| node_competitor_discovery
node_competitor_discovery -->|"identifies competitors"| node_competitor_crawl
node_competitor_crawl -->|"fetches pages"| node_site
node_competitor_crawl -->|"provides content"| node_chunking
node_chunking -->|"chunks text"| node_embedding
node_embedding -->|"provides vectors"| node_vector_store
node_vector_store -->|"indexes and retrieves"| node_vector_database
node_vector_store -->|"retrieves context"| node_rag_scoring
node_rag_scoring -->|"generates answers"| node_llm
node_llm -->|"requests inference"| node_model_service
node_rag_scoring -->|"reports progress"| node_sandbox_routes
node_sandbox_routes -->|"persists run data"| node_state_store
node_sandbox_routes -->|"serves run results"| node_dashboard
node_dashboard -->|"polls progress"| node_sandbox_routes
node_user -->|"views results"| node_dashboard

click node_launch "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-frontend/pages/index.tsx"
click node_dashboard "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-frontend/pages/%5BrunId%5D.tsx"
click node_api_server "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/server.ts"
click node_sandbox_routes "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/routes/sandbox.ts"
click node_worker_client "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/services/pythonClient.ts"
click node_state_store "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/routes/sandbox.ts"
click node_worker_api "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/main.py"
click node_target_crawl "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/crawl.py"
click node_intent_analysis "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py"
click node_query_generation "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py"
click node_competitor_discovery "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py"
click node_competitor_crawl "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py"
click node_chunking "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/chunkers/factory.py"
click node_embedding "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/embeddings.py"
click node_vector_store "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/vector_store.py"
click node_rag_scoring "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py"
click node_llm "https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/llm_provider.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_launch,node_dashboard toneBlue
class node_api_server,node_sandbox_routes,node_worker_client,node_vector_database toneAmber
class node_worker_api,node_target_crawl,node_intent_analysis,node_query_generation,node_competitor_discovery,node_competitor_crawl,node_rag_scoring toneMint
class node_chunking,node_embedding,node_vector_store,node_llm toneRose
class node_state_store,node_user,node_site,node_model_service toneIndigo
```

## Components

### User Interface

- [Run Launchpad](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-frontend/pages/index.tsx): `citelabs/cl-frontend/pages/index.tsx`
- [Run Dashboard](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-frontend/pages/%5BrunId%5D.tsx): `citelabs/cl-frontend/pages/[runId].tsx`

### Backend API

- [Fastify API](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/server.ts): `citelabs/cl-backend/src/server.ts`
- [Sandbox Routes](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/routes/sandbox.ts): `citelabs/cl-backend/src/routes/sandbox.ts`
- [Worker Client](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/services/pythonClient.ts): `citelabs/cl-backend/src/services/pythonClient.ts`

### Evaluation Worker

- [Worker API](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/main.py): `citelabs/cl-workers/app/main.py`
- [Target Crawl](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/crawl.py): `citelabs/cl-workers/app/crawl.py`
- [Intent Analysis](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py): `citelabs/cl-workers/app/sandbox.py`
- [Query Generation](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py): `citelabs/cl-workers/app/sandbox.py`
- [Competitor Discovery](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py): `citelabs/cl-workers/app/sandbox.py`
- [Competitor Crawl](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py): `citelabs/cl-workers/app/sandbox.py`
- [RAG and Scoring](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/sandbox.py): `citelabs/cl-workers/app/sandbox.py`

### Retrieval and Models

- [Content Chunking](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/chunkers/factory.py): `citelabs/cl-workers/app/chunkers/factory.py`
- [Text Embeddings](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/embeddings.py): `citelabs/cl-workers/app/embeddings.py`
- [Vector Store](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/vector_store.py): `citelabs/cl-workers/app/vector_store.py`
- [LLM Providers](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-workers/app/llm_provider.py): `citelabs/cl-workers/app/llm_provider.py`

### Evaluation State

- [Run and Event Store](https://github.com/clive0707/citewise-2/blob/main/citelabs/cl-backend/src/routes/sandbox.ts): `citelabs/cl-backend/src/routes/sandbox.ts`

### Other components

- **Analyst**
- **Target and Competitor Sites**
- **Model Services**
- **Vector Database**

## Connections

- Analyst → Run Launchpad: submits URL
- Run Launchpad → Fastify API: starts run
- Fastify API → Sandbox Routes: dispatches request
- Sandbox Routes → Worker Client: starts evaluation
- Worker Client → Worker API: HTTP request
- Worker API → Target Crawl: calls crawl
- Target Crawl → Target and Competitor Sites: fetches page
- Target Crawl → Intent Analysis: provides content
- Intent Analysis → Query Generation: provides intent
- Query Generation → Competitor Discovery: provides queries
- Competitor Discovery → Competitor Crawl: identifies competitors
- Competitor Crawl → Target and Competitor Sites: fetches pages
- Competitor Crawl → Content Chunking: provides content
- Content Chunking → Text Embeddings: chunks text
- Text Embeddings → Vector Store: provides vectors
- Vector Store → Vector Database: indexes and retrieves
- Vector Store → RAG and Scoring: retrieves context
- RAG and Scoring → LLM Providers: generates answers
- LLM Providers → Model Services: requests inference
- RAG and Scoring → Sandbox Routes: reports progress
- Sandbox Routes → Run and Event Store: persists run data
- Sandbox Routes → Run Dashboard: serves run results
- Run Dashboard → Sandbox Routes: polls progress
- Analyst → Run Dashboard: views results