# beeegee/fuwa architecture

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

- Interactive diagram: https://gitdiagram.com/beeegee/fuwa
- Repository: https://github.com/beeegee/fuwa

## Overview

Fuwa is a terminal companion whose main workflow is to observe configured folders, turn file activity into LLM-generated reactions, and present those reactions and text-RPG choices in a TUI with an animated axolotl. Users can also chat through choices, evolve the companion’s personality, and configure providers and watched folders. The graph follows the app orchestration and sampled module references; unsampled UI and event wiring is shown only where the README or source index supports it.

Main entry points: [`fuwa.py`](https://github.com/beeegee/fuwa/blob/main/fuwa.py) (Fuwa TUI app), [`features/brain/__init__.py`](https://github.com/beeegee/fuwa/blob/main/features/brain/__init__.py) (Fuwa brain), [`infrastructure/config/__init__.py`](https://github.com/beeegee/fuwa/blob/main/infrastructure/config/__init__.py) (Configuration), [`features/file_observer/__init__.py`](https://github.com/beeegee/fuwa/blob/main/features/file_observer/__init__.py) (File observer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Terminal experience"]
  node_app["Fuwa TUI app<br/>[fuwa.py]"]
  node_chat["Chat UI<br/>[__init__.py]"]
  node_dashboard["Dashboard UI<br/>[__init__.py]"]
  node_settings_ui["Settings UI<br/>[__init__.py]"]
  node_animation["Axolotl animation<br/>[__init__.py]"]
  node_ansi["ANSI image conversion<br/>[__init__.py]"]
end

subgraph group_companion["Observation and companion"]
  node_observer["File observer<br/>[__init__.py]"]
  node_brain["Fuwa brain<br/>[__init__.py]"]
end

subgraph group_services["Runtime services"]
  node_llm["LLM requests<br/>[__init__.py]"]
  node_provider(("LLM provider"))
  node_memory[("File memories<br/>[__init__.py]")]
  node_config[("Configuration<br/>[__init__.py]")]
  node_events["Event bus<br/>[__init__.py]"]
end

subgraph group_configuration["Setup and settings"]
  node_setup["First-run setup<br/>[__init__.py]"]
end

node_user(("User"))
node_folders["Watched folders"]

node_user -->|"uses"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"starts observing"| node_observer
node_folders -->|"supplies changes"| node_observer
node_observer -.->|"provides activity"| node_brain
node_app -->|"creates"| node_brain
node_brain -->|"requests reactions"| node_llm
node_llm -->|"sends requests"| node_provider
node_brain -->|"reads and updates"| node_memory
node_brain -->|"reads and updates"| node_config
node_app -->|"creates bus"| node_events
node_brain -->|"publishes updates"| node_events
node_app -.->|"uses interface"| node_chat
node_app -.->|"uses interface"| node_dashboard
node_app -.->|"uses interface"| node_settings_ui
node_settings_ui -->|"loads and saves"| node_config
node_app -->|"renders buddy"| node_animation
node_animation -->|"converts sprites"| node_ansi
node_user -->|"configures"| node_setup
node_setup -->|"writes settings"| node_config

click node_app "https://github.com/beeegee/fuwa/blob/main/fuwa.py"
click node_chat "https://github.com/beeegee/fuwa/blob/main/features/chat_ui/__init__.py"
click node_dashboard "https://github.com/beeegee/fuwa/blob/main/features/dashboard_ui/__init__.py"
click node_settings_ui "https://github.com/beeegee/fuwa/blob/main/features/settings_ui/__init__.py"
click node_animation "https://github.com/beeegee/fuwa/blob/main/features/axolotl/__init__.py"
click node_ansi "https://github.com/beeegee/fuwa/blob/main/infrastructure/ansi/__init__.py"
click node_observer "https://github.com/beeegee/fuwa/blob/main/features/file_observer/__init__.py"
click node_brain "https://github.com/beeegee/fuwa/blob/main/features/brain/__init__.py"
click node_llm "https://github.com/beeegee/fuwa/blob/main/infrastructure/llm/__init__.py"
click node_memory "https://github.com/beeegee/fuwa/blob/main/infrastructure/memory/__init__.py"
click node_config "https://github.com/beeegee/fuwa/blob/main/infrastructure/config/__init__.py"
click node_events "https://github.com/beeegee/fuwa/blob/main/infrastructure/events/__init__.py"
click node_setup "https://github.com/beeegee/fuwa/blob/main/features/setup/__init__.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_app,node_chat,node_dashboard,node_settings_ui,node_animation,node_ansi,node_user toneBlue
class node_observer,node_brain toneAmber
class node_llm,node_provider,node_memory,node_config,node_events toneMint
class node_setup toneRose
class node_folders toneIndigo
```

## Components

### Terminal experience

- [Fuwa TUI app](https://github.com/beeegee/fuwa/blob/main/fuwa.py): `fuwa.py`
- [Chat UI](https://github.com/beeegee/fuwa/blob/main/features/chat_ui/__init__.py): `features/chat_ui/__init__.py`
- [Dashboard UI](https://github.com/beeegee/fuwa/blob/main/features/dashboard_ui/__init__.py): `features/dashboard_ui/__init__.py`
- [Settings UI](https://github.com/beeegee/fuwa/blob/main/features/settings_ui/__init__.py): `features/settings_ui/__init__.py`
- [Axolotl animation](https://github.com/beeegee/fuwa/blob/main/features/axolotl/__init__.py): `features/axolotl/__init__.py`
- [ANSI image conversion](https://github.com/beeegee/fuwa/blob/main/infrastructure/ansi/__init__.py): `infrastructure/ansi/__init__.py`

### Observation and companion

- [File observer](https://github.com/beeegee/fuwa/blob/main/features/file_observer/__init__.py): `features/file_observer/__init__.py`
- [Fuwa brain](https://github.com/beeegee/fuwa/blob/main/features/brain/__init__.py): `features/brain/__init__.py`

### Runtime services

- [LLM requests](https://github.com/beeegee/fuwa/blob/main/infrastructure/llm/__init__.py): `infrastructure/llm/__init__.py`
- **LLM provider**
- [File memories](https://github.com/beeegee/fuwa/blob/main/infrastructure/memory/__init__.py): `infrastructure/memory/__init__.py`
- [Configuration](https://github.com/beeegee/fuwa/blob/main/infrastructure/config/__init__.py): `infrastructure/config/__init__.py`
- [Event bus](https://github.com/beeegee/fuwa/blob/main/infrastructure/events/__init__.py): `infrastructure/events/__init__.py`

### Setup and settings

- [First-run setup](https://github.com/beeegee/fuwa/blob/main/features/setup/__init__.py): `features/setup/__init__.py`

### Other components

- **User**
- **Watched folders**

## Connections

- User → Fuwa TUI app: uses (evidence: `README.md`)
- Fuwa TUI app → Configuration: loads settings (evidence: `fuwa.py`)
- Fuwa TUI app → File observer: starts observing (evidence: `fuwa.py`)
- Watched folders → File observer: supplies changes (evidence: `README.md`)
- File observer → Fuwa brain: provides activity
- Fuwa TUI app → Fuwa brain: creates (evidence: `fuwa.py`)
- Fuwa brain → LLM requests: requests reactions (evidence: `features/brain/__init__.py`)
- LLM requests → LLM provider: sends requests (evidence: `infrastructure/llm/__init__.py`)
- Fuwa brain → File memories: reads and updates (evidence: `features/brain/__init__.py`)
- Fuwa brain → Configuration: reads and updates (evidence: `features/brain/__init__.py`)
- Fuwa TUI app → Event bus: creates bus (evidence: `fuwa.py`)
- Fuwa brain → Event bus: publishes updates (evidence: `features/brain/__init__.py`)
- Fuwa TUI app → Chat UI: uses interface (evidence: `fuwa.py`)
- Fuwa TUI app → Dashboard UI: uses interface (evidence: `fuwa.py`)
- Fuwa TUI app → Settings UI: uses interface (evidence: `fuwa.py`)
- Settings UI → Configuration: loads and saves (evidence: `features/settings_ui/__init__.py`)
- Fuwa TUI app → Axolotl animation: renders buddy (evidence: `fuwa.py`)
- Axolotl animation → ANSI image conversion: converts sprites (evidence: `features/axolotl/__init__.py`)
- User → First-run setup: configures (evidence: `README.md`)
- First-run setup → Configuration: writes settings (evidence: `features/setup/__init__.py`)
