# 0xethano/bbb-security-cam architecture

> Architecture diagram of the GitHub repository 0xethano/bbb-security-cam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xethano/bbb-security-cam
- Repository: https://github.com/0xethano/bbb-security-cam

## Overview

This repository packages a BeagleBone Black security-camera system: Motion detects activity, a separate FFmpeg process maintains a rolling video buffer, and event capture preserves footage to removable storage. Camera services are controlled and managed on the device, while WireGuard and host hardening constrain remote access. The README documents these runtime relationships; no source excerpts were provided, so script-level call details and some service wiring are not represented.

Main entry points: [`appliance/motion/motion.conf`](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/motion/motion.conf) (Motion detection), [`appliance/wireguard/bbb_wg0.conf.example`](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/wireguard/bbb_wg0.conf.example) (WireGuard peers), [`appliance/security-cam/save-event.sh`](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/save-event.sh) (Event collector), [`appliance/security-cam/security-cam-ctl`](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/security-cam-ctl) (Camera control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and recording"]
  node_motion["Motion detection<br/>[motion.conf]"]
  node_ffmpeg["FFmpeg segmenter"]
  node_ring[("Rolling buffer")]
  node_collector["Event collector<br/>[save-event.sh]"]
  node_ring_service["Segment service"]
  node_ring_script["Segment runner<br/>[segment-ring.sh]"]
end

subgraph group_storage["Storage and operations"]
  node_saved[("Saved events")]
  node_prune["Event pruning"]
  node_prune_service["Prune schedule"]
  node_control["Camera control"]
end

subgraph group_security["Network security"]
  node_wireguard["WireGuard peers"]
  node_firewall["Firewall rules<br/>[nftables.conf]"]
  node_hardening["Host hardening<br/>[setup-hardening.sh]"]
  node_ssh["SSH restrictions<br/>[sshd-security.conf]"]
end

node_webcam(("USB webcam"))
node_remote(("VPN administrator"))

node_webcam -->|"supplies video"| node_motion
node_motion -->|"serves MJPG"| node_ffmpeg
node_ffmpeg -->|"writes segments"| node_ring
node_motion -->|"triggers capture"| node_collector
node_collector -->|"preserves recent segments"| node_ring
node_collector -->|"writes events"| node_saved
node_ring_service -.->|"runs"| node_ring_script
node_prune_service -.->|"schedules"| node_prune
node_prune -->|"prunes recordings"| node_saved
node_remote -->|"connects through"| node_wireguard
node_wireguard -->|"permits peer access"| node_ssh
node_wireguard -->|"permits stream access"| node_motion
node_firewall -->|"restricts ingress"| node_wireguard
node_hardening -.->|"configures"| node_firewall
node_control -->|"controls service"| node_motion
node_control -->|"controls service"| node_ring_service

click node_motion "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/motion/motion.conf"
click node_collector "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/save-event.sh"
click node_ring_service "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/segment-ring.service"
click node_ring_script "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/segment-ring.sh"
click node_prune "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/prune-saved-events.sh"
click node_prune_service "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/prune-saved-events.timer"
click node_control "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/security-cam-ctl"
click node_wireguard "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/wireguard/bbb_wg0.conf.example"
click node_firewall "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/nftables.conf"
click node_hardening "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/setup-hardening.sh"
click node_ssh "https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/sshd-security.conf"

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_motion,node_ffmpeg,node_ring,node_collector,node_ring_service,node_ring_script toneBlue
class node_saved,node_prune,node_prune_service,node_control toneAmber
class node_wireguard,node_firewall,node_hardening,node_ssh toneMint
class node_webcam,node_remote toneIndigo
```

## Components

### Capture and recording

- [Motion detection](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/motion/motion.conf): `appliance/motion/motion.conf`
- **FFmpeg segmenter**
- **Rolling buffer**
- [Event collector](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/save-event.sh): `appliance/security-cam/save-event.sh`
- [Segment service](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/segment-ring.service): `appliance/security-cam/segment-ring.service`
- [Segment runner](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/segment-ring.sh): `appliance/security-cam/segment-ring.sh`

### Storage and operations

- **Saved events**
- [Event pruning](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/prune-saved-events.sh): `appliance/security-cam/prune-saved-events.sh`
- [Prune schedule](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/prune-saved-events.timer): `appliance/security-cam/prune-saved-events.timer`
- [Camera control](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/security-cam/security-cam-ctl): `appliance/security-cam/security-cam-ctl`

### Network security

- [WireGuard peers](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/wireguard/bbb_wg0.conf.example): `appliance/wireguard/bbb_wg0.conf.example`
- [Firewall rules](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/nftables.conf): `appliance/hardening/nftables.conf`
- [Host hardening](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/setup-hardening.sh): `appliance/hardening/setup-hardening.sh`
- [SSH restrictions](https://github.com/0xethano/bbb-security-cam/blob/main/appliance/hardening/sshd-security.conf): `appliance/hardening/sshd-security.conf`

### Other components

- **USB webcam**
- **VPN administrator**

## Connections

- USB webcam → Motion detection: supplies video (evidence: `README.md`)
- Motion detection → FFmpeg segmenter: serves MJPG (evidence: `README.md`)
- FFmpeg segmenter → Rolling buffer: writes segments (evidence: `README.md`)
- Motion detection → Event collector: triggers capture (evidence: `README.md`)
- Event collector → Rolling buffer: preserves recent segments (evidence: `README.md`)
- Event collector → Saved events: writes events (evidence: `README.md`)
- Segment service → Segment runner: runs
- Prune schedule → Event pruning: schedules
- Event pruning → Saved events: prunes recordings (evidence: `README.md`)
- VPN administrator → WireGuard peers: connects through (evidence: `README.md`)
- WireGuard peers → SSH restrictions: permits peer access (evidence: `README.md`)
- WireGuard peers → Motion detection: permits stream access (evidence: `README.md`)
- Firewall rules → WireGuard peers: restricts ingress (evidence: `README.md`)
- Host hardening → Firewall rules: configures
- Camera control → Motion detection: controls service (evidence: `README.md`)
- Camera control → Segment service: controls service (evidence: `README.md`)
