# nazirlouis/ada_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/nazirlouis/ada_v2
- Repository: https://github.com/nazirlouis/ada_v2

## Overview

1. **System shape**
   - This is a **local desktop application** built from two major runtimes: **Electron + React** for the UI, and a **Python backend** for AI, vision, automation, and hardware control.
   - The app is not cloud-hosted; most data and processing happen on the user’s machine, with only Gemini API calls going over the network.

2. **Desktop shell and UI layer**
   - `electron/main.js` is the desktop host: it creates the application windows, manages lifecycle, and bridges native Electron behavior to the React UI.
   - The React app in `src/` is split into task-specific windows/modules: chat, browser automation, CAD, printer control, Kasa smart home, settings, auth lock, confirmations, memory prompts, and audio/visual feedback.

3. **Frontend as a control surface**
   - The UI is mostly a **command-and-status console** rather than a standalone business-logic layer.
   - Components like `ChatModule`, `ToolsModule`, `TopAudioBar`, and `Visualizer` expose voice/chat state and tool actions, while specialized windows (`CadWindow`, `PrinterWindow`, `BrowserWindow`, `KasaWindow`) surface the outputs of backend agents.

4. **Backend orchestration layer**
   - `backend/server.py` is the central backend entrypoint and request/event hub.
   - It coordinates the UI, authentication, project state, and tool execution, acting as the local control plane that receives user actions and forwards them to the correct subsystem.

5. **Gemini voice and tool-calling core**
   - `backend/ada.py` is the main AI runtime, integrating **Google Gemini 2.5 Native Audio** for low-latency conversational interaction.
   - `backend/tools.py` defines the tool surface exposed to the model, so the assistant can invoke CAD, web, printer, and smart-home actions through controlled functions rather than free-form code.

6. **Specialized agent subsystems**
   - `backend/cad_agent.py` handles parametric CAD generation and iteration, with `build123d`-style model creation and STL output.
   - `backend/web_agent.py` drives browser automation via **Playwright/Chromium**.
   - `backend/printer_agent.py` handles printer discovery, slicing, and print submission.
   - `backend/kasa_agent.py` manages TP-Link Kasa smart-home device control.

7. **Authentication and interaction gating**
   - `backend/authenticator.py` provides **local face authentication** using MediaPipe face landmarks; the `reference.jpg` file is the biometric anchor.
   - The UI also uses confirmation flows for sensitive actions, and `settings.json` stores whether tools like CAD generation, web automation, or file writes require manual approval before execution.

8. **Vision and gesture control**
   - Camera-based gestures are supported through MediaPipe task assets (`face_landmarker.task`, `hand_landmarker.task`).
   - Hand gestures are part of the UI interaction model, enabling window selection/movement and action confirmation without conventional mouse input.

9. **Project memory and workspace model**
   - `backend/project_manager.py` manages persistent per-project context and file organization.
   - The repository implies a workspace model where generated assets land under project folders, especially CAD outputs such as STL files, so the assistant can iterate on a named project across sessions.

10. **CAD-to-print pipeline**
   - The CAD path is a distinct pipeline: user intent → CAD agent → generated model/STL → optional verification → slicing/printing.
   - `backend/verify_cad.py`, `backend/temp_cad_gen.py`, and related mock/test files indicate that CAD generation has a validation step and supports iterative refinement before anything is sent to a printer.

11. **3D printing and physical device boundary**
   - Printer integration spans local network discovery, slicer integration, and printer APIs such as **Moonraker/OctoPrint/PrusaLink**.
   - This is a clear boundary between digital design and physical output: the backend prepares G-code and then submits jobs to external printer infrastructure.

12. **Persistence and configuration**
   - Persistent state is lightweight and file-based: `.env` for secrets, `settings.json` for app behavior, and project directories for user assets.
   - There is no separate database service in the repo; the architecture relies on local files and runtime state.

13. **Validation and support tooling**
   - The `tests/` directory covers the agents and server behavior, indicating the architecture is modular and testable by subsystem.
   - Debug and trace scripts (`debug_*`, `read_trace.py`, `grep_trace.py`) suggest the system is designed to diagnose hardware, network, and agent issues across the local device and external peripherals.

