# richard-hajek/environment-overseer architecture

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

- Interactive diagram: https://gitdiagram.com/richard-hajek/environment-overseer
- Repository: https://github.com/richard-hajek/environment-overseer

## Overview

##### Project Components & Layers
- Overseer Daemon Core:
- Central component as a block labeled “Overseer Daemon” (mainly overseer/main.py).
- Within this block, list or include submodules (auto_trigger, forced_activity, interrupt, limit, manager, pre_check, recharge, supermodule) which encapsulate the core decision-making and tracking logic.
- Auxiliary modules like config.py, filesystem.py, and utils.py which support configuration, file management, and shared utilities.

- Activity Scripts & Managers:
- The “checks” scripts (in scripts/checks) add a safety layer, ensuring that even if a user bypasses the daemon’s intervention, there is a fallback that detects tampering.
- Extensions (in scripts/extensions) and additional managers further enhance or customize the overseer's functionality.

- Example Configurations & Test Components:
- A “Examples” block that holds sample configurations (activity JSON files, example scripts) to demonstrate how a user might set up or customize the environment.
- A “Test” block that represents the testing artifacts – e.g., the test/Dockerfile and test/routine.sh that run end-to-end tests.

- Deployment & Integration:
- A “Docker Compose” component (via docker-compose.yml) – since the README instructs running the daemon using Docker for integration testing.
- Also, include a “Systemd Service” block (from systemd/overseer.service) which represents how the daemon might run as a background service on Linux environments.

##### Relationships & Data Flow
- That the daemon interfaces bidirectionally with the “Activity Scripts” (managers, checks, enable/disable scripts), indicating that the daemon can trigger these scripts and also receive status/feedback from them.
- “Configuration/Examples” block to the Overseer core, highlighting that the system reads its configuration (and sample files) from these directories.
- Data flow from the environment (for instance, logging input from Pi-hole or similar monitoring sources indicated by the manager scripts) to the Overseer core, which then triggers the corresponding scripts based on activity status.
- Deployment flow showing that the Docker Compose service coordinates launching the Overseer along with its tests, and that systemd is used for production-level service management.

##### Architectural Patterns & Design Principles
- A modular design, separating the core logic (in overseer/ modules) from external interfaces (scripts in enable/disable, checks, managers).
- Dynamic configuration possibilities and extensibility via the “extensions” modules in the scripts directory.
- Built-in resilience and multi-layer checks (for instance, the “checks” scripts ensuring that the Overseer isn’t tampered with) as part of the design.

##### Relevant Technologies
- Python (the primary language for the daemon).
- Docker (for containerized testing/deployment via docker-compose.yml).
- Systemd (for running the service reliably on Linux).
- Shell scripting (for the empirical scripts handling enabling/disabling and checking activities).
- JSON config files (for activities configuration, located in the examples and test folders).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        OD("Overseer Daemon"):::core
        MODS("Modules (auto_trigger, forced_activity, interrupt, limit, manager, pre_check, recharge, supermodule)"):::core
        CFG("config.py"):::core
        FS("filesystem.py"):::core
        UT("utils.py"):::core
    end

    %% Activity Scripts
    subgraph "Activity Scripts"
        AM("Activity Managers"):::script
        ES("Enable Scripts"):::script
        DS("Disable Scripts"):::script
        CS("Checks Scripts"):::script
        EXMOD("Extensions Modules"):::script
    end

    %% Configuration & Examples
    subgraph "Configuration & Examples"
        CONF("Example Configurations"):::config
    end

    %% Tests
    subgraph "Tests"
        TEST("Test Components"):::test
    end

    %% Deployment & Integration
    subgraph "Deployment & Integration"
        DC("Docker Compose"):::deployment
        SD("Systemd Service"):::deployment
    end

    %% External Environment
    subgraph "External Environment"
        ENV("Environmental Inputs"):::external
    end

    %% Relationships - Core internal links
    OD -->|"contains_submodules"| MODS
    OD -->|"uses"| CFG
    OD -->|"uses"| FS
    OD -->|"uses"| UT

    %% Relationships - External Scripts interactions
    OD -->|"triggers"| AM
    AM -->|"feedback"| OD

    OD -->|"triggers"| ES
    ES -->|"feedback"| OD

    OD -->|"triggers"| DS
    DS -->|"feedback"| OD

    OD -->|"triggers"| CS
    CS -->|"feedback"| OD

    OD -->|"triggers"| EXMOD
    EXMOD -->|"feedback"| OD

    %% Relationships - Configurations
    CONF -->|"provides_config"| OD

    %% Relationships - Environment input
    ENV -->|"sends_input"| OD

    %% Relationships - Deployment & Testing
    DC -->|"deploys"| OD
    DC -->|"deploys_tests"| TEST
    SD -->|"manages"| OD

    %% Click Events
    click OD "https://github.com/richard-hajek/environment-overseer/blob/master/overseer/main.py"
    click MODS "https://github.com/richard-hajek/environment-overseer/tree/master/overseer/modules/"
    click CFG "https://github.com/richard-hajek/environment-overseer/blob/master/overseer/config.py"
    click FS "https://github.com/richard-hajek/environment-overseer/blob/master/overseer/filesystem.py"
    click UT "https://github.com/richard-hajek/environment-overseer/blob/master/overseer/utils.py"
    click AM "https://github.com/richard-hajek/environment-overseer/tree/master/examples/scripts/managers/"
    click ES "https://github.com/richard-hajek/environment-overseer/tree/master/examples/scripts/enable/"
    click DS "https://github.com/richard-hajek/environment-overseer/tree/master/examples/scripts/disable/"
    click CS "https://github.com/richard-hajek/environment-overseer/tree/master/examples/scripts/checks/"
    click EXMOD "https://github.com/richard-hajek/environment-overseer/tree/master/examples/scripts/extensions/"
    click CONF "https://github.com/richard-hajek/environment-overseer/tree/master/examples/activities/"
    click TEST "https://github.com/richard-hajek/environment-overseer/tree/master/test/"
    click DC "https://github.com/richard-hajek/environment-overseer/blob/master/docker-compose.yml"
    click SD "https://github.com/richard-hajek/environment-overseer/blob/master/systemd/overseer.service"

    %% Styles
    classDef core fill:#FFDDC1,stroke:#D2691E,stroke-width:2px
    classDef script fill:#C1FFC1,stroke:#228B22,stroke-width:2px
    classDef config fill:#C1D4FF,stroke:#00008B,stroke-width:2px
    classDef test fill:#FFE4C4,stroke:#CD853F,stroke-width:2px
    classDef deployment fill:#FFB6C1,stroke:#8B0000,stroke-width:2px
    classDef external fill:#E6E6FA,stroke:#4B0082,stroke-width:2px
```
