# niihhhall/subreach architecture

> Architecture diagram of the GitHub repository niihhhall/subreach, 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/niihhhall/subreach
- Repository: https://github.com/niihhhall/subreach

## Overview

Subreach discovers Reddit prospects, qualifies and researches them, drafts personalized replies, checks compliance, and stores approved drafts for human review. The dashboard is a read-only view of leads, the review queue, handoffs, scout results, accounts, and health; sending is a separate backend capability. The README documents Scout and account-warm-up swarm alongside the main workflow. Some connections are based on README descriptions because their implementation was not sampled.

Main entry points: [`reddit_outreach/orchestrator.py`](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/orchestrator.py) (Pipeline Orchestrator), [`reddit_outreach/reddit_client.py`](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/reddit_client.py) (Reddit Access), [`reddit_outreach/llm.py`](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/llm.py) (LLM Adapter), [`reddit_outreach/agents/research.py`](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/research.py) (Thread Research)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Lead Pipeline"]
  node_orchestrator["Pipeline Orchestrator<br/>[orchestrator.py]"]
  node_discovery["Lead Discovery<br/>[discovery.py]"]
  node_qualification["Fit &amp; Intent<br/>[qualification.py]"]
  node_research["Thread Research<br/>[research.py]"]
  node_personalization["Personalization<br/>[personalization.py]"]
  node_compliance["Compliance Check<br/>[compliance.py]"]
end

subgraph group_operations["Safety &amp; Operations"]
  node_scout["Subreddit Scout<br/>[scout.py]"]
  node_swarm["Warm-Up Swarm<br/>[swarm.py]"]
  node_health["Account Health<br/>[health.py]"]
  node_pacing["Rate &amp; Pacing<br/>[pacing.py]"]
  node_sender["Outreach Sender<br/>[sender.py]"]
end

subgraph group_backend["Backend &amp; State"]
  node_reddit_client["Reddit Access<br/>[reddit_client.py]"]
  node_llm["LLM Adapter<br/>[llm.py]"]
  node_store[("Lead &amp; Activity Store<br/>[store.py]")]
  node_api["Read API<br/>[api.py]"]
end

subgraph group_dashboard["Read-Only Dashboard"]
  node_dashboard_app["Dashboard Shell<br/>[App.tsx]"]
  node_dashboard_pages["Dashboard Views"]
  node_dashboard_hooks["Data Hooks"]
  node_dashboard_api["API Client<br/>[api.ts]"]
end

node_operator(("Operator"))
node_reddit(("Reddit"))
node_llm_provider(("LLM Providers"))
node_dashboard_user(("Dashboard User"))

node_operator -->|"runs pipeline"| node_orchestrator
node_orchestrator -->|"runs discovery"| node_discovery
node_discovery -->|"searches posts"| node_reddit_client
node_reddit_client -->|"reads Reddit"| node_reddit
node_orchestrator -->|"qualifies leads"| node_qualification
node_orchestrator -->|"researches threads"| node_research
node_research -->|"reads threads"| node_reddit_client
node_orchestrator -->|"drafts replies"| node_personalization
node_orchestrator -->|"checks drafts"| node_compliance
node_qualification -.->|"requests analysis"| node_llm
node_research -.->|"requests analysis"| node_llm
node_personalization -.->|"requests drafting"| node_llm
node_compliance -.->|"requests review"| node_llm
node_llm -.->|"calls provider"| node_llm_provider
node_orchestrator -->|"persists stages"| node_store
node_orchestrator -->|"runs scout"| node_scout
node_scout -->|"discovers subs"| node_reddit_client
node_scout -->|"stores findings"| node_store
node_orchestrator -->|"runs warm-up"| node_swarm
node_orchestrator -->|"checks health"| node_health
node_orchestrator -->|"dispatches sends"| node_sender
node_sender -->|"checks limits"| node_pacing
node_sender -->|"posts outreach"| node_reddit_client
node_api -->|"reads state"| node_store
node_dashboard_user -->|"views dashboard"| node_dashboard_app
node_dashboard_app -->|"routes views"| node_dashboard_pages
node_dashboard_pages -->|"loads data"| node_dashboard_hooks
node_dashboard_hooks -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"fetches JSON"| node_api
node_dashboard_pages -->|"shows results"| node_dashboard_user

