# ammu-yuu/kyther architecture

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

## Overview

Kyther is a plugin-based OSINT aggregation service and CLI. An investigator submits an entity; the API or CLI normalizes it, the orchestrator dispatches compatible analyzers concurrently, and discovered entities are pivoted through a depth-limited scan. Findings form a correlated dossier, which the API enriches with confidence and risk assessment for the workspace or a generated PDF. The README documents additional Reddit, threat-actor, attack-feed, and scan-history capabilities. Several API and frontend excerpts are incomplete, so uncertain internal wiring for those features is omitted.

Main entry points: [`kyther/api.py`](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py) (FastAPI Service), [`kyther/core/registry.py`](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/registry.py) (Plugin Registry), [`kyther/web/index.html`](https://github.com/ammu-yuu/kyther/blob/main/kyther/web/index.html) (Workspace UI), [`kyther/core/orchestrator.py`](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/orchestrator.py) (Pivot Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Investigator Entry"]
  node_web["Workspace UI<br/>[index.html]"]
  node_cli["Command Line<br/>[cli.py]"]
  node_api["FastAPI Service<br/>[api.py]"]
end

subgraph group_engine["Scan Engine"]
  node_entities["Entity Model<br/>[entities.py]"]
  node_orchestrator["Pivot Orchestrator<br/>[orchestrator.py]"]
  node_registry["Plugin Registry<br/>[registry.py]"]
  node_netguard["SSRF Guard<br/>[netguard.py]"]
end

subgraph group_intel["Intelligence Sources"]
  node_username["Username Checks<br/>[username.py]"]
  node_profile["Profile Enrichment<br/>[profile.py]"]
  node_reddit["Reddit OSINT<br/>[reddit.py]"]
  node_email["Email Intel<br/>[email.py]"]
  node_infra["Domain IP Intel<br/>[dns.py]"]
  node_phone["Phone Intel<br/>[phone.py]"]
  node_investigative["Person Company Leads<br/>[search_dorks.py]"]
end

subgraph group_workspace["Results Workspace"]
  node_dossier["Dossier and Risk<br/>[api.py]"]
  node_report["PDF Reports<br/>[report.py]"]
  node_history["Search History<br/>[api.py]"]
  node_threats["Threat Actors and Timeline<br/>[api.py]"]
  node_news["Cyber Attacks Feed<br/>[api.py]"]
  node_redditview["Reddit View<br/>[index.html]"]
end

node_investigator(("Investigator"))
node_internet{{"Public OSINT Sources"}}
node_archives{{"Reddit Archives"}}
node_threatsources{{"Threat Data Sources"}}
node_newssources{{"News Sources"}}

node_investigator -->|"uses workspace"| node_web
node_investigator -->|"runs scans"| node_cli
node_web -->|"requests service"| node_api
node_cli -->|"creates seed"| node_entities
node_cli -->|"runs scan"| node_orchestrator
node_api -->|"accepts entity"| node_entities
node_api -->|"runs scan"| node_orchestrator
node_orchestrator -->|"selects plugins"| node_registry
node_registry -->|"dispatches"| node_username
node_registry -->|"dispatches"| node_profile
node_registry -->|"dispatches"| node_reddit
node_registry -->|"dispatches"| node_email
node_registry -->|"dispatches"| node_infra
node_registry -->|"dispatches"| node_phone
node_registry -->|"dispatches"| node_investigative
node_orchestrator -->|"records findings"| node_entities
node_username -->|"queries sources"| node_internet
node_profile -->|"queries sources"| node_internet
node_email -->|"queries sources"| node_internet
node_infra -->|"queries sources"| node_internet
node_phone -.->|"queries sources"| node_internet
node_reddit -->|"queries archives"| node_archives
node_api -->|"builds and scores"| node_dossier
node_orchestrator -->|"returns scan data"| node_dossier
node_api -->|"generates PDF"| node_report
node_api -->|"serves scan logs"| node_history
node_api -->|"serves threat data"| node_threats
node_api -->|"serves attack feed"| node_news
node_api -->|"serves Reddit data"| node_redditview
node_web -->|"opens saved scans"| node_history
node_web -->|"displays dossiers"| node_threats
node_web -->|"displays feed"| node_news
node_web -->|"displays profiles"| node_redditview
node_threats -->|"fetches threat data"| node_threatsources
node_news -->|"fetches articles"| node_newssources

click node_web "https://github.com/ammu-yuu/kyther/blob/main/kyther/web/index.html"
click node_cli "https://github.com/ammu-yuu/kyther/blob/main/kyther/cli.py"
click node_api "https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py"
click node_entities "https://github.com/ammu-yuu/kyther/blob/main/kyther/core/entities.py"
click node_orchestrator "https://github.com/ammu-yuu/kyther/blob/main/kyther/core/orchestrator.py"
click node_registry "https://github.com/ammu-yuu/kyther/blob/main/kyther/core/registry.py"
click node_netguard "https://github.com/ammu-yuu/kyther/blob/main/kyther/core/netguard.py"
click node_username "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/username.py"
click node_profile "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/profile.py"
click node_reddit "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/reddit.py"
click node_email "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/email.py"
click node_infra "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/dns.py"
click node_phone "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/phone.py"
click node_investigative "https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/search_dorks.py"
click node_dossier "https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py"
click node_report "https://github.com/ammu-yuu/kyther/blob/main/kyther/report.py"
click node_history "https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py"
click node_threats "https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py"
click node_news "https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py"
click node_redditview "https://github.com/ammu-yuu/kyther/blob/main/kyther/web/index.html"

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_web,node_cli,node_api toneBlue
class node_entities,node_orchestrator,node_registry,node_netguard toneAmber
class node_username,node_profile,node_reddit,node_email,node_infra,node_phone,node_investigative toneMint
class node_dossier,node_report,node_history,node_threats,node_news,node_redditview toneRose
class node_investigator,node_internet,node_archives,node_threatsources,node_newssources toneIndigo
```

## Components

### Investigator Entry

- [Workspace UI](https://github.com/ammu-yuu/kyther/blob/main/kyther/web/index.html): `kyther/web/index.html`
- [Command Line](https://github.com/ammu-yuu/kyther/blob/main/kyther/cli.py): `kyther/cli.py`
- [FastAPI Service](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py): `kyther/api.py`

### Scan Engine

- [Entity Model](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/entities.py): `kyther/core/entities.py`
- [Pivot Orchestrator](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/orchestrator.py): `kyther/core/orchestrator.py`
- [Plugin Registry](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/registry.py): `kyther/core/registry.py`
- [SSRF Guard](https://github.com/ammu-yuu/kyther/blob/main/kyther/core/netguard.py): `kyther/core/netguard.py`

### Intelligence Sources

- [Username Checks](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/username.py): `kyther/analyzers/username.py`
- [Profile Enrichment](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/profile.py): `kyther/analyzers/profile.py`
- [Reddit OSINT](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/reddit.py): `kyther/analyzers/reddit.py`
- [Email Intel](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/email.py): `kyther/analyzers/email.py`
- [Domain IP Intel](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/dns.py): `kyther/analyzers/dns.py`
- [Phone Intel](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/phone.py): `kyther/analyzers/phone.py`
- [Person Company Leads](https://github.com/ammu-yuu/kyther/blob/main/kyther/analyzers/search_dorks.py): `kyther/analyzers/search_dorks.py`

### Results Workspace

- [Dossier and Risk](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py): `kyther/api.py`
- [PDF Reports](https://github.com/ammu-yuu/kyther/blob/main/kyther/report.py): `kyther/report.py`
- [Search History](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py): `kyther/api.py`
- [Threat Actors and Timeline](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py): `kyther/api.py`
- [Cyber Attacks Feed](https://github.com/ammu-yuu/kyther/blob/main/kyther/api.py): `kyther/api.py`
- [Reddit View](https://github.com/ammu-yuu/kyther/blob/main/kyther/web/index.html): `kyther/web/index.html`

### Other components

- **Investigator**
- **Public OSINT Sources**
- **Reddit Archives**
- **Threat Data Sources**
- **News Sources**

## Connections

- Investigator → Workspace UI: uses workspace
- Investigator → Command Line: runs scans
- Workspace UI → FastAPI Service: requests service
- Command Line → Entity Model: creates seed
- Command Line → Pivot Orchestrator: runs scan
- FastAPI Service → Entity Model: accepts entity
- FastAPI Service → Pivot Orchestrator: runs scan
- Pivot Orchestrator → Plugin Registry: selects plugins
- Plugin Registry → Username Checks: dispatches
- Plugin Registry → Profile Enrichment: dispatches
- Plugin Registry → Reddit OSINT: dispatches
- Plugin Registry → Email Intel: dispatches
- Plugin Registry → Domain IP Intel: dispatches
- Plugin Registry → Phone Intel: dispatches
- Plugin Registry → Person Company Leads: dispatches
- Pivot Orchestrator → Entity Model: records findings
- Username Checks → Public OSINT Sources: queries sources
- Profile Enrichment → Public OSINT Sources: queries sources
- Email Intel → Public OSINT Sources: queries sources
- Domain IP Intel → Public OSINT Sources: queries sources
- Phone Intel → Public OSINT Sources: queries sources
- Reddit OSINT → Reddit Archives: queries archives
- FastAPI Service → Dossier and Risk: builds and scores
- Pivot Orchestrator → Dossier and Risk: returns scan data
- FastAPI Service → PDF Reports: generates PDF
- FastAPI Service → Search History: serves scan logs
- FastAPI Service → Threat Actors and Timeline: serves threat data
- FastAPI Service → Cyber Attacks Feed: serves attack feed
- FastAPI Service → Reddit View: serves Reddit data
- Workspace UI → Search History: opens saved scans
- Workspace UI → Threat Actors and Timeline: displays dossiers
- Workspace UI → Cyber Attacks Feed: displays feed
- Workspace UI → Reddit View: displays profiles
- Threat Actors and Timeline → Threat Data Sources: fetches threat data
- Cyber Attacks Feed → News Sources: fetches articles