# thevickypedia/jarvismonitor architecture

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

- Interactive diagram: https://gitdiagram.com/thevickypedia/jarvismonitor
- Repository: https://github.com/thevickypedia/jarvismonitor

## Overview

##### Project type and purpose
- JarvisMonitor is a background monitoring service (a specialized backend tool) that periodically checks the health of Jarvis processes, generates an HTML status page (and optional email notification), and publishes it via GitHub Pages.

##### File structure
- Top-level scripts:
- run.py – entry point called by cron.
- monitor.py – contains the core monitoring logic.
- templates/ – Jinja2 templates for web and email reports.
- docs/ – output directory; committed to the docs branch for GitHub Pages.
- .github/workflows/ – GitHub Actions to build/cleanup the docs branch.
- requirements.txt – dependencies (GitPython, Jinja2, PyYAML, etc.).

##### README for additional insights
- Monitored processes come from a source_map YAML file (generated by Jarvis).
- Environment variables drive configuration (Git credentials, Gmail creds, schedule overrides).
- The service is intended to run every minute via a crontab entry.
- On each run it:
a. Reads the source_map file.
b. Checks process statuses.
c. Renders HTML using Jinja templates.
d. Optionally emails the report.
e. Commits and pushes to GitHub Pages via GitPython/GitHub API.

##### Main components & interactions (to include
a. Scheduler (Cron)
– Triggers run.py every minute.
b. JarvisMonitor Application (run.py → monitor.py → models → templates)
1. Configuration Loader (env vars)
2. YAML Reader (models/helper.py)
3. Health Checker (monitor.py)
4. Renderer (Jinja2 templates in templates/)
5. Output Writers:
- File Writer → docs/index.html
- Email Sender (SMTP) → Gmail service (conditional)
6. Git Publisher (GitPython / GitHub API) → pushes docs/ to docs branch
c. External Dependencies
– Source Map File (processes.yaml generated by Jarvis)
– GitHub (repo, docs branch → GitHub Pages)
– Gmail SMTP (optional email notifications)

##### Architectural patterns & principles
- Pipeline pattern: Read → Process → Render → Publish.
- Single Responsibility: each module (models, monitor, templating, Git ops, email) has a clear role.
- External integration: decoupled via environment variables.
- Static site generation: output is pure HTML served by GitHub Pages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Scheduler
    Cron("Cron Scheduler"):::external

    %% Application Entry Point
    Run["run.py"]:::internal

    %% Subgraph for application internals
    subgraph "JarvisMonitor App"
        direction TB
        Config["Configuration Loader<br/>(env vars)"]:::internal
        YAMLReader["YAML Reader<br/>(models/helper.py)"]:::internal
        HealthCheck["Health Checker<br/>(monitor.py)"]:::internal
        Renderer["Renderer<br/>(Jinja2 Templates)"]:::internal
        FileWriter["File Writer<br/>(docs/index.html)"]:::data
        EmailSender["Email Sender<br/>(SMTP)"]:::external
        GitPublisher["Git Publisher<br/>(GitPython/GitHub API)"]:::internal
    end

    %% External Data Sources & Services
    SourceMap["Source Map YAML<br/>(processes.yaml)"]:::data
    Gmail["Gmail SMTP"]:::external
    GitHubAPI["GitHub API / Repo"]:::external
    GitHubPages["GitHub Pages<br/>(docs branch)"]:::external

    %% Dependencies & Metadata
    Requirements["requirements.txt"]:::internal
    GitIgnore[".gitignore"]:::internal
    PreCommit[".pre-commit-config.yaml"]:::internal
    Readme["README.md"]:::internal
    WorkflowsStatic["static.yml"]:::internal
    WorkflowsCleanup["cleanup.yml"]:::internal
    WorkflowsDelete["delete.yml"]:::internal
    DocsDir["docs/"]:::data

    %% Connections
    Cron -->|"triggers"| Run
    Run -->|reads env vars| Config
    Config -->|configs| YAMLReader
    YAMLReader -->|reads| SourceMap
    YAMLReader -->|parses| HealthCheck
    HealthCheck -->|checks processes| SourceMap
    HealthCheck -->|status data| Renderer
    Renderer -->|renders HTML| FileWriter
    Renderer -->|renders email| EmailSender
    FileWriter -->|writes to| DocsDir
    EmailSender -->|sends via SMTP| Gmail
    FileWriter -->|staged docs| GitPublisher
    GitPublisher -->|pushes docs branch| GitHubAPI
    GitHubAPI -->|publishes site| GitHubPages

    %% Click Events
    click Run "https://github.com/thevickypedia/jarvismonitor/blob/main/run.py"
    click YAMLReader "https://github.com/thevickypedia/jarvismonitor/blob/main/models/helper.py"
    click HealthCheck "https://github.com/thevickypedia/jarvismonitor/blob/main/monitor.py"
    click Config "https://github.com/thevickypedia/jarvismonitor/blob/main/run.py"
    click Requirements "https://github.com/thevickypedia/jarvismonitor/blob/main/requirements.txt"
    click GitIgnore "https://github.com/thevickypedia/jarvismonitor/blob/main/.gitignore"
    click PreCommit "https://github.com/thevickypedia/jarvismonitor/blob/main/.pre-commit-config.yaml"
    click Readme "https://github.com/thevickypedia/jarvismonitor/blob/main/README.md"
    click WorkflowsStatic "https://github.com/thevickypedia/jarvismonitor/blob/main/.github/workflows/static.yml"
    click WorkflowsCleanup "https://github.com/thevickypedia/jarvismonitor/blob/main/.github/workflows/cleanup.yml"
    click WorkflowsDelete "https://github.com/thevickypedia/jarvismonitor/blob/main/.github/workflows/delete.yml"
    click DocsDir "https://github.com/thevickypedia/jarvismonitor/tree/main/docs/"
    click Renderer "https://github.com/thevickypedia/jarvismonitor/blob/main/templates/web_template.html"
    click EmailSender "https://github.com/thevickypedia/jarvismonitor/blob/main/templates/email_template.html"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#2b6cb0,color:#1a365d
    classDef external fill:#d4edda,stroke:#276749,color:#22543d
    classDef data fill:#fff3cd,stroke:#9a6700,color:#744210
```
