# veinsurelee/thread-scope architecture

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

- Interactive diagram: https://gitdiagram.com/veinsurelee/thread-scope
- Repository: https://github.com/veinsurelee/thread-scope

## Overview

Thread Scope is an MCP service that lets AI clients discover BYR forum structure, retrieve and search forum content, inspect traffic, and query user information. The main workflow is MCP tool invocation → application use case → crawl or local lookup → persistence where applicable → presented result. The README documents the broader domain capabilities; sampled sources confirm the server entry point, traffic-history read path, structure cache behavior, thread crawling, user crawling, and HTTP/session handling. Other documented subsystem connections are shown only at the level supported by the architecture description.

Main entry points: [`src/application/use-case`](https://github.com/veinsurelee/thread-scope/tree/master/src/application/use-case) (Use cases), [`src/crawl/common/page-fetcher.ts`](https://github.com/veinsurelee/thread-scope/blob/master/src/crawl/common/page-fetcher.ts) (Page fetching), [`src/controller/tool`](https://github.com/veinsurelee/thread-scope/tree/master/src/controller/tool) (Tool handlers), [`src/crawl/structure`](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/structure) (Structure crawl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["MCP server<br/>[index.ts]"]
  node_tools["Tool handlers"]
  node_presenters["Result presenters"]
end

subgraph group_application["Application workflows"]
  node_usecases["Use cases"]
  node_models["Domain models"]
  node_algorithms["Forum algorithms"]
end

subgraph group_crawling["Forum data access"]
  node_structure["Structure crawl"]
  node_article["Article crawl"]
  node_thread["Thread crawl"]
  node_search["Search crawl"]
  node_traffic["Traffic crawl"]
  node_users["User crawl"]
end

subgraph group_persistence["Local persistence"]
  node_contentdb[("Content database<br/>[content-db.ts]")]
  node_trafficdb[("Traffic database<br/>[traffic-db.ts]")]
  node_trafficqueue["Traffic write queue<br/>[traffic-queue.ts]"]
  node_structurestore[("Structure snapshot<br/>[structure-store.ts]")]
end

subgraph group_foundation["Shared foundation"]
  node_fetching["Page fetching<br/>[page-fetcher.ts]"]
  node_http["HTTP and session<br/>[http-client.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

node_client(("MCP client"))
node_forum(("BYR forum"))

node_client -->|"sends JSON-RPC"| node_server
node_server -->|"registers tools"| node_tools
node_tools -->|"invokes workflows"| node_usecases
node_tools -->|"formats results"| node_presenters
node_usecases -->|"fetches structure"| node_structure
node_usecases -->|"fetches articles"| node_article
node_usecases -->|"fetches threads"| node_thread
node_usecases -->|"searches content"| node_search
node_usecases -->|"fetches traffic"| node_traffic
node_usecases -->|"fetches users"| node_users
node_usecases -->|"queries history"| node_trafficdb
node_structure -->|"reads and writes"| node_structurestore
node_usecases -->|"reads and writes"| node_contentdb
node_usecases -->|"queues samples"| node_trafficqueue
node_trafficqueue -->|"persists samples"| node_trafficdb
node_structure -->|"fetches pages"| node_fetching
node_article -->|"fetches pages"| node_fetching
node_thread -->|"fetches pages"| node_fetching
node_search -->|"fetches pages"| node_fetching
node_traffic -->|"fetches pages"| node_fetching
node_users -->|"fetches pages"| node_fetching
node_fetching -->|"requests pages"| node_http
node_http -->|"sends HTTP requests"| node_forum
node_auth -->|"manages session"| node_http
node_usecases -->|"uses domain data"| node_models
node_usecases -.->|"aggregates forum data"| node_algorithms

click node_server "https://github.com/veinsurelee/thread-scope/blob/master/src/index.ts"
click node_tools "https://github.com/veinsurelee/thread-scope/tree/master/src/controller/tool"
click node_presenters "https://github.com/veinsurelee/thread-scope/tree/master/src/controller/presenter"
click node_usecases "https://github.com/veinsurelee/thread-scope/tree/master/src/application/use-case"
click node_structure "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/structure"
click node_article "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/article"
click node_thread "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/content"
click node_search "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/search"
click node_traffic "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/traffic"
click node_users "https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/user"
click node_fetching "https://github.com/veinsurelee/thread-scope/blob/master/src/crawl/common/page-fetcher.ts"
click node_http "https://github.com/veinsurelee/thread-scope/blob/master/src/core/http-client.ts"
click node_auth "https://github.com/veinsurelee/thread-scope/blob/master/src/auth/auth.ts"
click node_contentdb "https://github.com/veinsurelee/thread-scope/blob/master/src/storage/content-db.ts"
click node_trafficdb "https://github.com/veinsurelee/thread-scope/blob/master/src/storage/traffic-db.ts"
click node_trafficqueue "https://github.com/veinsurelee/thread-scope/blob/master/src/storage/traffic-queue.ts"
click node_structurestore "https://github.com/veinsurelee/thread-scope/blob/master/src/storage/structure-store.ts"
click node_models "https://github.com/veinsurelee/thread-scope/tree/master/src/model"
click node_algorithms "https://github.com/veinsurelee/thread-scope/tree/master/src/model/algorithm/forum"

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_presenters,node_client toneBlue
class node_usecases,node_models,node_algorithms toneAmber
class node_structure,node_article,node_thread,node_search,node_traffic,node_users toneMint
class node_contentdb,node_trafficdb,node_trafficqueue,node_structurestore toneRose
class node_fetching,node_http,node_auth,node_forum toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/veinsurelee/thread-scope/blob/master/src/index.ts): `src/index.ts`
- [Tool handlers](https://github.com/veinsurelee/thread-scope/tree/master/src/controller/tool): `src/controller/tool`
- [Result presenters](https://github.com/veinsurelee/thread-scope/tree/master/src/controller/presenter): `src/controller/presenter`

### Application workflows

- [Use cases](https://github.com/veinsurelee/thread-scope/tree/master/src/application/use-case): `src/application/use-case`
- [Domain models](https://github.com/veinsurelee/thread-scope/tree/master/src/model): `src/model`
- [Forum algorithms](https://github.com/veinsurelee/thread-scope/tree/master/src/model/algorithm/forum): `src/model/algorithm/forum`

### Forum data access

- [Structure crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/structure): `src/crawl/structure`
- [Article crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/article): `src/crawl/article`
- [Thread crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/content): `src/crawl/content`
- [Search crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/search): `src/crawl/search`
- [Traffic crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/traffic): `src/crawl/traffic`
- [User crawl](https://github.com/veinsurelee/thread-scope/tree/master/src/crawl/user): `src/crawl/user`

### Local persistence

- [Content database](https://github.com/veinsurelee/thread-scope/blob/master/src/storage/content-db.ts): `src/storage/content-db.ts`
- [Traffic database](https://github.com/veinsurelee/thread-scope/blob/master/src/storage/traffic-db.ts): `src/storage/traffic-db.ts`
- [Traffic write queue](https://github.com/veinsurelee/thread-scope/blob/master/src/storage/traffic-queue.ts): `src/storage/traffic-queue.ts`
- [Structure snapshot](https://github.com/veinsurelee/thread-scope/blob/master/src/storage/structure-store.ts): `src/storage/structure-store.ts`

### Shared foundation

- [Page fetching](https://github.com/veinsurelee/thread-scope/blob/master/src/crawl/common/page-fetcher.ts): `src/crawl/common/page-fetcher.ts`
- [HTTP and session](https://github.com/veinsurelee/thread-scope/blob/master/src/core/http-client.ts): `src/core/http-client.ts`
- [Authentication](https://github.com/veinsurelee/thread-scope/blob/master/src/auth/auth.ts): `src/auth/auth.ts`

### Other components

- **MCP client**
- **BYR forum**

## Connections

- MCP client → MCP server: sends JSON-RPC
- MCP server → Tool handlers: registers tools
- Tool handlers → Use cases: invokes workflows
- Tool handlers → Result presenters: formats results
- Use cases → Structure crawl: fetches structure
- Use cases → Article crawl: fetches articles
- Use cases → Thread crawl: fetches threads
- Use cases → Search crawl: searches content
- Use cases → Traffic crawl: fetches traffic
- Use cases → User crawl: fetches users
- Use cases → Traffic database: queries history
- Structure crawl → Structure snapshot: reads and writes
- Use cases → Content database: reads and writes
- Use cases → Traffic write queue: queues samples
- Traffic write queue → Traffic database: persists samples
- Structure crawl → Page fetching: fetches pages
- Article crawl → Page fetching: fetches pages
- Thread crawl → Page fetching: fetches pages
- Search crawl → Page fetching: fetches pages
- Traffic crawl → Page fetching: fetches pages
- User crawl → Page fetching: fetches pages
- Page fetching → HTTP and session: requests pages
- HTTP and session → BYR forum: sends HTTP requests
- Authentication → HTTP and session: manages session
- Use cases → Domain models: uses domain data
- Use cases → Forum algorithms: aggregates forum data