# ogaradinest/wash_agent architecture

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

- Interactive diagram: https://gitdiagram.com/ogaradinest/wash_agent
- Repository: https://github.com/ogaradinest/wash_agent

## Overview

1. **Overall shape**
   - This repo is a **two-tier application**: a **Python backend** in `backend/` and a **React frontend** in `frontend/`.
   - The frontend is the primary user interface; the backend appears to provide the API and server-side logic behind it.

2. **Frontend application shell**
   - The frontend is a **single-page React app** built with **CRACO** (`frontend/craco.config.js`) and styled with **Tailwind CSS** (`tailwind.config.js`, `postcss.config.js`).
   - Entry points are `frontend/src/index.js` and `frontend/src/App.js`, with global styling in `App.css` and `index.css`.

3. **UI and page structure**
   - The main app surface is organized into pages: `LandingPage.jsx` and `Dashboard.jsx`.
   - Reusable feature components include `AICallDemo.jsx` and `CallLogDetail.jsx`, suggesting the app centers on an AI call/demo workflow plus call history or inspection.
   - The large `frontend/src/components/ui/` folder is a design-system layer of reusable controls (buttons, dialogs, tables, tabs, toast, etc.), likely built on a component library pattern.

4. **Frontend data flow**
   - The UI likely follows a simple flow: landing page entry → dashboard interaction → detailed call views and notifications.
   - Shared client-side helpers live in `frontend/src/lib/utils.js`, and transient UI state/feedback is handled via toast hooks in `frontend/src/hooks/use-toast.js`.

5. **Frontend development-time extensions**
   - `frontend/plugins/health-check/` adds custom **health endpoints** and a **webpack health plugin**, indicating the frontend dev server exposes operational checks beyond the normal app bundle.
   - `frontend/plugins/visual-edits/` contains Babel/dev-server plugins that support a **visual editing workflow** or metadata injection during development, so the frontend build is not just static bundling but also developer tooling-aware.

6. **Backend service boundary**
   - `backend/server.py` is the runtime entry for the Python service.
   - `backend/requirements.txt` defines the backend runtime dependencies, and `backend_test.py` indicates direct testing of backend behavior.
   - The backend is the clear boundary for server-side APIs, health checks, and any AI/call-related logic that the frontend consumes.

7. **Testing and validation**
   - There are separate repo-level test artifacts: `backend_test.py`, `tests/`, and `test_reports/`.
   - The presence of iteration-based JSON reports suggests repeated evaluation runs or benchmark-style validation, not just ad hoc unit tests.

8. **Deployment pipeline**
   - `.github/workflows/deploy.yml` is the primary CI/CD path and likely builds the frontend, validates the backend, and publishes the application.
   - This implies a deployment boundary where the frontend build artifacts and backend service are promoted together or in coordinated steps.

9. **Project guidance and product context**
   - `memory/PRD.md` and `design_guidelines.json` provide product/design constraints that influence implementation but are not runtime components.
   - They likely define the intended behavior and UI consistency for the app’s main flows.

10. **What to draw in an architecture diagram**
   - Show a **browser client** talking to a **React SPA**.
   - Show the SPA depending on a **Python API server** for dynamic data/actions.
   - Add a **development-only tooling lane** for health checks and visual-edit plugins on the frontend.
   - Add a **CI/CD lane** from GitHub Actions into deployment, with tests and reports as quality gates.

