# th3heretic/argus architecture

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

- Interactive diagram: https://gitdiagram.com/th3heretic/argus
- Repository: https://github.com/th3heretic/argus

## Overview

Argus Core is a home-security event orchestrator with an administrator-facing dashboard. The main documented flow is a module or adapter sending an event over MQTT; Core validates the source, applies consent and mode policy, stores approved event metadata, and presents events and system state in the dashboard. Registration and device discovery, authentication, auditing, and retention are separate supporting capabilities. The index and README identify several capabilities whose implementation details were not sampled, so their internal wiring is omitted where unverified.

Main entry points: [`core/argus_core/events/service.py`](https://github.com/th3heretic/argus/blob/main/core/argus_core/events/service.py) (Event evaluation), [`core/argus_core/main.py`](https://github.com/th3heretic/argus/blob/main/core/argus_core/main.py) (Core application), [`core/argus_core/storage/event_store.py`](https://github.com/th3heretic/argus/blob/main/core/argus_core/storage/event_store.py) (Event store), [`core/argus_core/registry/store.py`](https://github.com/th3heretic/argus/blob/main/core/argus_core/registry/store.py) (Source registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingress and Discovery"]
  node_mqtt["MQTT ingress<br/>[mqtt_ingress.py]"]
  node_discovery["Device discovery<br/>[service.py]"]
  node_discovery_routes["Discovery API<br/>[router.py]"]
end

subgraph group_governance["Trust and Policy"]
  node_registry_api["Source registry API<br/>[router.py]"]
  node_registry[("Source registry<br/>[store.py]")]
  node_consent["Consent evaluation<br/>[effective.py]"]
  node_consent_store[("Consent settings<br/>[store.py]")]
  node_modes[("Household modes<br/>[store.py]")]
  node_policy["Event policy<br/>[event_policy.py]"]
end

subgraph group_eventdata["Events and Retention"]
  node_event_service["Event evaluation<br/>[service.py]"]
  node_event_api["Events API<br/>[router.py]"]
  node_event_store[("Event store<br/>[event_store.py]")]
  node_retention["Retention service<br/>[service.py]"]
  node_database[("SQLite access<br/>[database.py]")]
end

subgraph group_operations["Admin and Health"]
  node_auth["Admin authentication<br/>[dependencies.py]"]
  node_auth_store[("Accounts and sessions<br/>[store.py]")]
  node_audit[("Audit log<br/>[store.py]")]
  node_health["Source health monitor"]
end

subgraph group_interface["User Interface"]
  node_ui["Admin dashboard<br/>[router.py]"]
  node_core["Core application<br/>[main.py]"]
end

node_module(("Modules / adapters"))

node_module -.->|"sends events"| node_mqtt
node_mqtt -->|"submits events"| node_event_service
node_event_service -->|"checks source"| node_registry
node_event_service -->|"checks consent"| node_consent
node_event_service -->|"reads modes"| node_modes
node_event_service -->|"evaluates policy"| node_policy
node_event_service -->|"stores approved"| node_event_store
node_event_api -->|"invokes evaluation"| node_event_service
node_event_api -->|"reads events"| node_event_store
node_consent -->|"loads settings"| node_consent_store
node_discovery_routes -->|"invokes discovery"| node_discovery
node_discovery -->|"registers devices"| node_registry
node_registry_api -->|"manages sources"| node_registry
node_retention -->|"purges expired"| node_event_store
node_retention -->|"records deletion"| node_audit
node_auth -->|"validates sessions"| node_auth_store
node_ui -->|"loads dashboard events"| node_event_store
node_ui -->|"checks administrator"| node_auth_store
node_health -->|"checks registered sources"| node_registry
node_core -->|"registers ingress"| node_mqtt
node_core -->|"mounts API"| node_event_api
node_core -->|"mounts API"| node_discovery_routes
node_core -->|"mounts API"| node_registry_api
node_core -->|"mounts dashboard"| node_ui
node_database -.->|"provides connections"| node_event_store

click node_mqtt "https://github.com/th3heretic/argus/blob/main/core/argus_core/integrations/mqtt_ingress.py"
click node_discovery "https://github.com/th3heretic/argus/blob/main/core/argus_core/discovery/service.py"
click node_discovery_routes "https://github.com/th3heretic/argus/blob/main/core/argus_core/discovery/router.py"
click node_registry_api "https://github.com/th3heretic/argus/blob/main/core/argus_core/registry/router.py"
click node_registry "https://github.com/th3heretic/argus/blob/main/core/argus_core/registry/store.py"
click node_consent "https://github.com/th3heretic/argus/blob/main/core/argus_core/consent/effective.py"
click node_consent_store "https://github.com/th3heretic/argus/blob/main/core/argus_core/consent/store.py"
click node_modes "https://github.com/th3heretic/argus/blob/main/core/argus_core/modes/store.py"
click node_policy "https://github.com/th3heretic/argus/blob/main/core/argus_core/policy/event_policy.py"
click node_event_service "https://github.com/th3heretic/argus/blob/main/core/argus_core/events/service.py"
click node_event_api "https://github.com/th3heretic/argus/blob/main/core/argus_core/events/router.py"
click node_event_store "https://github.com/th3heretic/argus/blob/main/core/argus_core/storage/event_store.py"
click node_retention "https://github.com/th3heretic/argus/blob/main/core/argus_core/retention/service.py"
click node_database "https://github.com/th3heretic/argus/blob/main/core/argus_core/storage/database.py"
click node_auth "https://github.com/th3heretic/argus/blob/main/core/argus_core/auth/dependencies.py"
click node_auth_store "https://github.com/th3heretic/argus/blob/main/core/argus_core/auth/store.py"
click node_audit "https://github.com/th3heretic/argus/blob/main/core/argus_core/audit/store.py"
click node_health "https://github.com/th3heretic/argus/blob/main/core/argus_core/monitoring/source_health_monitor.py"
click node_ui "https://github.com/th3heretic/argus/blob/main/core/argus_core/ui/router.py"
click node_core "https://github.com/th3heretic/argus/blob/main/core/argus_core/main.py"

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_mqtt,node_discovery,node_discovery_routes toneBlue
class node_registry_api,node_registry,node_consent,node_consent_store,node_modes,node_policy toneAmber
class node_event_service,node_event_api,node_event_store,node_retention,node_database toneMint
class node_auth,node_auth_store,node_audit,node_health toneRose
class node_ui,node_core,node_module toneIndigo
```

## Components

### Ingress and Discovery

- [MQTT ingress](https://github.com/th3heretic/argus/blob/main/core/argus_core/integrations/mqtt_ingress.py): `core/argus_core/integrations/mqtt_ingress.py`
- [Device discovery](https://github.com/th3heretic/argus/blob/main/core/argus_core/discovery/service.py): `core/argus_core/discovery/service.py`
- [Discovery API](https://github.com/th3heretic/argus/blob/main/core/argus_core/discovery/router.py): `core/argus_core/discovery/router.py`

### Trust and Policy

- [Source registry API](https://github.com/th3heretic/argus/blob/main/core/argus_core/registry/router.py): `core/argus_core/registry/router.py`
- [Source registry](https://github.com/th3heretic/argus/blob/main/core/argus_core/registry/store.py): `core/argus_core/registry/store.py`
- [Consent evaluation](https://github.com/th3heretic/argus/blob/main/core/argus_core/consent/effective.py): `core/argus_core/consent/effective.py`
- [Consent settings](https://github.com/th3heretic/argus/blob/main/core/argus_core/consent/store.py): `core/argus_core/consent/store.py`
- [Household modes](https://github.com/th3heretic/argus/blob/main/core/argus_core/modes/store.py): `core/argus_core/modes/store.py`
- [Event policy](https://github.com/th3heretic/argus/blob/main/core/argus_core/policy/event_policy.py): `core/argus_core/policy/event_policy.py`

### Events and Retention

- [Event evaluation](https://github.com/th3heretic/argus/blob/main/core/argus_core/events/service.py): `core/argus_core/events/service.py`
- [Events API](https://github.com/th3heretic/argus/blob/main/core/argus_core/events/router.py): `core/argus_core/events/router.py`
- [Event store](https://github.com/th3heretic/argus/blob/main/core/argus_core/storage/event_store.py): `core/argus_core/storage/event_store.py`
- [Retention service](https://github.com/th3heretic/argus/blob/main/core/argus_core/retention/service.py): `core/argus_core/retention/service.py`
- [SQLite access](https://github.com/th3heretic/argus/blob/main/core/argus_core/storage/database.py): `core/argus_core/storage/database.py`

### Admin and Health

- [Admin authentication](https://github.com/th3heretic/argus/blob/main/core/argus_core/auth/dependencies.py): `core/argus_core/auth/dependencies.py`
- [Accounts and sessions](https://github.com/th3heretic/argus/blob/main/core/argus_core/auth/store.py): `core/argus_core/auth/store.py`
- [Audit log](https://github.com/th3heretic/argus/blob/main/core/argus_core/audit/store.py): `core/argus_core/audit/store.py`
- [Source health monitor](https://github.com/th3heretic/argus/blob/main/core/argus_core/monitoring/source_health_monitor.py): `core/argus_core/monitoring/source_health_monitor.py`

### User Interface

- [Admin dashboard](https://github.com/th3heretic/argus/blob/main/core/argus_core/ui/router.py): `core/argus_core/ui/router.py`
- [Core application](https://github.com/th3heretic/argus/blob/main/core/argus_core/main.py): `core/argus_core/main.py`

### Other components

- **Modules / adapters**

## Connections

- Modules / adapters → MQTT ingress: sends events (evidence: `README.md`)
- MQTT ingress → Event evaluation: submits events (evidence: `core/argus_core/integrations/mqtt_ingress.py`)
- Event evaluation → Source registry: checks source (evidence: `core/argus_core/events/service.py`)
- Event evaluation → Consent evaluation: checks consent (evidence: `core/argus_core/events/service.py`)
- Event evaluation → Household modes: reads modes (evidence: `core/argus_core/events/service.py`)
- Event evaluation → Event policy: evaluates policy (evidence: `core/argus_core/events/service.py`)
- Event evaluation → Event store: stores approved (evidence: `core/argus_core/events/service.py`)
- Events API → Event evaluation: invokes evaluation (evidence: `core/argus_core/events/router.py`)
- Events API → Event store: reads events (evidence: `core/argus_core/events/router.py`)
- Consent evaluation → Consent settings: loads settings (evidence: `core/argus_core/consent/effective.py`)
- Discovery API → Device discovery: invokes discovery (evidence: `core/argus_core/discovery/router.py`)
- Device discovery → Source registry: registers devices (evidence: `core/argus_core/discovery/service.py`)
- Source registry API → Source registry: manages sources (evidence: `core/argus_core/registry/router.py`)
- Retention service → Event store: purges expired (evidence: `core/argus_core/retention/service.py`)
- Retention service → Audit log: records deletion (evidence: `core/argus_core/retention/service.py`)
- Admin authentication → Accounts and sessions: validates sessions (evidence: `core/argus_core/auth/dependencies.py`)
- Admin dashboard → Event store: loads dashboard events (evidence: `core/argus_core/ui/router.py`)
- Admin dashboard → Accounts and sessions: checks administrator (evidence: `core/argus_core/ui/router.py`)
- Source health monitor → Source registry: checks registered sources (evidence: `core/argus_core/monitoring/source_health_monitor.py`)
- Core application → MQTT ingress: registers ingress (evidence: `core/argus_core/main.py`)
- Core application → Events API: mounts API (evidence: `core/argus_core/main.py`)
- Core application → Discovery API: mounts API (evidence: `core/argus_core/main.py`)
- Core application → Source registry API: mounts API (evidence: `core/argus_core/main.py`)
- Core application → Admin dashboard: mounts dashboard (evidence: `core/argus_core/main.py`)
- SQLite access → Event store: provides connections (evidence: `core/argus_core/storage/event_store.py`)