manual_slop/docs/guide_architecture.md

Manual Slop: Architectural Technical Reference

A deep-dive into the asynchronous orchestration, state synchronization, and the "Linear Execution Clutch" of the Manual Slop engine. This document is designed to move the reader from a high-level mental model to a low-level implementation understanding.

---

1. Philosophy: The Decoupled State Machine

Manual Slop is built on a single, core realization: AI reasoning is high-latency and non-deterministic, while GUI interaction must be low-latency and responsive.

To solve this, the engine enforces a strict decoupling between three distinct boundaries:

• The GUI Boundary (Main Thread): A retained-mode loop (ImGui) that must never block. It handles visual telemetry and user "Seal of Approval" actions.
• The AI Boundary (Daemon Threads): Stateless execution loops that handle the "heavy lifting" of context aggregation, LLM communication, and tool reasoning.
• The Orchestration Boundary (Asyncio): A background thread that manages the flow of data between the other two, ensuring thread-safe communication without blocking the UI.

---

2. System Lifetime & Initialization

The application lifecycle, managed by App in gui_2.py, follows a precise sequence to ensure the environment is ready before the first frame:

1. Context Hydration: The engine reads config.toml (global) and <project>.toml (local). This builds the initial "world view" of the project—what files are tracked, what the discussion history is, and which AI models are active.
2. Thread Bootstrapping:
   • The Asyncio event loop thread is started (_loop_thread).
   • The HookServer (FastAPI) is started as a daemon to handle IPC.
3. UI Entry: The main thread enters immapp.run(). At this point, the GUI is "alive," and the background threads are ready to receive tasks.
4. The Dual-Flush Shutdown: On exit, the system commits state back to both project and global configs. This ensures that your window positions, active discussions, and even pending tool results are preserved for the next session.

---

3. The Task Pipeline: Producer-Consumer Synchronization

Because ImGui state cannot be safely modified from a background thread, Manual Slop uses a Producer-Consumer model for all updates.

The Flow of an AI Request

1. Produce: When you click "Gen + Send," the GUI thread produces a UserRequestEvent and pushes it into the AsyncEventQueue.
2. Consume: The background asyncio loop pops this event and dispatches it to the ai_client. The GUI thread remains free to render and respond to other inputs.
3. Task Backlog: When the AI responds, the background thread cannot update the UI text boxes directly. Instead, it appends a Task Dictionary to the _pending_gui_tasks list.
4. Sync: On every frame, the GUI thread checks this list. If tasks exist, it acquires a lock, clears the list, and executes the updates (e.g., "Set AI response text," "Blink the terminal indicator").

---

4. The Execution Clutch: Human-In-The-Loop (HITL)

The "Execution Clutch" is our answer to the "Black Box" problem of AI. It allows you to shift from automatic execution to a manual, deterministic step-through mode.

How the "Shifting" Works

When the AI requests a destructive action (like running a PowerShell script), the background execution thread is suspended using a threading.Condition:

1. The Pause: The thread enters a .wait() state. It is physically blocked.
2. The Modal: A task is sent to the GUI to open a modal dialog.
3. The Mutation: The user can read the script, edit it, or reject it.
4. The Unleash: When the user clicks "Approve," the GUI thread updates the shared state and calls .notify_all(). The background thread "wakes up," executes the (potentially modified) script, and reports the result back to the AI.

---

5. Security: The MCP Allowlist

To prevent "hallucinated" file access, every filesystem tool (read, list, search) is gated by the MCP (Model Context Protocol) Bridge:

• Resolution: Every path requested by the AI is resolved to an absolute path.
• Checking: It is verified against the project's base_dir. If the AI tries to read_file("C:/Windows/System32/..."), the bridge intercepts the call and returns an ACCESS DENIED error to the model before the OS is ever touched.

---

6. Telemetry & Auditing

Every interaction in Manual Slop is designed to be auditable:

• JSON-L Comms Logs: Raw API traffic is logged for debugging and token cost analysis.
• Generated Scripts: Every script that passes through the "Clutch" is saved to scripts/generated/.
• Performance Monitor: Real-time metrics (FPS, Frame Time, Input Lag) are tracked and can be queried via the Hook API to ensure the UI remains "fluid" under load.