Main entry points: [`backend/server.py`](https://github.com/nazirlouis/ada_v2/blob/main/backend/server.py) (Backend server), [`backend/tools.py`](https://github.com/nazirlouis/ada_v2/blob/main/backend/tools.py) (Tool surface), [`src/App.jsx`](https://github.com/nazirlouis/ada_v2/blob/main/src/App.jsx) (App shell), [`backend/cad_agent.py`](https://github.com/nazirlouis/ada_v2/blob/main/backend/cad_agent.py) (CAD agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop UI"]
  node_electron_main["Electron host<br/>desktop shell<br/>[main.js]"]
  node_app_shell["App shell<br/>React root<br/>[App.jsx]"]
  node_chat_module["Chat module<br/>UI module<br/>[ChatModule.jsx]"]
  node_tools_module["Tools module<br/>UI module<br/>[ToolsModule.jsx]"]
  node_audio_visual["Audio feedback<br/>UI feedback<br/>[TopAudioBar.jsx]"]
  node_special_windows["Task windows<br/>UI windows"]
end

subgraph group_backend["Backend Control Plane"]
  node_server["Backend server<br/>orchestrator<br/>[server.py]"]
  node_ada["Ada runtime<br/>gemini voice core<br/>[ada.py]"]
  node_tools["Tool surface<br/>tool registry<br/>[tools.py]"]
  node_project_manager["Project memory<br/>workspace state<br/>[project_manager.py]"]
end

subgraph group_agents["Automation Agents"]
  node_cad_agent["CAD agent<br/>parametric cad<br/>[cad_agent.py]"]
  node_web_agent["Web agent<br/>browser automation<br/>[web_agent.py]"]
  node_printer_agent["Printer agent<br/>3d print pipeline<br/>[printer_agent.py]"]
  node_kasa_agent["Kasa agent<br/>smart-home control<br/>[kasa_agent.py]"]
end

subgraph group_support["Support Tools"]
  node_authenticator["Face auth<br/>local biometrics<br/>[authenticator.py]"]
  node_cad_verify["CAD verify<br/>validation<br/>[verify_cad.py]"]
end

node_electron_main -->|"launches"| node_app_shell
node_app_shell -->|"renders"| node_chat_module
node_app_shell -->|"renders"| node_tools_module
node_app_shell -->|"renders"| node_audio_visual
node_app_shell -->|"opens"| node_special_windows
node_special_windows -.->|"gated by"| node_authenticator
node_server -->|"coordinates"| node_ada
node_server -->|"exposes"| node_tools
node_server -->|"tracks"| node_project_manager
node_server -->|"checks"| node_authenticator
node_ada -->|"calls"| node_tools
node_tools -->|"routes"| node_cad_agent
node_tools -->|"routes"| node_web_agent
node_tools -->|"routes"| node_printer_agent
node_tools -->|"routes"| node_kasa_agent
node_cad_agent -.->|"validates"| node_cad_verify
node_cad_agent -->|"writes"| node_project_manager
node_printer_agent -->|"reads"| node_project_manager
node_server -.->|"feeds status"| node_chat_module
node_server -.->|"updates"| node_special_windows

click node_electron_main "https://github.com/nazirlouis/ada_v2/blob/main/electron/main.js"
click node_app_shell "https://github.com/nazirlouis/ada_v2/blob/main/src/App.jsx"
click node_chat_module "https://github.com/nazirlouis/ada_v2/blob/main/src/components/ChatModule.jsx"
click node_tools_module "https://github.com/nazirlouis/ada_v2/blob/main/src/components/ToolsModule.jsx"
click node_audio_visual "https://github.com/nazirlouis/ada_v2/blob/main/src/components/TopAudioBar.jsx"
click node_server "https://github.com/nazirlouis/ada_v2/blob/main/backend/server.py"
click node_ada "https://github.com/nazirlouis/ada_v2/blob/main/backend/ada.py"
click node_tools "https://github.com/nazirlouis/ada_v2/blob/main/backend/tools.py"
click node_project_manager "https://github.com/nazirlouis/ada_v2/blob/main/backend/project_manager.py"
click node_authenticator "https://github.com/nazirlouis/ada_v2/blob/main/backend/authenticator.py"
click node_cad_agent "https://github.com/nazirlouis/ada_v2/blob/main/backend/cad_agent.py"
click node_web_agent "https://github.com/nazirlouis/ada_v2/blob/main/backend/web_agent.py"
click node_printer_agent "https://github.com/nazirlouis/ada_v2/blob/main/backend/printer_agent.py"
click node_kasa_agent "https://github.com/nazirlouis/ada_v2/blob/main/backend/kasa_agent.py"
click node_cad_verify "https://github.com/nazirlouis/ada_v2/blob/main/backend/verify_cad.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_electron_main,node_app_shell,node_chat_module,node_tools_module,node_audio_visual,node_special_windows toneBlue
class node_server,node_ada,node_tools,node_project_manager toneAmber
class node_cad_agent,node_web_agent,node_printer_agent,node_kasa_agent toneMint
class node_authenticator,node_cad_verify toneRose
```

## Components

### Desktop UI

Electron shell and React control surface.

- [Electron host](https://github.com/nazirlouis/ada_v2/blob/main/electron/main.js): desktop shell · Creates the desktop window and bridges native app lifecycle to the UI. · `electron/main.js`
- [App shell](https://github.com/nazirlouis/ada_v2/blob/main/src/App.jsx): React root · Top-level React application that routes the desktop experience. · `src/App.jsx`
- [Chat module](https://github.com/nazirlouis/ada_v2/blob/main/src/components/ChatModule.jsx): UI module · Primary conversation and command surface. · `src/components/ChatModule.jsx`
- [Tools module](https://github.com/nazirlouis/ada_v2/blob/main/src/components/ToolsModule.jsx): UI module · Exposes tool actions and task controls to the user. · `src/components/ToolsModule.jsx`
- [Audio feedback](https://github.com/nazirlouis/ada_v2/blob/main/src/components/TopAudioBar.jsx): UI feedback · Voice status and visual feedback for the assistant. · `src/components/TopAudioBar.jsx`
- **Task windows**: UI windows · Specialized surfaces for browser, CAD, printer, Kasa, settings, and prompts.

### Backend Control Plane

Local orchestration, AI runtime, and shared state.

- [Backend server](https://github.com/nazirlouis/ada_v2/blob/main/backend/server.py): orchestrator · Central request and event hub for the local control plane. · `backend/server.py`
- [Ada runtime](https://github.com/nazirlouis/ada_v2/blob/main/backend/ada.py): gemini voice core · Low-latency Gemini audio conversation and tool-calling runtime. · `backend/ada.py`
- [Tool surface](https://github.com/nazirlouis/ada_v2/blob/main/backend/tools.py): tool registry · Defines the callable actions exposed to the AI runtime. · `backend/tools.py`
- [Project memory](https://github.com/nazirlouis/ada_v2/blob/main/backend/project_manager.py): workspace state · Manages persistent per-project context and generated assets. · `backend/project_manager.py`

### Automation Agents

Specialized subsystems for CAD, web, printer, and smart-home actions.

- [CAD agent](https://github.com/nazirlouis/ada_v2/blob/main/backend/cad_agent.py): parametric cad · Generates and iterates models and STL output. · `backend/cad_agent.py`
- [Web agent](https://github.com/nazirlouis/ada_v2/blob/main/backend/web_agent.py): browser automation · Controls Chromium via Playwright for browser tasks. · `backend/web_agent.py`
- [Printer agent](https://github.com/nazirlouis/ada_v2/blob/main/backend/printer_agent.py): 3d print pipeline · Handles printer discovery, slicing, and job submission. · `backend/printer_agent.py`
- [Kasa agent](https://github.com/nazirlouis/ada_v2/blob/main/backend/kasa_agent.py): smart-home control · Controls TP-Link Kasa devices on the local network. · `backend/kasa_agent.py`

### Support Tools

Authentication, verification, and workspace helpers.

- [Face auth](https://github.com/nazirlouis/ada_v2/blob/main/backend/authenticator.py): local biometrics · Performs local face-based authentication for gated actions. · `backend/authenticator.py`
- [CAD verify](https://github.com/nazirlouis/ada_v2/blob/main/backend/verify_cad.py): validation · Validates generated CAD iterations before release or printing. · `backend/verify_cad.py`

## Connections

- Electron host → App shell: launches · Starts and hosts the React application.
- App shell → Chat module: renders · Composes the main conversation surface.
- App shell → Tools module: renders · Provides task controls and action entry points.
- App shell → Audio feedback: renders · Surfaces voice state and assistant feedback.
- App shell → Task windows: opens · Manages task-specific windows and prompts.
- Task windows → Face auth: gated by · Sensitive interactions require local authentication or confirmation.
- Backend server → Ada runtime: coordinates · Routes user interactions into the AI runtime.
- Backend server → Tool surface: exposes · Publishes the controlled tool set to the backend.
- Backend server → Project memory: tracks · Maintains per-project context and workspace state.
- Backend server → Face auth: checks · Applies local authentication before protected actions.
- Ada runtime → Tool surface: calls · Invokes tool functions during conversation.
- Tool surface → CAD agent: routes · Delegates CAD tasks to the modeling subsystem.
- Tool surface → Web agent: routes · Delegates browser automation tasks.
- Tool surface → Printer agent: routes · Delegates printing and slicing tasks.
- Tool surface → Kasa agent: routes · Delegates smart-home control tasks.
- CAD agent → CAD verify: validates · Runs CAD output through validation before handoff.
- CAD agent → Project memory: writes · Stores generated CAD artifacts in project workspace.
- Printer agent → Project memory: reads · Uses project assets when preparing print jobs.
- Backend server → Chat module: feeds status · Pushes backend state back into the UI.
- Backend server → Task windows: updates · Updates task windows with agent results and confirmations.
