# njgraham/things2c architecture

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

- Interactive diagram: https://gitdiagram.com/njgraham/things2c
- Repository: https://github.com/njgraham/things2c

## Overview

##### Project type and purpose
- This is an IoT surveillance/notification system built around Raspberry Pis. It uses NFC tags to arm/disarm motion detection, records video on motion events, publishes messages via MQTT, controls an LED indicator, uploads video clips to S3 or ownCloud, and pushes mobile alerts via Pushover.
- Its primary purpose is home monitoring: turning off motion alerts when the owner’s NFC keyfob is present, flashing a status LED, recording clips, pushing notifications, and storing video.

##### File structure
- Top‐level scripts and configs:
- Dockerfile_broker, Dockerfile_motion, Dockerfile_things2c: containerize Mosquitto, Motion daemon, and the things2c Python tool.
- build_*.sh, run_*.sh: build and launch containers.
- config.py, version.py: shared configuration and version info.
- deployment/ subdirectory:
- ansible playbook (playbook.yml) plus service config fragments for mosquitto, motion, motionctl, nfc_scan, blinkctl, filemanager, watchdog.
- hosts example, udev rules for the NFC reader.
- Python modules and CLI:
- things2c.py: entry point with subcommands (nfc_scan, motionctl, watchdog, blinkctl, notify, publish, snoop, filemanager).
- mqtt_client.py: abstracts MQTT publish/subscribe.
- nfc_interface.py, nfc_write_rnd.py: read NFC tags.
- pushover_notify.py: mobile alerts.
- file_manager.py: upload/delete video clips.
- Shell helpers: update_motion_conf.sh.
- Requirements.txt lists dependencies like nfcpy, blink(1) tools, mosquitto client, etc.

##### README for additional insights
- High‐level design: NFC reader and motion sensor feed into things2c via MQTT. things2c orchestrates state, notifies via Pushover, controls blink(1), triggers uploads.
- External services: Amazon S3 or ownCloud for storage, Pushover for mobile push.
- Deployment uses Docker optionally and Ansible.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Interfaces"
        direction TB
        NFCReader["USB NFC Reader"]:::hardware
        Webcam["USB Webcam"]:::hardware
        LEDDevice["USB blink(1) LED"]:::hardware
    end

    %% Raspberry Pi Host
    subgraph "Raspberry Pi Host"
        direction TB

        %% Docker Containers
        subgraph "MQTT Broker Container"
            direction TB
            Broker["MQTT Broker<br/>(Mosquitto)"]:::broker
        end

        subgraph "Motion Daemon Container"
            direction TB
            MotionDaemon["Motion Daemon<br/>(motion)"]:::service
        end

        subgraph "things2c Controller Container"
            direction TB
            Controller["things2c Controller"]:::controller
            subgraph Processes
                direction TB
                NFCScan["NFC Scanner<br/>(nfc_scan)"]:::process
                MotionCtl["Motion Control<br/>(motionctl)"]:::process
                Watchdog["Watchdog"]:::process
                BlinkCtl["LED Controller<br/>(blinkctl)"]:::process
                Notify["Notification<br/>(pushover_notify)"]:::process
                FileManager["File Manager<br/>(file_manager)"]:::process
                MQTTClient["MQTT Client<br/>(mqtt_client)"]:::library
            end
        end
    end

    %% Cloud Services
    subgraph "Cloud Services"
        direction TB
        S3["S3 / ownCloud Storage"]:::storage
        Pushover["Pushover API"]:::external
    end

    %% Flows
    NFCReader -->|nfc/present, nfc/absent| NFCScan
    NFCScan -->|publish| Broker
    Webcam --> MotionDaemon
    MotionDaemon -->|motion/detected| Broker

    Broker -->|subscribe| NFCScan
    Broker -->|subscribe| MotionCtl
    Broker -->|subscribe| Watchdog
    Broker -->|subscribe| BlinkCtl
    Broker -->|subscribe| Notify
    Broker -->|subscribe| FileManager

    MotionCtl -->|arm/disarm commands| BlinkCtl
    MotionCtl -->|trigger upload| FileManager
    MotionCtl -->|trigger notify| Notify

    BlinkCtl --> LEDDevice
    FileManager -->|HTTPS POST/PUT| S3
    Notify -->|push| Pushover

    %% Click Events
    click Broker "https://github.com/njgraham/things2c/tree/master/Dockerfile_broker"
    click MotionDaemon "https://github.com/njgraham/things2c/tree/master/Dockerfile_motion"
    click Controller "https://github.com/njgraham/things2c/tree/master/Dockerfile_things2c"
    click NFCScan "https://github.com/njgraham/things2c/blob/master/deployment/nfc_scan.conf"
    click MotionCtl "https://github.com/njgraham/things2c/blob/master/deployment/motionctl.conf"
    click Watchdog "https://github.com/njgraham/things2c/blob/master/deployment/watchdog.conf"
    click BlinkCtl "https://github.com/njgraham/things2c/blob/master/deployment/blinkctl.conf"
    click Notify "https://github.com/njgraham/things2c/blob/master/pushover_notify.py"
    click FileManager "https://github.com/njgraham/things2c/blob/master/deployment/filemanager.conf"
    click MQTTClient "https://github.com/njgraham/things2c/blob/master/mqtt_client.py"

    %% Styles
    classDef hardware fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef broker fill:#d0e0ff,stroke:#00f,stroke-width:1px
    classDef service fill:#e8e8e8,stroke:#888,stroke-width:1px
    classDef controller fill:#ccffcc,stroke:#090,stroke-width:1px
    classDef process fill:#c8f7c5,stroke:#070,stroke-width:1px
    classDef library fill:#fff0b3,stroke:#aa0,stroke-width:1px
    classDef storage fill:#f0f0f0,stroke:#666,stroke-width:1px
    classDef external fill:#ffe0b3,stroke:#f80,stroke-width:1px
```
