# nifinet/gtm-brain architecture

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

## Overview

gtm-brain is a small AI outbound system: it collects buying signals, remembers account history, judges which accounts merit action, drafts trigger-grounded outreach, and tracks outcomes to evaluate signal weights and prompt variants. The principal run is orchestrated by `run.py`; delivery is dry-run by default. The graph preserves the documented configuration and prompt-tuning capabilities. Source excerpts show the main calls and persistence behavior; outcome feedback and weight adjustment are capabilities, but their ongoing external wiring is not shown.

Main entry points: [`run.py`](https://github.com/nifinet/gtm-brain/blob/main/run.py) (Run pass), [`brain/act.py`](https://github.com/nifinet/gtm-brain/blob/main/brain/act.py) (Draft outreach), [`brain/judge.py`](https://github.com/nifinet/gtm-brain/blob/main/brain/judge.py) (Judge accounts), [`brain/loop.py`](https://github.com/nifinet/gtm-brain/blob/main/brain/loop.py) (Outcome learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_runner["Run pass<br/>[run.py]"]
  node_config["Runtime config"]
end

subgraph group_brain["Brain stages"]
  node_sensing["Sense signals<br/>[sense.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_judging["Judge accounts<br/>[judge.py]"]
  node_drafting["Draft outreach<br/>[act.py]"]
  node_prompt_loader["Prompt loader<br/>[prompts.py]"]
  node_prompt_files["Reasoning prompts"]
end

subgraph group_memory_learning["Memory and learning"]
  node_memory[("Account history<br/>[memory.py]")]
  node_learning["Outcome learning<br/>[loop.py]"]
end

subgraph group_integration["Adapters and inputs"]
  node_signal_source["Signal source<br/>[signals_stub.py]"]
  node_delivery["Delivery adapter<br/>[delivery_stub.py]"]
end

node_operator(("Operator"))
node_claude["Claude API"]
node_outcome_source(("Outcome reporter"))

node_operator -->|"starts run"| node_runner
node_runner -->|"loads settings"| node_config
node_runner -->|"creates source"| node_signal_source
node_runner -->|"creates sink"| node_delivery
node_runner -->|"calls sense"| node_sensing
node_sensing -->|"fetches signals"| node_signal_source
node_sensing -->|"records signals"| node_memory
node_sensing -->|"validates signals"| node_models
node_runner -->|"judges accounts"| node_judging
node_judging -->|"reads history"| node_memory
node_judging -->|"loads judge prompt"| node_prompt_loader
node_judging -->|"requests judgment"| node_claude
node_runner -->|"acts on verdicts"| node_drafting
node_runner -->|"passes sequences"| node_config
node_drafting -->|"loads draft prompt"| node_prompt_loader
node_drafting -->|"requests draft"| node_claude
node_drafting -->|"sends draft"| node_delivery
node_drafting -->|"records touch"| node_memory
node_prompt_loader -->|"reads prompt files"| node_prompt_files
node_runner -->|"selects variant"| node_learning
node_runner -->|"prints report"| node_learning
node_learning -->|"records outcomes"| node_memory
node_learning -->|"reads outcome stats"| node_memory
node_outcome_source -.->|"reports outcomes"| node_learning
node_config -->|"supplies ICP"| node_judging
node_config -->|"supplies sequences"| node_drafting

click node_runner "https://github.com/nifinet/gtm-brain/blob/main/run.py"
click node_config "https://github.com/nifinet/gtm-brain/tree/main/config"
click node_signal_source "https://github.com/nifinet/gtm-brain/blob/main/adapters/signals_stub.py"
click node_delivery "https://github.com/nifinet/gtm-brain/blob/main/adapters/delivery_stub.py"
click node_sensing "https://github.com/nifinet/gtm-brain/blob/main/brain/sense.py"
click node_models "https://github.com/nifinet/gtm-brain/blob/main/brain/models.py"
click node_judging "https://github.com/nifinet/gtm-brain/blob/main/brain/judge.py"
click node_drafting "https://github.com/nifinet/gtm-brain/blob/main/brain/act.py"
click node_prompt_loader "https://github.com/nifinet/gtm-brain/blob/main/brain/prompts.py"
click node_prompt_files "https://github.com/nifinet/gtm-brain/tree/main/prompts"
click node_memory "https://github.com/nifinet/gtm-brain/blob/main/brain/memory.py"
click node_learning "https://github.com/nifinet/gtm-brain/blob/main/brain/loop.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_runner,node_config toneBlue
class node_sensing,node_models,node_judging,node_drafting,node_prompt_loader,node_prompt_files toneAmber
class node_memory,node_learning,node_claude toneMint
class node_signal_source,node_delivery toneRose
class node_operator,node_outcome_source toneIndigo
```

## Components

### Run orchestration

- [Run pass](https://github.com/nifinet/gtm-brain/blob/main/run.py): `run.py`
- [Runtime config](https://github.com/nifinet/gtm-brain/tree/main/config): `config`

### Brain stages

- [Sense signals](https://github.com/nifinet/gtm-brain/blob/main/brain/sense.py): `brain/sense.py`
- [Domain models](https://github.com/nifinet/gtm-brain/blob/main/brain/models.py): `brain/models.py`
- [Judge accounts](https://github.com/nifinet/gtm-brain/blob/main/brain/judge.py): `brain/judge.py`
- [Draft outreach](https://github.com/nifinet/gtm-brain/blob/main/brain/act.py): `brain/act.py`
- [Prompt loader](https://github.com/nifinet/gtm-brain/blob/main/brain/prompts.py): `brain/prompts.py`
- [Reasoning prompts](https://github.com/nifinet/gtm-brain/tree/main/prompts): `prompts`

### Memory and learning

- [Account history](https://github.com/nifinet/gtm-brain/blob/main/brain/memory.py): `brain/memory.py`
- [Outcome learning](https://github.com/nifinet/gtm-brain/blob/main/brain/loop.py): `brain/loop.py`

### Adapters and inputs

- [Signal source](https://github.com/nifinet/gtm-brain/blob/main/adapters/signals_stub.py): `adapters/signals_stub.py`
- [Delivery adapter](https://github.com/nifinet/gtm-brain/blob/main/adapters/delivery_stub.py): `adapters/delivery_stub.py`

### Other components

- **Operator**
- **Claude API**
- **Outcome reporter**

## Connections

- Operator → Run pass: starts run (evidence: `README.md`)
- Run pass → Runtime config: loads settings (evidence: `run.py`)
- Run pass → Signal source: creates source (evidence: `run.py`)
- Run pass → Delivery adapter: creates sink (evidence: `run.py`)
- Run pass → Sense signals: calls sense (evidence: `run.py`)
- Sense signals → Signal source: fetches signals (evidence: `brain/sense.py`)
- Sense signals → Account history: records signals (evidence: `brain/sense.py`)
- Sense signals → Domain models: validates signals (evidence: `brain/sense.py`)
- Run pass → Judge accounts: judges accounts (evidence: `run.py`)
- Judge accounts → Account history: reads history (evidence: `brain/judge.py`)
- Judge accounts → Prompt loader: loads judge prompt (evidence: `brain/judge.py`)
- Judge accounts → Claude API: requests judgment (evidence: `brain/judge.py`)
- Run pass → Draft outreach: acts on verdicts (evidence: `run.py`)
- Run pass → Runtime config: passes sequences (evidence: `run.py`)
- Draft outreach → Prompt loader: loads draft prompt (evidence: `brain/act.py`)
- Draft outreach → Claude API: requests draft (evidence: `brain/act.py`)
- Draft outreach → Delivery adapter: sends draft (evidence: `brain/act.py`)
- Draft outreach → Account history: records touch (evidence: `brain/act.py`)
- Prompt loader → Reasoning prompts: reads prompt files (evidence: `brain/prompts.py`)
- Run pass → Outcome learning: selects variant (evidence: `run.py`)
- Run pass → Outcome learning: prints report (evidence: `run.py`)
- Outcome learning → Account history: records outcomes (evidence: `brain/loop.py`)
- Outcome learning → Account history: reads outcome stats (evidence: `brain/loop.py`)
- Outcome reporter → Outcome learning: reports outcomes (evidence: `README.md`)
- Runtime config → Judge accounts: supplies ICP
- Runtime config → Draft outreach: supplies sequences
