# goldlance07/ttula architecture

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

- Interactive diagram: https://gitdiagram.com/goldlance07/ttula
- Repository: https://github.com/goldlance07/ttula

## Overview

TTULA is a terminal-first security reconnaissance workspace with an optional browser console. Operators launch a UI or CLI workflow; the core engine dispatches discovery, URL processing, mesh-status, command-knowledge, and lab-gated authentication tasks through adapters. Tookie and the crawler can feed Uro normalization, while the execution manager provides one-shot processes and persistent PTY sessions. Shared models carry targets, commands, results, and URL collections. README and sampled-source evidence establish the main wiring; some UI and adapter internals were not sampled, so those links are omitted where unverified.

Main entry points: [`ttula/core/engine.py`](https://github.com/goldlance07/ttula/blob/main/ttula/core/engine.py) (TTULA Engine), [`ttula/integrations/uro/adapter.py`](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/uro/adapter.py) (Uro URL Filter), [`ttula/execution/process.py`](https://github.com/goldlance07/ttula/blob/main/ttula/execution/process.py) (Subprocess Runner), [`ttula/ui/streamlit/app.py`](https://github.com/goldlance07/ttula/blob/main/ttula/ui/streamlit/app.py) (Browser Console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator Interfaces"]
  node_cli["CLI Commands<br/>[main.py]"]
  node_tui["Textual Dashboard<br/>[app.py]"]
  node_streamlit["Browser Console<br/>[app.py]"]
  node_home["Home View<br/>[home.py]"]
  node_header["Tool Header<br/>[header.py]"]
  node_badges["Category Badges<br/>[badges.py]"]
end

subgraph group_core["Core Orchestration"]
  node_engine["TTULA Engine<br/>[engine.py]"]
  node_models["Shared Data Models<br/>[models.py]"]
  node_operations["Operation Mapping<br/>[operations.py]"]
  node_toolmeta["Tool Metadata<br/>[tools.py]"]
end

subgraph group_domain["Recon Capabilities"]
  node_crawler["Web Crawler<br/>[adapter.py]"]
  node_tookie["Tookie OSINT<br/>[adapter.py]"]
  node_uro["Uro URL Filter<br/>[adapter.py]"]
  node_arsenal["Arsenal Cheats<br/>[adapter.py]"]
  node_legba["Legba Auth Builder<br/>[adapter.py]"]
  node_tailscale["Tailscale Mesh<br/>[adapter.py]"]
end

subgraph group_runtime["Execution Runtime"]
  node_manager["Execution Manager<br/>[manager.py]"]
  node_process["Subprocess Runner<br/>[process.py]"]
  node_pty["Persistent PTY<br/>[pty.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses dashboard"| node_tui
node_operator -.->|"uses console"| node_streamlit
node_cli -->|"dispatches workflows"| node_engine
node_tui -->|"invokes workflows"| node_engine
node_streamlit -->|"invokes workflows"| node_engine
node_streamlit -->|"renders home"| node_home
node_header -->|"renders badges"| node_badges
node_header -->|"reads metadata"| node_toolmeta
node_badges -->|"reads categories"| node_toolmeta
node_home -->|"renders badges"| node_badges
node_engine -->|"uses models"| node_models
node_engine -->|"uses mappings"| node_operations
node_engine -->|"dispatches crawl"| node_crawler
node_engine -->|"dispatches discovery"| node_tookie
node_engine -->|"dispatches filtering"| node_uro
node_engine -->|"dispatches search"| node_arsenal
node_engine -->|"dispatches auth build"| node_legba
node_engine -->|"requests mesh status"| node_tailscale
node_engine -->|"runs commands"| node_manager
node_engine -->|"normalizes crawl results"| node_uro
node_engine -->|"normalizes OSINT results"| node_uro
node_manager -->|"starts sessions"| node_pty
node_manager -->|"runs one-shot commands"| node_process
node_tailscale -->|"runs CLI calls"| node_process
node_tookie -->|"runs discovery tool"| node_process
node_uro -->|"runs filter tool"| node_process

click node_cli "https://github.com/goldlance07/ttula/blob/main/ttula/cli/main.py"
click node_tui "https://github.com/goldlance07/ttula/blob/main/ttula/ui/tui/app.py"
click node_streamlit "https://github.com/goldlance07/ttula/blob/main/ttula/ui/streamlit/app.py"
click node_home "https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/home.py"
click node_header "https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/header.py"
click node_badges "https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/badges.py"
click node_engine "https://github.com/goldlance07/ttula/blob/main/ttula/core/engine.py"
click node_models "https://github.com/goldlance07/ttula/blob/main/ttula/core/models.py"
click node_operations "https://github.com/goldlance07/ttula/blob/main/ttula/core/operations.py"
click node_toolmeta "https://github.com/goldlance07/ttula/blob/main/ttula/config/tools.py"
click node_crawler "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/crawler/adapter.py"
click node_tookie "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/tookie/adapter.py"
click node_uro "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/uro/adapter.py"
click node_arsenal "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/arsenal/adapter.py"
click node_legba "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/legba/adapter.py"
click node_tailscale "https://github.com/goldlance07/ttula/blob/main/ttula/integrations/tailscale/adapter.py"
click node_manager "https://github.com/goldlance07/ttula/blob/main/ttula/execution/manager.py"
click node_process "https://github.com/goldlance07/ttula/blob/main/ttula/execution/process.py"
click node_pty "https://github.com/goldlance07/ttula/blob/main/ttula/execution/pty.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_tui,node_streamlit,node_home,node_header,node_badges toneBlue
class node_engine,node_models,node_operations,node_toolmeta toneAmber
class node_crawler,node_tookie,node_uro,node_arsenal,node_legba,node_tailscale toneMint
class node_manager,node_process,node_pty toneRose
class node_operator toneIndigo
```

## Components

### Operator Interfaces

- [CLI Commands](https://github.com/goldlance07/ttula/blob/main/ttula/cli/main.py): `ttula/cli/main.py`
- [Textual Dashboard](https://github.com/goldlance07/ttula/blob/main/ttula/ui/tui/app.py): `ttula/ui/tui/app.py`
- [Browser Console](https://github.com/goldlance07/ttula/blob/main/ttula/ui/streamlit/app.py): `ttula/ui/streamlit/app.py`
- [Home View](https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/home.py): `ttula/ui/components/home.py`
- [Tool Header](https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/header.py): `ttula/ui/components/header.py`
- [Category Badges](https://github.com/goldlance07/ttula/blob/main/ttula/ui/components/badges.py): `ttula/ui/components/badges.py`

### Core Orchestration

- [TTULA Engine](https://github.com/goldlance07/ttula/blob/main/ttula/core/engine.py): `ttula/core/engine.py`
- [Shared Data Models](https://github.com/goldlance07/ttula/blob/main/ttula/core/models.py): `ttula/core/models.py`
- [Operation Mapping](https://github.com/goldlance07/ttula/blob/main/ttula/core/operations.py): `ttula/core/operations.py`
- [Tool Metadata](https://github.com/goldlance07/ttula/blob/main/ttula/config/tools.py): `ttula/config/tools.py`

### Recon Capabilities

- [Web Crawler](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/crawler/adapter.py): `ttula/integrations/crawler/adapter.py`
- [Tookie OSINT](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/tookie/adapter.py): `ttula/integrations/tookie/adapter.py`
- [Uro URL Filter](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/uro/adapter.py): `ttula/integrations/uro/adapter.py`
- [Arsenal Cheats](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/arsenal/adapter.py): `ttula/integrations/arsenal/adapter.py`
- [Legba Auth Builder](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/legba/adapter.py): `ttula/integrations/legba/adapter.py`
- [Tailscale Mesh](https://github.com/goldlance07/ttula/blob/main/ttula/integrations/tailscale/adapter.py): `ttula/integrations/tailscale/adapter.py`

### Execution Runtime

- [Execution Manager](https://github.com/goldlance07/ttula/blob/main/ttula/execution/manager.py): `ttula/execution/manager.py`
- [Subprocess Runner](https://github.com/goldlance07/ttula/blob/main/ttula/execution/process.py): `ttula/execution/process.py`
- [Persistent PTY](https://github.com/goldlance07/ttula/blob/main/ttula/execution/pty.py): `ttula/execution/pty.py`

### Other components

- **Operator**

## Connections

- Operator → CLI Commands: runs commands (evidence: `README.md`)
- Operator → Textual Dashboard: uses dashboard (evidence: `README.md`)
- Operator → Browser Console: uses console (evidence: `README.md`)
- CLI Commands → TTULA Engine: dispatches workflows (evidence: `ttula/cli/main.py`)
- Textual Dashboard → TTULA Engine: invokes workflows (evidence: `ttula/ui/tui/app.py`)
- Browser Console → TTULA Engine: invokes workflows (evidence: `ttula/ui/streamlit/app.py`)
- Browser Console → Home View: renders home (evidence: `ttula/ui/streamlit/app.py`)
- Tool Header → Category Badges: renders badges (evidence: `ttula/ui/components/header.py`)
- Tool Header → Tool Metadata: reads metadata (evidence: `ttula/ui/components/header.py`)
- Category Badges → Tool Metadata: reads categories (evidence: `ttula/ui/components/badges.py`)
- Home View → Category Badges: renders badges (evidence: `ttula/ui/components/home.py`)
- TTULA Engine → Shared Data Models: uses models (evidence: `ttula/core/engine.py`)
- TTULA Engine → Operation Mapping: uses mappings (evidence: `ttula/core/engine.py`)
- TTULA Engine → Web Crawler: dispatches crawl (evidence: `ttula/core/engine.py`)
- TTULA Engine → Tookie OSINT: dispatches discovery (evidence: `ttula/core/engine.py`)
- TTULA Engine → Uro URL Filter: dispatches filtering (evidence: `ttula/core/engine.py`)
- TTULA Engine → Arsenal Cheats: dispatches search (evidence: `ttula/core/engine.py`)
- TTULA Engine → Legba Auth Builder: dispatches auth build (evidence: `ttula/core/engine.py`)
- TTULA Engine → Tailscale Mesh: requests mesh status (evidence: `ttula/core/engine.py`)
- TTULA Engine → Execution Manager: runs commands (evidence: `ttula/core/engine.py`)
- TTULA Engine → Uro URL Filter: normalizes crawl results (evidence: `ttula/core/engine.py`)
- TTULA Engine → Uro URL Filter: normalizes OSINT results (evidence: `ttula/core/engine.py`)
- Execution Manager → Persistent PTY: starts sessions (evidence: `ttula/execution/manager.py`)
- Execution Manager → Subprocess Runner: runs one-shot commands (evidence: `README.md`)
- Tailscale Mesh → Subprocess Runner: runs CLI calls (evidence: `ttula/integrations/tailscale/adapter.py`)
- Tookie OSINT → Subprocess Runner: runs discovery tool (evidence: `ttula/integrations/tookie/adapter.py`)
- Uro URL Filter → Subprocess Runner: runs filter tool (evidence: `ttula/integrations/uro/adapter.py`)