click node_orchestrator "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/orchestrator.py"
click node_discovery "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/discovery.py"
click node_qualification "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/qualification.py"
click node_research "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/research.py"
click node_personalization "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/personalization.py"
click node_compliance "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/compliance.py"
click node_scout "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/scout.py"
click node_swarm "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/swarm.py"
click node_health "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/health.py"
click node_pacing "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/pacing.py"
click node_sender "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/sender.py"
click node_reddit_client "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/reddit_client.py"
click node_llm "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/llm.py"
click node_store "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/store.py"
click node_api "https://github.com/niihhhall/subreach/blob/main/reddit_outreach/api.py"
click node_dashboard_app "https://github.com/niihhhall/subreach/blob/main/dashboard/src/App.tsx"
click node_dashboard_pages "https://github.com/niihhhall/subreach/tree/main/dashboard/src/pages"
click node_dashboard_hooks "https://github.com/niihhhall/subreach/tree/main/dashboard/src/hooks"
click node_dashboard_api "https://github.com/niihhhall/subreach/blob/main/dashboard/src/lib/api.ts"

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_orchestrator,node_discovery,node_qualification,node_research,node_personalization,node_compliance,node_dashboard_user toneBlue
class node_scout,node_swarm,node_health,node_pacing,node_sender toneAmber
class node_reddit_client,node_llm,node_store,node_api toneMint
class node_dashboard_app,node_dashboard_pages,node_dashboard_hooks,node_dashboard_api toneRose
class node_operator,node_reddit,node_llm_provider toneIndigo
```

## Components

### Lead Pipeline

- [Pipeline Orchestrator](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/orchestrator.py): `reddit_outreach/orchestrator.py`
- [Lead Discovery](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/discovery.py): `reddit_outreach/agents/discovery.py`
- [Fit & Intent](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/qualification.py): `reddit_outreach/agents/qualification.py`
- [Thread Research](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/research.py): `reddit_outreach/agents/research.py`
- [Personalization](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/personalization.py): `reddit_outreach/agents/personalization.py`
- [Compliance Check](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/compliance.py): `reddit_outreach/agents/compliance.py`

### Safety & Operations

- [Subreddit Scout](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/agents/scout.py): `reddit_outreach/agents/scout.py`
- [Warm-Up Swarm](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/swarm.py): `reddit_outreach/swarm.py`
- [Account Health](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/health.py): `reddit_outreach/health.py`
- [Rate & Pacing](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/pacing.py): `reddit_outreach/pacing.py`
- [Outreach Sender](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/sender.py): `reddit_outreach/sender.py`

### Backend & State

- [Reddit Access](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/reddit_client.py): `reddit_outreach/reddit_client.py`
- [LLM Adapter](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/llm.py): `reddit_outreach/llm.py`
- [Lead & Activity Store](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/store.py): `reddit_outreach/store.py`
- [Read API](https://github.com/niihhhall/subreach/blob/main/reddit_outreach/api.py): `reddit_outreach/api.py`

### Read-Only Dashboard

- [Dashboard Shell](https://github.com/niihhhall/subreach/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard Views](https://github.com/niihhhall/subreach/tree/main/dashboard/src/pages): `dashboard/src/pages`
- [Data Hooks](https://github.com/niihhhall/subreach/tree/main/dashboard/src/hooks): `dashboard/src/hooks`
- [API Client](https://github.com/niihhhall/subreach/blob/main/dashboard/src/lib/api.ts): `dashboard/src/lib/api.ts`

### Other components

- **Operator**
- **Reddit**
- **LLM Providers**
- **Dashboard User**

## Connections

- Operator → Pipeline Orchestrator: runs pipeline
- Pipeline Orchestrator → Lead Discovery: runs discovery
- Lead Discovery → Reddit Access: searches posts
- Reddit Access → Reddit: reads Reddit
- Pipeline Orchestrator → Fit & Intent: qualifies leads
- Pipeline Orchestrator → Thread Research: researches threads
- Thread Research → Reddit Access: reads threads
- Pipeline Orchestrator → Personalization: drafts replies
- Pipeline Orchestrator → Compliance Check: checks drafts
- Fit & Intent → LLM Adapter: requests analysis
- Thread Research → LLM Adapter: requests analysis
- Personalization → LLM Adapter: requests drafting
- Compliance Check → LLM Adapter: requests review
- LLM Adapter → LLM Providers: calls provider
- Pipeline Orchestrator → Lead & Activity Store: persists stages
- Pipeline Orchestrator → Subreddit Scout: runs scout
- Subreddit Scout → Reddit Access: discovers subs
- Subreddit Scout → Lead & Activity Store: stores findings
- Pipeline Orchestrator → Warm-Up Swarm: runs warm-up
- Pipeline Orchestrator → Account Health: checks health
- Pipeline Orchestrator → Outreach Sender: dispatches sends
- Outreach Sender → Rate & Pacing: checks limits
- Outreach Sender → Reddit Access: posts outreach
- Read API → Lead & Activity Store: reads state
- Dashboard User → Dashboard Shell: views dashboard
- Dashboard Shell → Dashboard Views: routes views
- Dashboard Views → Data Hooks: loads data
- Data Hooks → API Client: requests data
- API Client → Read API: fetches JSON
- Dashboard Views → Dashboard User: shows results