# tzpzfmz/upsp architecture

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

- Interactive diagram: https://gitdiagram.com/tzpzfmz/upsp
- Repository: https://github.com/tzpzfmz/upsp

## Overview

UPSP is a local Windows application for maintaining a continuing, auditable persona across model calls. The principal workflow is initialization, then a serial setup → reaction (including tool practice) → cleanup cycle; assembled context and persisted state, memory, relationships, and Round records carry results forward. The README documents the product stages and capabilities; source-index references and excerpts support the named implementation layers. Some GUI-to-backend wiring and unsampled subsystem calls are not shown, so those links are omitted or marked unverified.

Main entry points: [`UPSP/OS/engines/executor.py`](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/executor.py) (Runtime Executor), [`UPSP/OS/assembly/context.py`](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/assembly/context.py) (Context Assembly), [`UPSP/OS/engines/cleanup_pipeline.py`](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/cleanup_pipeline.py) (Cleanup Stage), [`UPSP/OS/engines/reaction_loop.py`](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/reaction_loop.py) (Reaction Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User Surface"]
  node_desktop["Windows Desktop Shell<br/>[MainForm.cs]"]
  node_gui["Conversation UI<br/>[view.ts]"]
  node_gui_runtime["GUI Runtime<br/>[runtime.ts]"]
end

subgraph group_runtime["Runtime Cycle"]
  node_backend["Local Backend Entry<br/>[main.py]"]
  node_executor["Runtime Executor<br/>[executor.py]"]
  node_setup_stage["Setup Stage<br/>[setup_runner.py]"]
  node_reaction["Reaction Loop<br/>[reaction_loop.py]"]
  node_cleanup["Cleanup Stage"]
end

subgraph group_context["Context and Action"]
  node_assembly["Context Assembly<br/>[context.py]"]
  node_tool_dispatch["Tool Dispatch"]
end

subgraph group_records["Persona Records"]
  node_memory[("Memory Records<br/>[memory_store.py]")]
  node_relations[("Relationship Records<br/>[relation_store.py]")]
  node_state[("Persona State<br/>[state_store.py]")]
  node_context_store[("Context Cache<br/>[context_store.py]")]
  node_workbench[("Workbench<br/>[workbench.py]")]
  node_round_history[("Round History<br/>[chronicle_store.py]")]
end

subgraph group_setup["Identity and Setup"]
  node_initializer["Persona Initialization"]
  node_instance["Instance Management"]
  node_config[("Model Configuration<br/>[config_store.py]")]
end

node_user(("User"))
node_provider(("Configured Model Service"))

node_user -->|"uses"| node_desktop
node_desktop -.->|"presents"| node_gui
node_gui -->|"dispatches UI events"| node_gui_runtime
node_gui_runtime -.->|"requests"| node_backend
node_user -->|"creates persona"| node_initializer
node_initializer -.->|"initializes instance"| node_instance
node_backend -->|"starts runtime"| node_executor
node_executor -.->|"runs setup"| node_setup_stage
node_executor -.->|"runs reaction"| node_reaction
node_executor -.->|"runs cleanup"| node_cleanup
node_reaction -->|"sends request"| node_provider
node_reaction -.->|"dispatches tools"| node_tool_dispatch
node_executor -->|"assembles frames"| node_assembly
node_assembly -->|"reads memory"| node_memory
node_assembly -->|"reads relationships"| node_relations
node_assembly -->|"uses context cache"| node_context_store
node_assembly -.->|"mounts materials"| node_workbench
node_cleanup -.->|"settles memory"| node_memory
node_cleanup -.->|"settles state"| node_state
node_cleanup -->|"records Round"| node_round_history
node_executor -->|"reads and updates"| node_state
node_executor -->|"loads settings"| node_config
node_config -->|"configures connection"| node_provider

click node_desktop "https://github.com/tzpzfmz/upsp/blob/main/desktop/UPSP.Desktop/MainForm.cs"
click node_gui "https://github.com/tzpzfmz/upsp/blob/main/UPSP/gui/src/view.ts"
click node_gui_runtime "https://github.com/tzpzfmz/upsp/blob/main/UPSP/gui/src/runtime.ts"
click node_backend "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/main.py"
click node_initializer "https://github.com/tzpzfmz/upsp/blob/main/UPSP/initialization/persona_initializer.py"
click node_instance "https://github.com/tzpzfmz/upsp/blob/main/UPSP/initialization/instance_service.py"
click node_executor "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/executor.py"
click node_setup_stage "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/setup_runner.py"
click node_reaction "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/reaction_loop.py"
click node_cleanup "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/cleanup_pipeline.py"
click node_assembly "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/assembly/context.py"
click node_tool_dispatch "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/general_tool_dispatcher.py"
click node_memory "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/memory_store.py"
click node_relations "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/relation_store.py"
click node_state "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/state_store.py"
click node_context_store "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/context_store.py"
click node_workbench "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/workbench.py"
click node_round_history "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/chronicle_store.py"
click node_config "https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/config_store.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_desktop,node_gui,node_gui_runtime,node_user toneBlue
class node_backend,node_executor,node_setup_stage,node_reaction,node_cleanup toneAmber
class node_assembly,node_tool_dispatch toneMint
class node_memory,node_relations,node_state,node_context_store,node_workbench,node_round_history toneRose
class node_initializer,node_instance,node_config,node_provider toneIndigo
```

## Components

### User Surface

- [Windows Desktop Shell](https://github.com/tzpzfmz/upsp/blob/main/desktop/UPSP.Desktop/MainForm.cs): `desktop/UPSP.Desktop/MainForm.cs`
- [Conversation UI](https://github.com/tzpzfmz/upsp/blob/main/UPSP/gui/src/view.ts): `UPSP/gui/src/view.ts`
- [GUI Runtime](https://github.com/tzpzfmz/upsp/blob/main/UPSP/gui/src/runtime.ts): `UPSP/gui/src/runtime.ts`

### Runtime Cycle

- [Local Backend Entry](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/main.py): `UPSP/OS/main.py`
- [Runtime Executor](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/executor.py): `UPSP/OS/engines/executor.py`
- [Setup Stage](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/setup_runner.py): `UPSP/OS/engines/setup_runner.py`
- [Reaction Loop](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/reaction_loop.py): `UPSP/OS/engines/reaction_loop.py`
- [Cleanup Stage](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/cleanup_pipeline.py): `UPSP/OS/engines/cleanup_pipeline.py`

### Context and Action

- [Context Assembly](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/assembly/context.py): `UPSP/OS/assembly/context.py`
- [Tool Dispatch](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/engines/general_tool_dispatcher.py): `UPSP/OS/engines/general_tool_dispatcher.py`

### Persona Records

- [Memory Records](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/memory_store.py): `UPSP/OS/data/memory_store.py`
- [Relationship Records](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/relation_store.py): `UPSP/OS/data/relation_store.py`
- [Persona State](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/state_store.py): `UPSP/OS/data/state_store.py`
- [Context Cache](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/context_store.py): `UPSP/OS/data/context_store.py`
- [Workbench](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/workbench.py): `UPSP/OS/data/workbench.py`
- [Round History](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/chronicle_store.py): `UPSP/OS/data/chronicle_store.py`

### Identity and Setup

- [Persona Initialization](https://github.com/tzpzfmz/upsp/blob/main/UPSP/initialization/persona_initializer.py): `UPSP/initialization/persona_initializer.py`
- [Instance Management](https://github.com/tzpzfmz/upsp/blob/main/UPSP/initialization/instance_service.py): `UPSP/initialization/instance_service.py`
- [Model Configuration](https://github.com/tzpzfmz/upsp/blob/main/UPSP/OS/data/config_store.py): `UPSP/OS/data/config_store.py`

### Other components

- **User**
- **Configured Model Service**

## Connections

- User → Windows Desktop Shell: uses (evidence: `README.md`)
- Windows Desktop Shell → Conversation UI: presents
- Conversation UI → GUI Runtime: dispatches UI events (evidence: `UPSP/gui/src/app.ts`)
- GUI Runtime → Local Backend Entry: requests
- User → Persona Initialization: creates persona (evidence: `README.md`)
- Persona Initialization → Instance Management: initializes instance (evidence: `UPSP/initialization/instance_service.py`)
- Local Backend Entry → Runtime Executor: starts runtime (evidence: `UPSP/OS/main.py`)
- Runtime Executor → Setup Stage: runs setup
- Runtime Executor → Reaction Loop: runs reaction
- Runtime Executor → Cleanup Stage: runs cleanup
- Reaction Loop → Configured Model Service: sends request (evidence: `README.md`)
- Reaction Loop → Tool Dispatch: dispatches tools
- Runtime Executor → Context Assembly: assembles frames (evidence: `UPSP/OS/engines/runtime_services.py`)
- Context Assembly → Memory Records: reads memory (evidence: `UPSP/OS/assembly/context.py`)
- Context Assembly → Relationship Records: reads relationships (evidence: `UPSP/OS/assembly/context.py`)
- Context Assembly → Context Cache: uses context cache (evidence: `UPSP/OS/assembly/context.py`)
- Context Assembly → Workbench: mounts materials (evidence: `UPSP/OS/assembly/context.py`)
- Cleanup Stage → Memory Records: settles memory
- Cleanup Stage → Persona State: settles state
- Cleanup Stage → Round History: records Round (evidence: `UPSP/OS/engines/cleanup_pipeline.py`)
- Runtime Executor → Persona State: reads and updates (evidence: `UPSP/OS/engines/runtime_services.py`)
- Runtime Executor → Model Configuration: loads settings (evidence: `UPSP/OS/engines/runtime_services.py`)
- Model Configuration → Configured Model Service: configures connection (evidence: `UPSP/OS/data/config_store.py`)