# sarverott/gitrecon architecture

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

- Interactive diagram: https://gitdiagram.com/sarverott/gitrecon
- Repository: https://github.com/sarverott/gitrecon

## Overview

gitrecon collects GitHub and related public-source activity, buffers it for repeatable analysis, and helps users map relationships and detect activity patterns. Its broader capabilities include cloned-repository analysis, history visualizations, content generation, atlas dataset maintenance, and offline text translation. Edges follow documented command workflows and explicit source references; several subsystem internals were not sampled, so uncertain implementation links are omitted.

Main entry points: [`src/gitrecon/cli/collect.py`](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/collect.py) (Collection commands), [`src/gitrecon/sources/github_api.py`](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/sources/github_api.py) (GitHub API client), [`src/gitrecon/cli/__init__.py`](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/__init__.py) (CLI commands), [`src/gitrecon/tui/app.py`](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/tui/app.py) (Interactive menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[__init__.py]"]
  node_menu["Interactive menu<br/>[app.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_collect["Collection and storage"]
  node_collect_commands["Collection commands<br/>[collect.py]"]
  node_github["GitHub API client<br/>[github_api.py]"]
  node_sources["Activity sources"]
  node_links["Link catalog<br/>[links.py]"]
  node_buffer[("Raw activity buffer<br/>[rawbuffer.py]")]
end

subgraph group_recognition["Analysis and mapping"]
  node_models["GitHub entity models<br/>[base.py]"]
  node_labels["Activity labels<br/>[rules.py]"]
  node_timeline["Activity timeline<br/>[timeline.py]"]
  node_mapping["Activity graph<br/>[graph.py]"]
  node_repo_analysis["Repository analysis<br/>[analyze.py]"]
  node_repo_relations["Repository relations<br/>[relations.py]"]
  node_history["History visualizations<br/>[gitgraph.py]"]
  node_contributors["Contributor mapping<br/>[contributors.py]"]
end

subgraph group_content["Content and text"]
  node_digest["Digest summaries<br/>[summarize.py]"]
  node_posts["Draft posts<br/>[posts.py]"]
  node_text["Text utilities<br/>[tokenizer.py]"]
  node_translation["Offline translation<br/>[argos.py]"]
end

subgraph group_extensions["Atlas and integrations"]
  node_atlas["Atlas updates<br/>[update.py]"]
  node_atlas_namespace["Atlas namespaces<br/>[namespace.py]"]
  node_hub["Dataset sync<br/>[huggingface.py]"]
end

node_user(("User"))
node_ollama(("Ollama"))
node_xai(("xAI"))
node_huggingface(("Hugging Face Hub"))

node_user -->|"runs commands"| node_cli
node_user -->|"opens menu"| node_menu
node_menu -->|"launches commands"| node_cli
node_cli -->|"dispatches collection"| node_collect_commands
node_collect_commands -->|"requests GitHub data"| node_github
node_github -->|"uses API settings"| node_config
node_github -->|"calls GitHub API"| node_user
node_collect_commands -->|"collects source data"| node_sources
node_collect_commands -->|"stores activity"| node_buffer
node_collect_commands -->|"harvests links"| node_links
node_user -->|"inspects activity map"| node_mapping
node_user -->|"requests labels"| node_labels
node_labels -->|"uses activity windows"| node_timeline
node_user -->|"analyzes clones"| node_repo_analysis
node_user -->|"finds repository ties"| node_repo_relations
node_user -->|"renders Git history"| node_history
node_user -->|"maps contributors"| node_contributors
node_user -->|"requests summary"| node_digest
node_digest -->|"summarizes locally"| node_ollama
node_user -->|"requests drafts"| node_posts
node_posts -->|"generates content"| node_xai
node_user -->|"runs text tools"| node_text
node_user -->|"translates text"| node_translation
node_user -->|"updates atlas"| node_atlas
node_atlas -->|"updates namespaces"| node_atlas_namespace
node_user -->|"syncs dataset"| node_hub
node_hub -->|"pulls and pushes"| node_huggingface

click node_cli "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/__init__.py"
click node_menu "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/tui/app.py"
click node_config "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/config.py"
click node_collect_commands "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/collect.py"
click node_github "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/sources/github_api.py"
click node_sources "https://github.com/sarverott/gitrecon/tree/master/src/gitrecon/sources"
click node_links "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/sources/links.py"
click node_buffer "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/storage/rawbuffer.py"
click node_models "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/models/base.py"
click node_labels "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/analysis/rules.py"
click node_timeline "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/analysis/timeline.py"
click node_mapping "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/graph.py"
click node_repo_analysis "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/code/analyze.py"
click node_repo_relations "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/code/relations.py"
click node_history "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/gitgraph.py"
click node_contributors "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/contributors.py"
click node_digest "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/digest/summarize.py"
click node_posts "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/digest/posts.py"
click node_text "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/text/tokenizer.py"
click node_translation "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/translate/argos.py"
click node_atlas "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/atlas/update.py"
click node_atlas_namespace "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/atlas/namespace.py"
click node_hub "https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/hub/huggingface.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_cli,node_menu,node_config,node_user toneBlue
class node_collect_commands,node_github,node_sources,node_links,node_buffer toneAmber
class node_models,node_labels,node_timeline,node_mapping,node_repo_analysis,node_repo_relations,node_history,node_contributors toneMint
class node_digest,node_posts,node_text,node_translation toneRose
class node_atlas,node_atlas_namespace,node_hub,node_ollama,node_xai,node_huggingface toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/__init__.py): `src/gitrecon/cli/__init__.py`
- [Interactive menu](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/tui/app.py): `src/gitrecon/tui/app.py`
- [Runtime config](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/config.py): `src/gitrecon/config.py`

### Collection and storage

- [Collection commands](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/cli/collect.py): `src/gitrecon/cli/collect.py`
- [GitHub API client](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/sources/github_api.py): `src/gitrecon/sources/github_api.py`
- [Activity sources](https://github.com/sarverott/gitrecon/tree/master/src/gitrecon/sources): `src/gitrecon/sources`
- [Link catalog](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/sources/links.py): `src/gitrecon/sources/links.py`
- [Raw activity buffer](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/storage/rawbuffer.py): `src/gitrecon/storage/rawbuffer.py`

### Analysis and mapping

- [GitHub entity models](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/models/base.py): `src/gitrecon/models/base.py`
- [Activity labels](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/analysis/rules.py): `src/gitrecon/analysis/rules.py`
- [Activity timeline](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/analysis/timeline.py): `src/gitrecon/analysis/timeline.py`
- [Activity graph](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/graph.py): `src/gitrecon/mapping/graph.py`
- [Repository analysis](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/code/analyze.py): `src/gitrecon/code/analyze.py`
- [Repository relations](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/code/relations.py): `src/gitrecon/code/relations.py`
- [History visualizations](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/gitgraph.py): `src/gitrecon/mapping/gitgraph.py`
- [Contributor mapping](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/mapping/contributors.py): `src/gitrecon/mapping/contributors.py`

### Content and text

- [Digest summaries](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/digest/summarize.py): `src/gitrecon/digest/summarize.py`
- [Draft posts](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/digest/posts.py): `src/gitrecon/digest/posts.py`
- [Text utilities](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/text/tokenizer.py): `src/gitrecon/text/tokenizer.py`
- [Offline translation](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/translate/argos.py): `src/gitrecon/translate/argos.py`

### Atlas and integrations

- [Atlas updates](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/atlas/update.py): `src/gitrecon/atlas/update.py`
- [Atlas namespaces](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/atlas/namespace.py): `src/gitrecon/atlas/namespace.py`
- [Dataset sync](https://github.com/sarverott/gitrecon/blob/master/src/gitrecon/hub/huggingface.py): `src/gitrecon/hub/huggingface.py`

### Other components

- **User**
- **Ollama**
- **xAI**
- **Hugging Face Hub**

## Connections

- User → CLI commands: runs commands
- User → Interactive menu: opens menu
- Interactive menu → CLI commands: launches commands
- CLI commands → Collection commands: dispatches collection
- Collection commands → GitHub API client: requests GitHub data (evidence: `src/gitrecon/cli/collect.py`)
- GitHub API client → Runtime config: uses API settings (evidence: `src/gitrecon/sources/github_api.py`)
- GitHub API client → User: calls GitHub API
- Collection commands → Activity sources: collects source data (evidence: `src/gitrecon/cli/collect.py`)
- Collection commands → Raw activity buffer: stores activity
- Collection commands → Link catalog: harvests links (evidence: `src/gitrecon/cli/collect.py`)
- User → Activity graph: inspects activity map
- User → Activity labels: requests labels
- Activity labels → Activity timeline: uses activity windows (evidence: `src/gitrecon/analysis/rules.py`)
- User → Repository analysis: analyzes clones
- User → Repository relations: finds repository ties
- User → History visualizations: renders Git history
- User → Contributor mapping: maps contributors
- User → Digest summaries: requests summary
- Digest summaries → Ollama: summarizes locally
- User → Draft posts: requests drafts
- Draft posts → xAI: generates content
- User → Text utilities: runs text tools
- User → Offline translation: translates text
- User → Atlas updates: updates atlas
- Atlas updates → Atlas namespaces: updates namespaces
- User → Dataset sync: syncs dataset
- Dataset sync → Hugging Face Hub: pulls and pushes (evidence: `src/gitrecon/hub/huggingface.py`)
