# b-3llum/tars architecture

> Architecture diagram of the GitHub repository b-3llum/tars, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b-3llum/tars
- Repository: https://github.com/b-3llum/tars

## Overview

TARS is an iOS cybersecurity command assistant backed by a FastAPI server. Operators send chat or voice-derived requests, receive a structured plan, and may confirm sensitive actions before execution; results return to chat with optional speech output. The README describes local/Claude routing, while the sampled decision engine routes only through Ollama, so no Claude dispatch edge is shown. The repository also documents kerb-map guidance, whitelisted scans, system and log queries, and configured-host SSH. Some router, security, configuration, and audit wiring is based on README descriptions where implementation excerpts were not provided.

Main entry points: [`server/router.py`](https://github.com/b-3llum/tars/blob/main/server/router.py) (API Router), [`server/action_engine.py`](https://github.com/b-3llum/tars/blob/main/server/action_engine.py) (Action Engine), [`ios/Tars/Network/NetworkManager.swift`](https://github.com/b-3llum/tars/blob/main/ios/Tars/Network/NetworkManager.swift) (Network Manager), [`ios/Tars/Views/ChatView.swift`](https://github.com/b-3llum/tars/blob/main/ios/Tars/Views/ChatView.swift) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ios["iOS Client"]
  node_chat["Chat UI<br/>[ChatView.swift]"]
  node_viewmodel["Chat ViewModel"]
  node_iosmodels["Request Models<br/>[TarsModels.swift]"]
  node_network["Network Manager"]
end

subgraph group_server["Control Server"]
  node_server["FastAPI App<br/>[main.py]"]
  node_router["API Router<br/>[router.py]"]
  node_models["API and Plan Models<br/>[models.py]"]
end

subgraph group_planning["Planning and Actions"]
  node_decision["Decision Engine<br/>[decision_engine.py]"]
  node_ollama["Ollama Integration<br/>[llm_local.py]"]
  node_claude["Claude Integration<br/>[llm_claude.py]"]
  node_action["Action Engine<br/>[action_engine.py]"]
end

subgraph group_operations["Operations and Safety"]
  node_config["Settings and Rules<br/>[config.py]"]
  node_security["Request Security<br/>[security.py]"]
  node_audit["Audit Logging<br/>[logger.py]"]
  node_ssh["SSH Manager<br/>[ssh_manager.py]"]
end

node_operator(("Operator"))
node_local["Local Commands"]
node_hosts["Configured Hosts<br/>[hosts.yaml]"]
node_ollama_service["Ollama Service"]
node_claude_service["Claude API"]
node_remote["Remote Host"]

node_operator -->|"enters requests"| node_chat
node_chat -->|"sends input"| node_viewmodel
node_viewmodel -->|"submits requests"| node_network
node_network -->|"encodes and decodes"| node_iosmodels
node_network -->|"HTTP requests"| node_server
node_server -->|"dispatches API"| node_router
node_router -->|"checks access"| node_security
node_router -->|"requests plans"| node_decision
node_decision -->|"plans requests"| node_ollama
node_ollama -->|"calls generation API"| node_ollama_service
node_ollama -->|"returns plan"| node_models
node_decision -->|"returns plan"| node_models
node_router -->|"executes plans"| node_action
node_router -->|"stores or retrieves pending"| node_action
node_action -->|"reads command rules"| node_config
node_action -->|"sanitizes and validates"| node_security
node_action -->|"runs whitelisted commands"| node_local
node_action -->|"dispatches remote actions"| node_ssh
node_ssh -->|"reads host settings"| node_config
node_config -->|"loads host definitions"| node_hosts
node_ssh -->|"executes over SSH"| node_remote
node_action -->|"records action events"| node_audit
node_router -->|"records request events"| node_audit
node_router -->|"builds API responses"| node_models
node_network -->|"returns responses"| node_viewmodel
node_viewmodel -->|"updates chat and speaks"| node_chat
node_chat -->|"shows responses"| node_operator

click node_chat "https://github.com/b-3llum/tars/blob/main/ios/Tars/Views/ChatView.swift"
click node_viewmodel "https://github.com/b-3llum/tars/blob/main/ios/Tars/Views/ChatViewModel.swift"
click node_iosmodels "https://github.com/b-3llum/tars/blob/main/ios/Tars/Models/TarsModels.swift"
click node_network "https://github.com/b-3llum/tars/blob/main/ios/Tars/Network/NetworkManager.swift"
click node_server "https://github.com/b-3llum/tars/blob/main/server/main.py"
click node_router "https://github.com/b-3llum/tars/blob/main/server/router.py"
click node_models "https://github.com/b-3llum/tars/blob/main/server/models.py"
click node_decision "https://github.com/b-3llum/tars/blob/main/server/decision_engine.py"
click node_ollama "https://github.com/b-3llum/tars/blob/main/server/llm_local.py"
click node_claude "https://github.com/b-3llum/tars/blob/main/server/llm_claude.py"
click node_action "https://github.com/b-3llum/tars/blob/main/server/action_engine.py"
click node_config "https://github.com/b-3llum/tars/blob/main/server/config.py"
click node_security "https://github.com/b-3llum/tars/blob/main/server/security.py"
click node_audit "https://github.com/b-3llum/tars/blob/main/server/logger.py"
click node_ssh "https://github.com/b-3llum/tars/blob/main/server/ssh_manager.py"
click node_hosts "https://github.com/b-3llum/tars/blob/main/config/hosts.yaml"

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_chat,node_viewmodel,node_iosmodels,node_network toneBlue
class node_server,node_router,node_models toneAmber
class node_decision,node_ollama,node_claude,node_action,node_claude_service toneMint
class node_config,node_security,node_audit,node_ssh toneRose
class node_operator,node_local,node_ollama_service,node_remote toneIndigo
class node_hosts toneTeal
```

## Components

### iOS Client

- [Chat UI](https://github.com/b-3llum/tars/blob/main/ios/Tars/Views/ChatView.swift): `ios/Tars/Views/ChatView.swift`
- [Chat ViewModel](https://github.com/b-3llum/tars/blob/main/ios/Tars/Views/ChatViewModel.swift): `ios/Tars/Views/ChatViewModel.swift`
- [Request Models](https://github.com/b-3llum/tars/blob/main/ios/Tars/Models/TarsModels.swift): `ios/Tars/Models/TarsModels.swift`
- [Network Manager](https://github.com/b-3llum/tars/blob/main/ios/Tars/Network/NetworkManager.swift): `ios/Tars/Network/NetworkManager.swift`

### Control Server

- [FastAPI App](https://github.com/b-3llum/tars/blob/main/server/main.py): `server/main.py`
- [API Router](https://github.com/b-3llum/tars/blob/main/server/router.py): `server/router.py`
- [API and Plan Models](https://github.com/b-3llum/tars/blob/main/server/models.py): `server/models.py`

### Planning and Actions

- [Decision Engine](https://github.com/b-3llum/tars/blob/main/server/decision_engine.py): `server/decision_engine.py`
- [Ollama Integration](https://github.com/b-3llum/tars/blob/main/server/llm_local.py): `server/llm_local.py`
- [Claude Integration](https://github.com/b-3llum/tars/blob/main/server/llm_claude.py): `server/llm_claude.py`
- [Action Engine](https://github.com/b-3llum/tars/blob/main/server/action_engine.py): `server/action_engine.py`

### Operations and Safety

- [Settings and Rules](https://github.com/b-3llum/tars/blob/main/server/config.py): `server/config.py`
- [Request Security](https://github.com/b-3llum/tars/blob/main/server/security.py): `server/security.py`
- [Audit Logging](https://github.com/b-3llum/tars/blob/main/server/logger.py): `server/logger.py`
- [SSH Manager](https://github.com/b-3llum/tars/blob/main/server/ssh_manager.py): `server/ssh_manager.py`

### Other components

- **Operator**
- **Local Commands**
- [Configured Hosts](https://github.com/b-3llum/tars/blob/main/config/hosts.yaml): `config/hosts.yaml`
- **Ollama Service**
- **Claude API**
- **Remote Host**

## Connections

- Operator → Chat UI: enters requests
- Chat UI → Chat ViewModel: sends input
- Chat ViewModel → Network Manager: submits requests
- Network Manager → Request Models: encodes and decodes
- Network Manager → FastAPI App: HTTP requests
- FastAPI App → API Router: dispatches API
- API Router → Request Security: checks access
- API Router → Decision Engine: requests plans
- Decision Engine → Ollama Integration: plans requests
- Ollama Integration → Ollama Service: calls generation API
- Ollama Integration → API and Plan Models: returns plan
- Decision Engine → API and Plan Models: returns plan
- API Router → Action Engine: executes plans
- API Router → Action Engine: stores or retrieves pending
- Action Engine → Settings and Rules: reads command rules
- Action Engine → Request Security: sanitizes and validates
- Action Engine → Local Commands: runs whitelisted commands
- Action Engine → SSH Manager: dispatches remote actions
- SSH Manager → Settings and Rules: reads host settings
- Settings and Rules → Configured Hosts: loads host definitions
- SSH Manager → Remote Host: executes over SSH
- Action Engine → Audit Logging: records action events
- API Router → Audit Logging: records request events
- API Router → API and Plan Models: builds API responses
- Network Manager → Chat ViewModel: returns responses
- Chat ViewModel → Chat UI: updates chat and speaks
- Chat UI → Operator: shows responses