# herrera-dev/pircam_telegrambot_espcam architecture

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

- Interactive diagram: https://gitdiagram.com/herrera-dev/pircam_telegrambot_espcam
- Repository: https://github.com/herrera-dev/pircam_telegrambot_espcam

## Overview

##### Main Components
- Hardware:
- ESP32-CAM Board (the central processing and camera module).
- PIR Sensor (for motion detection).
- Power Management Unit (showing battery, TP4056, step-up converter, and external power inputs).
- Auxiliary components: LED indicators and any connection pins (note “pines_cam.h” serves as a pinout reference).
- Software/Firmware:
- Boot & Configuration Module: Responsible for loading stored configurations (token, WiFi credentials, user list) at startup; if not found, triggers WiFiManager’s AP mode.
- Telegram Bot Handler: Handles incoming Telegram commands (/estado, /foto, /VIGILAR, etc.), formats responses, and sends notifications.
- Camera & Sensor Handler: Manages image capture when the PIR sensor detects motion.
- Power Management / Deep Sleep Controller: Controls low-power state (deep sleep) and wakeup based on motion or timer.
- OTA Update Module: Enables over-the-air firmware updates.
- Debug Module: Implements remote debugging through TelnetStream.
- External Interactions:
- Telegram Servers (for receiving commands and sending images/status updates).
- Possibly additional services for battery monitoring or sensor diagnostics.

##### Relationships and Interactions
- On power-up, the Boot & Configuration module loads configuration data. If configuration data is missing (like the bot token or WiFi details), it activates WiFiManager in AP mode for reconfiguration.
- Once configured, the device connects to the user’s WiFi network. The Telegram Bot Handler then initiates a connection with the Telegram servers.
- The PIR sensor continuously monitors for motion. When motion is detected, the Camera & Sensor Handler captures an image.
- The captured image and status data (e.g., battery level or system state) are sent to registered users via the Telegram Bot Handler.
- Additionally, OTA updates can be triggered remotely, allowing firmware maintenance without physical access.
- The Debug Module (via TelnetStream) provides real-time diagnostics and logging information which can be crucial for troubleshooting.

##### Architectural Patterns & Design Principles
- Modularity: The firmware is designed as separate modules (configuration, sensor handling, bot communication) that clearly define responsibilities.
- Event-Driven Architecture: Events such as motion detection or incoming Telegram commands drive the flows within the system.
- Resilience & Fault Handling: The system is designed to handle missing configurations by switching to AP mode and includes fallback mechanisms (like disabling watchdog timers in some error cases).
- Energy Efficiency: Utilizes deep sleep modes for low-power operation especially when running on battery.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Hardware Components
    subgraph "Hardware"
        HW1["ESP32-CAM Board"]:::hardware
        HW2["PIR Sensor"]:::hardware
        HW3["Power Management Unit"]:::hardware
        HW4["LED Indicators"]:::hardware
        HW5["Pinout Reference"]:::hardware
    end

    %% Firmware Modules
    subgraph "Firmware Modules"
        FW1["Boot & Configuration Module"]:::firmware
        FW2["Telegram Bot Handler"]:::firmware
        FW3["Camera & Sensor Handler"]:::firmware
        FW4["OTA Update Module"]:::firmware
        FW5["Debug Module (TelnetStream)"]:::firmware
    end

    %% External Services
    subgraph "External Services"
        EXT1["Telegram Servers"]:::external
    end

    %% Connections - Hardware to Firmware
    HW1 -->|"Power_On"| FW1

    %% Firmware flow
    FW1 -->|"ConfigComplete"| FW2
    HW2 -->|"MotionDetected"| FW3
    FW3 -->|"ImageData"| FW2
    FW2 -->|"NotifyTelegram"| EXT1
    FW2 -->|"OTACommand"| FW4

    %% Debug logging from modules to Debug Module
    FW1 -->|"DebugLog"| FW5
    FW2 -->|"DebugLog"| FW5
    FW3 -->|"DebugLog"| FW5
    FW4 -->|"DebugLog"| FW5

    %% Styling Classes
    classDef hardware fill:#9ecae1, stroke:#2171b5, stroke-width:2px;
    classDef firmware fill:#a1d99b, stroke:#31a354, stroke-width:2px;
    classDef external fill:#fdd0a2, stroke:#e6550d, stroke-width:2px;

    %% Click Events
    click HW5 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/pines_cam.h"
    click FW1 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/PirCam_TelegramBot_ESPCAM.ino"
    click FW2 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/PirCam_TelegramBot_ESPCAM.ino"
    click FW3 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/PirCam_TelegramBot_ESPCAM.ino"
    click FW4 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/config_OTA.hpp"
    click FW5 "https://github.com/herrera-dev/pircam_telegrambot_espcam/blob/main/PirCam_TelegramBot_ESPCAM.ino"
```
