# bbrunossf/presentationagent architecture

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

- Interactive diagram: https://gitdiagram.com/bbrunossf/presentationagent
- Repository: https://github.com/bbrunossf/presentationagent

## Overview

##### Project type and purpose
- This is a full‑stack web application built with Remix (React on the frontend, Node.js on the backend) that provides an interactive UI for sending commands to an AI agent and visualizing the results (text, charts, canvas).  A secondary Python microservice (“agent”) handles transcription (via Whisper) and command execution.

##### File structure
- Top‑level:
- package.json, tsconfig.json, remix.config.js, vite.config.ts → Node/Remix app config
- app/ → Remix source
- public/ → static assets
- .gitignore, Dockerfile, docker‑compose.yml → container setup
- app/routes/ holds your HTTP endpoints (`api.run-agent.ts`, `api.transcribe.ts`) and the main UI route (`_index.tsx`).
- app/components/ contains React UI: Canvas, Sidebar, Header, Input/Output.
- app/services/remoteAgent.ts wraps HTTP calls to your backend API.
- app/store/useCommandStore.ts is your client‑side state store (e.g., Zustand).
- app/data/routes.json stores generated route history.
- app/utils/ generate/write functions create new Remix routes dynamically.
- app/backend/ is a Python agent microservice (Docker‑ized) with main.py and whisper_handler.py.

##### README for additional insights
- The goal is live demo of commands→agent→UI refresh.
- It calls for real‑time re‑rendering (Remix revalidation), canvas/panel for results, an API to modify/save routes, and server‑side change detection.

a. Main components
- User Interface (React/Remix loader/actions)
- Remix Server (Node.js runtime hosting routes & APIs)
- AI Agent Microservice (Python + Whisper)
- Data Store (routes.json file, dynamic route files)
- External AI/Whisper library
b. Relationships & interactions
1. User enters a command in VoiceInput/CommandInput → React state/store
2. remoteAgent service invokes POST /api.run-agent or /api.transcribe on Remix server
3. Remix route handler forwards request to the Python agent via HTTP (Docker Compose network)
4. Python agent processes (transcription or action) → returns JSON result
5. Remix handler returns response → React updates OutputDisplay/Canvas/WorkloadChart
6. If route generation is involved: utils.generateRoute → writeRouteToFile updates file system → Remix triggers revalidation → new dynamic route appears
c. Architectural patterns & design principles
- Separation of concerns: UI vs. API vs. agent service
- Event‑driven flow: user action triggers network calls → stream results
- Dynamic code generation: server writes new route modules
- Revalidation (Remix incremental re‑render) for real‑time updates
d. Relevant technologies/frameworks
- Frontend: React + TypeScript, Tailwind CSS, Zustand (store), Canvas/Chart libs
- Backend: Remix (Node.js), Express‑style routes, file‑watch/revalidate
- Agent: Python 3, Whisper, Flask or pure HTTP server
- Orchestration: Docker Compose
- Persistence: JSON file (routes.json) + generated .tsx files

##### Detailed capture of essential elements
- Network calls (HTTP), file operations, and revalidation triggers.
- How dynamic route generation flows from front → server util → write to disk → Remix dev server picks up changes.
- Don’t simply list files—represent their runtime roles (UI, API, service, data store).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Docker Compose Network"
    subgraph "Remix App"
      subgraph "Browser / React Components"
        CI["CommandInput Component"]:::ui
        VI["VoiceInput Component"]:::ui
        CAN["Canvas Component"]:::ui
        OD["OutputDisplay Component"]:::ui
        WC["WorkloadChart Component"]:::ui
        SB["Sidebar Component"]:::ui
        HL["Header/Layout Component"]:::ui
      end

      subgraph "Client Store & Services"
        Store["useCommandStore (Zustand)"]:::backend
        Remote["remoteAgent Service"]:::backend
      end

      subgraph "Server / API Routes"
        MainRoute["_index.tsx (UI Entry Route)"]:::backend
        API_RUN["POST /api.run-agent Route"]:::backend
        API_TRANS["POST /api.transcribe Route"]:::backend
      end

      subgraph "Dynamic Route Generation"
        Gen["generateRoute Utility"]:::backend
        Write["writeRouteToFile Utility"]:::backend
        DS["routes.json Data Store"]:::data
      end
    end

    subgraph "Agent Microservice"
      PyServer["main.py (Python HTTP Server)"]:::micro
      WH["whisper_handler.py"]:::micro
      Req["requirements.txt"]:::micro
      DockerfileAgent["Dockerfile"]:::micro
      Compose["docker-compose.yml"]:::micro
    end
  end

  CI --> Store
  VI --> Store
  Store --> Remote
  Remote --> API_RUN
  Remote --> API_TRANS
  API_RUN --> PyServer
  API_TRANS --> PyServer
  PyServer --> WH
  WH --> API_TRANS
  PyServer --> API_RUN
  API_RUN --> Remote
  API_TRANS --> Remote
  Store --> CAN
  Store --> OD
  Store --> WC

  API_RUN --> Gen
  Gen --> Write
  Write -.-> DS
  DS -.-> MainRoute

  click CI "https://github.com/bbrunossf/presentationagent/blob/main/app/components/CommandInput.tsx"
  click VI "https://github.com/bbrunossf/presentationagent/blob/main/app/components/VoiceInput.tsx"
  click CAN "https://github.com/bbrunossf/presentationagent/blob/main/app/components/Canvas.tsx"
  click OD "https://github.com/bbrunossf/presentationagent/blob/main/app/components/OutputDisplay.tsx"
  click WC "https://github.com/bbrunossf/presentationagent/blob/main/app/components/WorkloadChart.tsx"
  click SB "https://github.com/bbrunossf/presentationagent/blob/main/app/components/Sidebar.tsx"
  click HL "https://github.com/bbrunossf/presentationagent/blob/main/app/components/Layout.tsx"
  click MainRoute "https://github.com/bbrunossf/presentationagent/blob/main/app/routes/_index.tsx"
  click API_RUN "https://github.com/bbrunossf/presentationagent/blob/main/app/routes/api.run-agent.ts"
  click API_TRANS "https://github.com/bbrunossf/presentationagent/blob/main/app/routes/api.transcribe.ts"
  click Remote "https://github.com/bbrunossf/presentationagent/blob/main/app/services/remoteAgent.ts"
  click Store "https://github.com/bbrunossf/presentationagent/blob/main/app/store/useCommandStore.ts"
  click DS "https://github.com/bbrunossf/presentationagent/blob/main/app/data/routes.json"
  click Gen "https://github.com/bbrunossf/presentationagent/blob/main/app/utils/generateRoute.ts"
  click Write "https://github.com/bbrunossf/presentationagent/blob/main/app/utils/writeRouteToFile.ts"
  click PyServer "https://github.com/bbrunossf/presentationagent/blob/main/app/backend/agent/main.py"
  click WH "https://github.com/bbrunossf/presentationagent/blob/main/app/backend/agent/whisper_handler.py"
  click Req "https://github.com/bbrunossf/presentationagent/blob/main/app/backend/agent/requirements.txt"
  click DockerfileAgent "https://github.com/bbrunossf/presentationagent/tree/main/app/backend/Dockerfile"
  click Compose "https://github.com/bbrunossf/presentationagent/blob/main/app/backend/docker-compose.yml"

  classDef ui fill:#D0E8FF,stroke:#0366D6
  classDef backend fill:#D2F8D2,stroke:#28A745
  classDef data fill:#FFEFD5,stroke:#FF8C00
  classDef micro fill:#EDEDED,stroke:#6E6E6E
```
