# anthony-faria-dos-santos/project-motion-detection-system architecture

> Architecture diagram of the GitHub repository anthony-faria-dos-santos/project-motion-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthony-faria-dos-santos/project-motion-detection-system
- Repository: https://github.com/anthony-faria-dos-santos/project-motion-detection-system

## Overview

##### Project Type & Purpose
- Full-stack Python “edge” application for 24/7 motion detection
- Uses OpenCV for image capture/processing, Slack for alerts, and Google Cloud Storage (GCS) for long-term storage

##### High-Level Architectural Components
a. Hardware/Input Layer
- Webcam (video feed)
b. Core Application Layer
- main.py – orchestrator
- Motion Detection module (OpenCV code inside main.py)
- Manager (handles interval & area threshold logic)
c. Utility/Integration Layer
- utils/slack_utils.py – Slack API wrapper
- utils/gcs_utils.py – GCS API wrapper
d. Local Storage
- captures/ directory (temporary local image storage)
e. External Services
- Slack API (chat.postMessage & files.upload endpoints)
- Google Cloud Storage (bucket for captured images)
f. Configuration & Environment
- .env (environment variables via python-dotenv)
- reload_venv.sh (ensures .env is loaded in virtualenv)
g. Test & Validation
- test_connections.py – verifies Slack & GCS connectivity

##### Interactions & Data Flow
1. Startup
– main.py loads .env → config object
2. Frame Capture
– main.py opens webcam (OpenCV VideoCapture)
– Streams frames into Motion Detection subroutine
3. Detection Logic
– Compute difference between frames → threshold + contour area
– If motion detected & capture interval elapsed:
a. Save frame locally → captures/<timestamp>.jpg
b. Call slack_utils.upload_image() → Slack channel
c. Call gcs_utils.upload_blob() → GCS bucket
4. Continuous Loop
– Repeat 2–3 until user quits (Q key)
5. Error Handling & Logging
– try/except around camera, API calls, upload tasks → console logs

##### Architectural Patterns & Principles
- Single-process, modular design
- Layered separation: Capture & Detection → Notification → Storage
- Utility modules isolate 3rd-party API logic (SRP)
- Environment-driven configuration (12-factor principle)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware/Input Layer
    subgraph "Hardware/Input Layer"
        Camera["📷 Webcam"]:::external
    end

    %% Core Application Layer
    subgraph "Core Application Layer"
        Main["main.py\n(Orchestrator)"]:::code
        MotionDetector["Motion Detector\n(OpenCV)"]:::code
        CaptureManager["Capture Manager\n(interval & area logic)"]:::code
    end

    %% Integration Layer
    subgraph "Integration Layer"
        SlackUploader["Slack Uploader\nutils/slack_utils.py"]:::code
        GCSUploader["GCS Uploader\nutils/gcs_utils.py"]:::code
    end

    %% Local Storage
    LocalStorage["captures/\n(Local Storage)"]:::storage

    %% External Services
    SlackAPI["☁️ Slack API"]:::external
    GCSService["☁️ Google Cloud Storage"]:::external

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        EnvFile[".env.example"]:::config
        ReloadScript["reload_venv.sh"]:::config
    end

    %% Environment Inspector
    ShowConfig["show_config.py"]:::code

    %% Connectivity Tests
    TestConnections["test_connections.py"]:::test

    %% Dependencies
    subgraph "Dependencies"
        Requirements["requirements.txt"]:::code
        Setup["setup.py"]:::code
    end

    %% Documentation & Metadata
    subgraph "Documentation & Metadata"
        README["README.md"]:::code
        README_FR["README_FR.md"]:::code
        LICENSE["LICENSE"]:::code
        NOTICE["NOTICE"]:::code
        GITIGNORE[".gitignore"]:::code
    end

    %% Data Flows
    Camera -->|"Video Frame\n(OpenCV)"| Main
    Main -->|"frame→analysis"| MotionDetector
    MotionDetector -->|"motion detected?"| CaptureManager
    CaptureManager -->|"Image File"| LocalStorage
    CaptureManager -->|"Image File"| SlackUploader
    CaptureManager -->|"Image File"| GCSUploader
    SlackUploader -->|"POST files.upload\nrequests"| SlackAPI
    GCSUploader -->|"upload_blob\ngoogle-cloud-storage"| GCSService
    EnvFile --> Main
    ReloadScript --> Main
    EnvFile --> SlackUploader
    EnvFile --> GCSUploader
    EnvFile --> ShowConfig
    ShowConfig -->|"inspect config"| Main
    EnvFile --> TestConnections
    TestConnections -->|"test Slack"| SlackAPI
    TestConnections -->|"test GCS"| GCSService
    Requirements --> Main
    Requirements --> SlackUploader
    Requirements --> GCSUploader
    Requirements --> TestConnections
    Setup --> Requirements
    Documentation --> Requirements

    %% Click Events
    click Main "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/main.py"
    click SlackUploader "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/utils/slack_utils.py"
    click GCSUploader "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/utils/gcs_utils.py"
    click LocalStorage "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/tree/main/captures/"
    click EnvFile "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/.env.example"
    click ReloadScript "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/reload_venv.sh"
    click ShowConfig "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/show_config.py"
    click TestConnections "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/test_connections.py"
    click Requirements "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/requirements.txt"
    click Setup "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/setup.py"
    click README "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/README.md"
    click README_FR "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/README_FR.md"
    click LICENSE "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/tree/main/LICENSE"
    click NOTICE "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/tree/main/NOTICE"
    click GITIGNORE "https://github.com/anthony-faria-dos-santos/project-motion-detection-system/blob/main/.gitignore"

    %% Styles
    classDef code fill:#e0ffe0,stroke:#2f6627,stroke-width:1px
    classDef storage fill:#e0f0ff,stroke:#1a4d8f,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#b35e00,stroke-width:1px
    classDef config fill:#f0f0f0,stroke:#555,stroke-width:1px
    classDef test fill:#f5e6ff,stroke:#5f259f,stroke-width:1px
```
