# rzeldent/esp32-cam-ai architecture

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

- Interactive diagram: https://gitdiagram.com/rzeldent/esp32-cam-ai
- Repository: https://github.com/rzeldent/esp32-cam-ai

## Overview

ESP32-CAM MCP Server exposes camera and device controls to AI assistants and automation clients over MCP. The principal workflow is a client request reaching the firmware’s HTTP/MCP entry point, being dispatched to a tool operation, and returning a structured result or error. The README also describes network recovery/discovery, OTA, diagnostics, and browser CORS support. Most tool handling is in one source file; the excerpts do not show every handler or setup relationship, so unverified links are omitted or marked dashed.

Main entry points: [`src/main.cpp`](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp) (Request Dispatch), [`lib/mcp/mcp.cpp`](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp.cpp) (JSON-RPC Response), [`include/camera_config.h`](https://github.com/rzeldent/esp32-cam-ai/blob/main/include/camera_config.h) (Camera Board Settings), [`lib/mcp/mcp_schema_tool.h`](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp_schema_tool.h) (Tool / Result Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["MCP and HTTP"]
  node_http["HTTP MCP Endpoint<br/>[main.cpp]"]
  node_dispatch["Request Dispatch<br/>[main.cpp]"]
  node_request["JSON-RPC Request Parser<br/>[mcp.cpp]"]
  node_response["JSON-RPC Response<br/>[mcp.cpp]"]
  node_schemas["Tool / Result Schemas<br/>[mcp_schema_tool.h]"]
  node_errors["Protocol Errors<br/>[mcp_schema_error.h]"]
end

subgraph group_tools["Device Tools"]
  node_capture["Camera Capture<br/>[main.cpp]"]
  node_led["LED and Flash Control<br/>[main.cpp]"]
  node_gpio["GPIO Control<br/>[main.cpp]"]
  node_diagnostics["System Diagnostics<br/>[main.cpp]"]
end

subgraph group_device["Hardware Configuration"]
  node_camera_config["Camera Board Settings<br/>[camera_config.h]"]
  node_board_config["LED Board Mapping<br/>[board_config.h]"]
  node_settings["Firmware Defaults<br/>[settings.h]"]
end

subgraph group_network["Connectivity and Reliability"]
  node_wifi["WiFi Connection<br/>[main.cpp]"]
  node_mdns["mDNS Discovery<br/>[main.cpp]"]
  node_ota["OTA Updates<br/>[main.cpp]"]
  node_recovery["Watchdog / Reconnect<br/>[main.cpp]"]
end

node_client(("AI / Automation Client"))
node_browser(("Web Browser"))

node_client -->|"sends MCP requests"| node_http
node_http -->|"routes requests"| node_dispatch
node_dispatch -.->|"parses JSON-RPC"| node_request
node_dispatch -.->|"dispatches capture"| node_capture
node_dispatch -.->|"dispatches controls"| node_led
node_dispatch -.->|"dispatches GPIO"| node_gpio
node_dispatch -.->|"dispatches diagnostics"| node_diagnostics
node_dispatch -->|"builds tool list"| node_schemas
node_capture -.->|"uses camera settings"| node_camera_config
node_capture -.->|"uses capture defaults"| node_settings
node_led -.->|"uses LED mapping"| node_board_config
node_gpio -.->|"checks reserved pins"| node_camera_config
node_dispatch -.->|"creates responses"| node_response
node_dispatch -.->|"reports failures"| node_errors
node_response -.->|"returns JSON-RPC"| node_client
node_http -->|"allows CORS access"| node_browser
node_wifi -.->|"enables discovery"| node_mdns
node_wifi -->|"reconnects on loss"| node_recovery
node_ota -.->|"accepts firmware updates"| node_client
node_recovery -.->|"maintains service"| node_http

click node_http "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_dispatch "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_request "https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp.cpp"
click node_response "https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp.cpp"
click node_schemas "https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp_schema_tool.h"
click node_errors "https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp_schema_error.h"
click node_capture "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_led "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_gpio "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_diagnostics "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_camera_config "https://github.com/rzeldent/esp32-cam-ai/blob/main/include/camera_config.h"
click node_board_config "https://github.com/rzeldent/esp32-cam-ai/blob/main/include/board_config.h"
click node_settings "https://github.com/rzeldent/esp32-cam-ai/blob/main/include/settings.h"
click node_wifi "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_mdns "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_ota "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"
click node_recovery "https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp"

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_http,node_dispatch,node_request,node_response,node_schemas,node_errors,node_client,node_browser toneBlue
class node_capture,node_led,node_gpio,node_diagnostics toneAmber
class node_camera_config,node_board_config,node_settings toneMint
class node_wifi,node_mdns,node_ota,node_recovery toneRose
```

## Components

### MCP and HTTP

- [HTTP MCP Endpoint](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [Request Dispatch](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [JSON-RPC Request Parser](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp.cpp): `lib/mcp/mcp.cpp`
- [JSON-RPC Response](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp.cpp): `lib/mcp/mcp.cpp`
- [Tool / Result Schemas](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp_schema_tool.h): `lib/mcp/mcp_schema_tool.h`
- [Protocol Errors](https://github.com/rzeldent/esp32-cam-ai/blob/main/lib/mcp/mcp_schema_error.h): `lib/mcp/mcp_schema_error.h`

### Device Tools

- [Camera Capture](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [LED and Flash Control](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [GPIO Control](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [System Diagnostics](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`

### Hardware Configuration

- [Camera Board Settings](https://github.com/rzeldent/esp32-cam-ai/blob/main/include/camera_config.h): `include/camera_config.h`
- [LED Board Mapping](https://github.com/rzeldent/esp32-cam-ai/blob/main/include/board_config.h): `include/board_config.h`
- [Firmware Defaults](https://github.com/rzeldent/esp32-cam-ai/blob/main/include/settings.h): `include/settings.h`

### Connectivity and Reliability

- [WiFi Connection](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [mDNS Discovery](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [OTA Updates](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`
- [Watchdog / Reconnect](https://github.com/rzeldent/esp32-cam-ai/blob/main/src/main.cpp): `src/main.cpp`

### Other components

- **AI / Automation Client**
- **Web Browser**

## Connections

- AI / Automation Client → HTTP MCP Endpoint: sends MCP requests (evidence: `README.md`)
- HTTP MCP Endpoint → Request Dispatch: routes requests (evidence: `src/main.cpp`)
- Request Dispatch → JSON-RPC Request Parser: parses JSON-RPC
- Request Dispatch → Camera Capture: dispatches capture (evidence: `src/main.cpp`)
- Request Dispatch → LED and Flash Control: dispatches controls (evidence: `src/main.cpp`)
- Request Dispatch → GPIO Control: dispatches GPIO (evidence: `src/main.cpp`)
- Request Dispatch → System Diagnostics: dispatches diagnostics (evidence: `src/main.cpp`)
- Request Dispatch → Tool / Result Schemas: builds tool list (evidence: `src/main.cpp`)
- Camera Capture → Camera Board Settings: uses camera settings
- Camera Capture → Firmware Defaults: uses capture defaults (evidence: `src/main.cpp`)
- LED and Flash Control → LED Board Mapping: uses LED mapping (evidence: `src/main.cpp`)
- GPIO Control → Camera Board Settings: checks reserved pins
- Request Dispatch → JSON-RPC Response: creates responses
- Request Dispatch → Protocol Errors: reports failures (evidence: `src/main.cpp`)
- JSON-RPC Response → AI / Automation Client: returns JSON-RPC
- HTTP MCP Endpoint → Web Browser: allows CORS access (evidence: `README.md`)
- WiFi Connection → mDNS Discovery: enables discovery (evidence: `src/main.cpp`)
- WiFi Connection → Watchdog / Reconnect: reconnects on loss (evidence: `README.md`)
- OTA Updates → AI / Automation Client: accepts firmware updates
- Watchdog / Reconnect → HTTP MCP Endpoint: maintains service (evidence: `src/main.cpp`)