# shubhagarwal-03/raphael architecture

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

- Interactive diagram: https://gitdiagram.com/shubhagarwal-03/raphael
- Repository: https://github.com/shubhagarwal-03/raphael

## Overview

Raphael is a local, offline-first command-line assistant. Its main workflow takes user input through intent handling, memory and rule actions, then planning and tool execution; unmatched requests can fall back to Ollama. Major branches include app control, web search, music playback, calculation, and persistent and semantic memory. The README documents the search-manager ordering, but no such file appears in the tree, so that orchestration is represented as part of main.py. Edges reflect shown imports/calls or README claims; some internal dispatch details are not visible in the excerpts.

Main entry points: [`main.py`](https://github.com/shubhagarwal-03/raphael/blob/master/main.py) (Intent and response flow), [`tool_executor.py`](https://github.com/shubhagarwal-03/raphael/blob/master/tool_executor.py) (Tool execution), [`planner.py`](https://github.com/shubhagarwal-03/raphael/blob/master/planner.py) (Task planner), [`memory.json`](https://github.com/shubhagarwal-03/raphael/blob/master/memory.json) (Persistent memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Input and orchestration"]
  node_main["Intent and response flow<br/>[main.py]"]
  node_planner["Task planner<br/>[planner.py]"]
end

subgraph group_memory["Memory and rules"]
  node_memory_ops["Memory commands<br/>[main.py]"]
  node_long_memory[("Persistent memory<br/>[memory.json]")]
  node_semantic_cache[("Semantic cache<br/>[semantic_cache.py]")]
  node_rules["Rule checks<br/>[rule_engine.py]"]
end

subgraph group_tools["Tools and actions"]
  node_compute["Calculator<br/>[compute.py]"]
  node_tool_runner["Tool execution<br/>[tool_executor.py]"]
  node_song_cache[("Song cache<br/>[song_cache.py]")]
end

subgraph group_runtime["Local runtime"]
  node_app_config["App registry<br/>[config.py]"]
  node_process_runner["Process launcher<br/>[executor.py]"]
end

node_user(("User"))
node_ollama["Ollama model"]
node_browser["Chrome browser"]
node_youtube_search["YouTube search"]

node_user -->|"enters command"| node_main
node_main -->|"plans task"| node_planner
node_planner -->|"routes tool"| node_tool_runner
node_main -->|"handles memory"| node_memory_ops
node_memory_ops -->|"reads and writes"| node_long_memory
node_main -->|"looks up answers"| node_semantic_cache
node_main -->|"uses calculator"| node_compute
node_main -->|"falls back"| node_ollama
node_main -.->|"checks blocks"| node_rules
node_tool_runner -->|"finds app"| node_app_config
node_tool_runner -->|"launches command"| node_process_runner
node_tool_runner -->|"reads and writes"| node_song_cache
node_tool_runner -->|"searches tracks"| node_youtube_search
node_tool_runner -->|"opens results"| node_browser

click node_main "https://github.com/shubhagarwal-03/raphael/blob/master/main.py"
click node_planner "https://github.com/shubhagarwal-03/raphael/blob/master/planner.py"
click node_memory_ops "https://github.com/shubhagarwal-03/raphael/blob/master/main.py"
click node_long_memory "https://github.com/shubhagarwal-03/raphael/blob/master/memory.json"
click node_semantic_cache "https://github.com/shubhagarwal-03/raphael/blob/master/memory/semantic_cache.py"
click node_rules "https://github.com/shubhagarwal-03/raphael/blob/master/rule_engine.py"
click node_compute "https://github.com/shubhagarwal-03/raphael/blob/master/tools/compute.py"
click node_tool_runner "https://github.com/shubhagarwal-03/raphael/blob/master/tool_executor.py"
click node_song_cache "https://github.com/shubhagarwal-03/raphael/blob/master/memory/song_cache.py"
click node_app_config "https://github.com/shubhagarwal-03/raphael/blob/master/config.py"
click node_process_runner "https://github.com/shubhagarwal-03/raphael/blob/master/executor.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_main,node_planner,node_user,node_browser toneBlue
class node_memory_ops,node_long_memory,node_semantic_cache,node_rules toneAmber
class node_compute,node_tool_runner,node_song_cache toneMint
class node_app_config,node_process_runner toneRose
class node_ollama,node_youtube_search toneIndigo
```

## Components

### Input and orchestration

- [Intent and response flow](https://github.com/shubhagarwal-03/raphael/blob/master/main.py): `main.py`
- [Task planner](https://github.com/shubhagarwal-03/raphael/blob/master/planner.py): `planner.py`

### Memory and rules

- [Memory commands](https://github.com/shubhagarwal-03/raphael/blob/master/main.py): `main.py`
- [Persistent memory](https://github.com/shubhagarwal-03/raphael/blob/master/memory.json): `memory.json`
- [Semantic cache](https://github.com/shubhagarwal-03/raphael/blob/master/memory/semantic_cache.py): `memory/semantic_cache.py`
- [Rule checks](https://github.com/shubhagarwal-03/raphael/blob/master/rule_engine.py): `rule_engine.py`

### Tools and actions

- [Calculator](https://github.com/shubhagarwal-03/raphael/blob/master/tools/compute.py): `tools/compute.py`
- [Tool execution](https://github.com/shubhagarwal-03/raphael/blob/master/tool_executor.py): `tool_executor.py`
- [Song cache](https://github.com/shubhagarwal-03/raphael/blob/master/memory/song_cache.py): `memory/song_cache.py`

### Local runtime

- [App registry](https://github.com/shubhagarwal-03/raphael/blob/master/config.py): `config.py`
- [Process launcher](https://github.com/shubhagarwal-03/raphael/blob/master/executor.py): `executor.py`

### Other components

- **User**
- **Ollama model**
- **Chrome browser**
- **YouTube search**

## Connections

- User → Intent and response flow: enters command (evidence: `ReadMe.md`)
- Intent and response flow → Task planner: plans task (evidence: `ReadMe.md`)
- Task planner → Tool execution: routes tool (evidence: `ReadMe.md`)
- Intent and response flow → Memory commands: handles memory (evidence: `ReadMe.md`)
- Memory commands → Persistent memory: reads and writes (evidence: `ReadMe.md`)
- Intent and response flow → Semantic cache: looks up answers (evidence: `main.py`)
- Intent and response flow → Calculator: uses calculator (evidence: `main.py`)
- Intent and response flow → Ollama model: falls back (evidence: `ReadMe.md`)
- Intent and response flow → Rule checks: checks blocks (evidence: `main.py`)
- Tool execution → App registry: finds app (evidence: `tool_executor.py`)
- Tool execution → Process launcher: launches command (evidence: `tool_executor.py`)
- Tool execution → Song cache: reads and writes (evidence: `tool_executor.py`)
- Tool execution → YouTube search: searches tracks (evidence: `ReadMe.md`)
- Tool execution → Chrome browser: opens results (evidence: `tool_executor.py`)