Main entry points: [`frontend/src/App.js`](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/App.js) (React SPA), [`backend/server.py`](https://github.com/ogaradinest/wash_agent/blob/main/backend/server.py) (Python Server), [`.github/workflows/deploy.yml`](https://github.com/ogaradinest/wash_agent/blob/main/.github/workflows/deploy.yml) (Deploy Workflow), [`frontend/src/pages/Dashboard.jsx`](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_client["Client UI"]
  node_browser(("Browser<br/>user client"))
  node_frontend_shell["React SPA<br/>frontend app<br/>[App.js]"]
  node_frontend_boot["App Entry<br/>bootstrap<br/>[index.js]"]
  node_landing_page["Landing Page<br/>[LandingPage.jsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_ai_demo["AI Demo<br/>feature<br/>[AICallDemo.jsx]"]
  node_call_log["Call Log<br/>feature<br/>[CallLogDetail.jsx]"]
  node_ui_kit["UI Kit<br/>design system"]
  node_toast_state["Toast State<br/>client state<br/>[use-toast.js]"]
  node_utils["Client Utils<br/>helpers<br/>[utils.js]"]
  node_styles["Styles<br/>styling<br/>[App.css]"]
end

subgraph group_g_backend["Backend Service"]
  node_backend_server["Python Server<br/>api server<br/>[server.py]"]
  node_backend_deps["Backend Deps<br/>runtime deps<br/>[requirements.txt]"]
end

subgraph group_g_tooling["Frontend Tooling"]
  node_health_plugin["Health Plugin<br/>dev plugin"]
  node_health_endpoints["Health Endpoints<br/>dev endpoints"]
  node_visual_edits["Visual Edits<br/>dev tooling"]
end

subgraph group_g_delivery["Quality & Delivery"]
  node_tests["Tests<br/>validation"]
  node_test_reports["Reports<br/>validation artifacts"]
  node_ci_cd["Deploy Workflow<br/>ci/cd<br/>[deploy.yml]"]
end

subgraph group_g_context["Product Context"]
  node_prd["PRD<br/>product docs<br/>[PRD.md]"]
  node_design_guidelines["Design Guide<br/>product docs"]
end

node_browser -->|"loads"| node_frontend_boot
node_frontend_boot -->|"mounts"| node_frontend_shell
node_frontend_shell -->|"routes"| node_landing_page
node_frontend_shell -->|"routes"| node_dashboard_page
node_dashboard_page -->|"uses"| node_ai_demo
node_dashboard_page -->|"uses"| node_call_log
node_frontend_shell -->|"composes"| node_ui_kit
node_frontend_shell -->|"notifies"| node_toast_state
node_frontend_shell -->|"shares"| node_utils
node_frontend_shell -->|"styles"| node_styles
node_frontend_shell -->|"api calls"| node_backend_server
node_frontend_shell -.->|"dev support"| node_health_plugin
node_health_plugin -->|"exposes"| node_health_endpoints
node_frontend_shell -.->|"dev support"| node_visual_edits
node_backend_server -->|"depends on"| node_backend_deps
node_backend_server -->|"validated by"| node_tests
node_tests -->|"produces"| node_test_reports
node_ci_cd -->|"runs"| node_tests
node_ci_cd -->|"deploys"| node_backend_server
node_ci_cd -->|"builds"| node_frontend_shell
node_prd -.->|"guides"| node_frontend_shell
node_design_guidelines -.->|"guides"| node_ui_kit

click node_frontend_shell "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/App.js"
click node_frontend_boot "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/index.js"
click node_landing_page "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/pages/LandingPage.jsx"
click node_dashboard_page "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/pages/Dashboard.jsx"
click node_ai_demo "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/components/AICallDemo.jsx"
click node_call_log "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/components/CallLogDetail.jsx"
click node_ui_kit "https://github.com/ogaradinest/wash_agent/tree/main/frontend/src/components/ui"
click node_toast_state "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/hooks/use-toast.js"
click node_utils "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/lib/utils.js"
click node_styles "https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/App.css"
click node_health_plugin "https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/health-check/webpack-health-plugin.js"
click node_health_endpoints "https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/health-check/health-endpoints.js"
click node_visual_edits "https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/visual-edits/dev-server-setup.js"
click node_backend_server "https://github.com/ogaradinest/wash_agent/blob/main/backend/server.py"
click node_backend_deps "https://github.com/ogaradinest/wash_agent/blob/main/backend/requirements.txt"
click node_tests "https://github.com/ogaradinest/wash_agent/tree/main/tests"
click node_test_reports "https://github.com/ogaradinest/wash_agent/tree/main/test_reports"
click node_ci_cd "https://github.com/ogaradinest/wash_agent/blob/main/.github/workflows/deploy.yml"
click node_prd "https://github.com/ogaradinest/wash_agent/blob/main/memory/PRD.md"
click node_design_guidelines "https://github.com/ogaradinest/wash_agent/blob/main/design_guidelines.json"

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_browser,node_frontend_shell,node_frontend_boot,node_landing_page,node_dashboard_page,node_ai_demo,node_call_log,node_ui_kit,node_toast_state,node_utils,node_styles toneBlue
class node_backend_server,node_backend_deps toneAmber
class node_health_plugin,node_health_endpoints,node_visual_edits toneMint
class node_tests,node_test_reports,node_ci_cd toneRose
class node_prd,node_design_guidelines toneIndigo
```

## Components

### Client UI

React single-page application and its runtime surface.

- **Browser**: user client · End-user entry point for the app.
- [React SPA](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/App.js): frontend app · Main single-page application shell built with React and CRACO. · `frontend/src/App.js`
- [App Entry](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/index.js): bootstrap · Client startup and root mounting. · `frontend/src/index.js`
- [Landing Page](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/pages/LandingPage.jsx): page · Initial public-facing page. · `frontend/src/pages/LandingPage.jsx`
- [Dashboard](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/pages/Dashboard.jsx): page · Primary interactive workspace. · `frontend/src/pages/Dashboard.jsx`
- [AI Demo](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/components/AICallDemo.jsx): feature · Core AI call/demo workflow UI. · `frontend/src/components/AICallDemo.jsx`
- [Call Log](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/components/CallLogDetail.jsx): feature · Call detail and inspection view. · `frontend/src/components/CallLogDetail.jsx`
- [UI Kit](https://github.com/ogaradinest/wash_agent/tree/main/frontend/src/components/ui): design system · Reusable component primitives and controls. · `frontend/src/components/ui`
- [Toast State](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/hooks/use-toast.js): client state · Transient feedback and notification handling. · `frontend/src/hooks/use-toast.js`
- [Client Utils](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/lib/utils.js): helpers · Shared frontend utility helpers. · `frontend/src/lib/utils.js`
- [Styles](https://github.com/ogaradinest/wash_agent/blob/main/frontend/src/App.css): styling · Global app styles and Tailwind/PostCSS setup. · `frontend/src/App.css`

### Backend Service

Python server and its service boundary.

- [Python Server](https://github.com/ogaradinest/wash_agent/blob/main/backend/server.py): api server · Backend runtime entry point and server-side logic. · `backend/server.py`
- [Backend Deps](https://github.com/ogaradinest/wash_agent/blob/main/backend/requirements.txt): runtime deps · Python dependency set for the backend service. · `backend/requirements.txt`

### Frontend Tooling

Development-time plugins and build customization.

- [Health Plugin](https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/health-check/webpack-health-plugin.js): dev plugin · Custom frontend health-check integration. · `frontend/plugins/health-check/webpack-health-plugin.js`
- [Health Endpoints](https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/health-check/health-endpoints.js): dev endpoints · Operational endpoints used during frontend development. · `frontend/plugins/health-check/health-endpoints.js`
- [Visual Edits](https://github.com/ogaradinest/wash_agent/blob/main/frontend/plugins/visual-edits/dev-server-setup.js): dev tooling · Babel and dev-server support for visual editing workflows. · `frontend/plugins/visual-edits/dev-server-setup.js`

### Quality & Delivery

Tests, reports, and CI/CD automation.

- [Tests](https://github.com/ogaradinest/wash_agent/tree/main/tests): validation · Repository-level backend and integration test coverage. · `tests`
- [Reports](https://github.com/ogaradinest/wash_agent/tree/main/test_reports): validation artifacts · Iteration-based evaluation and test outputs. · `test_reports`
- [Deploy Workflow](https://github.com/ogaradinest/wash_agent/blob/main/.github/workflows/deploy.yml): ci/cd · GitHub Actions deployment pipeline. · `.github/workflows/deploy.yml`

### Product Context

Docs and design constraints that guide implementation.

- [PRD](https://github.com/ogaradinest/wash_agent/blob/main/memory/PRD.md): product docs · Product requirements and behavior guidance. · `memory/PRD.md`
- [Design Guide](https://github.com/ogaradinest/wash_agent/blob/main/design_guidelines.json): product docs · UI and implementation constraints. · `design_guidelines.json`

## Connections

- Browser → App Entry: loads · Browser opens the app entrypoint.
- App Entry → React SPA: mounts · Client bootstrap renders the main React app.
- React SPA → Landing Page: routes · App exposes the landing surface.
- React SPA → Dashboard: routes · App exposes the main dashboard.
- Dashboard → AI Demo: uses · Dashboard hosts the core AI call workflow.
- Dashboard → Call Log: uses · Dashboard shows call details and history.
- React SPA → UI Kit: composes · App screens are built from reusable UI primitives.
- React SPA → Toast State: notifies · App uses toast feedback for transient status.
- React SPA → Client Utils: shares · Common helpers support client logic.
- React SPA → Styles: styles · Global styling and Tailwind configuration shape the shell.
- React SPA → Python Server: api calls · Frontend depends on backend data and actions.
- React SPA → Health Plugin: dev support · Frontend build includes health-check tooling.
- Health Plugin → Health Endpoints: exposes · Plugin wires operational endpoints into dev runtime.
- React SPA → Visual Edits: dev support · Frontend build includes visual-edit workflow tooling.
- Python Server → Backend Deps: depends on · Backend runtime is defined by Python dependencies.
- Python Server → Tests: validated by · Backend behavior is covered by test execution.
- Tests → Reports: produces · Test runs generate iteration reports and artifacts.
- Deploy Workflow → Tests: runs · Deployment workflow gates on validation.
- Deploy Workflow → Python Server: deploys · Workflow promotes the backend service.
- Deploy Workflow → React SPA: builds · Workflow builds and ships the frontend app.
- PRD → React SPA: guides · Product requirements inform app behavior.
- Design Guide → UI Kit: guides · Design constraints influence reusable UI primitives.