How richard-hajek/environment-overseer works
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).