# greogory/hibp-checker architecture

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

- Interactive diagram: https://gitdiagram.com/greogory/hibp-checker
- Repository: https://github.com/greogory/hibp-checker

## Overview

##### Project Type and Purpose
- This is an open-source security automation tool (“HIBP Comprehensive Checker”) written in Python and Bash, with an optional Flask-based web dashboard.
- Purpose: Automate Have I Been Pwned (HIBP) breach and credential-stuffing checks for one or many emails and passwords, produce reports (text/JSON/CSV), and provide a real-time dashboard. It supports native Linux scheduling (systemd/cron) and cross-platform Docker deployment.

##### File Structure Analysis
- **Root scripts & binaries**
- `hibp_comprehensive_checker.py` – core Python engine that calls HIBP APIs
- `hibp_workflow.sh` – Bash CLI wrapper for setup, check, schedule, email management
- `quick_start.sh`, `multi_email_setup.sh` – helper scripts for initial configuration
- **Configuration & orchestration**
- `hibp_config.conf.example` – sample config used by both Python and Bash scripts
- `docker-compose.yml` + `docker-compose.scheduled.yml`, `Dockerfile` – container builds and multi-service composition
- **Web Dashboard** (`dashboard/`)
- `app.py` – Flask application entry point
- `templates/index.html` – UI definition
- `start-dashboard.*` scripts & `systemd/hibp-dashboard.service` – service definitions for Linux
- **Scheduling & automation**
- `systemd/` – timers and service units for Linux native scheduling
- `scripts/` – cron/systemd setup helpers
- **CI/CD & GitHub**
- `.github/workflows/` – auto-approve, auto-merge, security checks, Docker publish pipelines
- **Documentation & guides**
- `README.md`, `DOCKER.md`, `WINDOWS_INSTALL.md`, `SCHEDULING.md`, etc.

##### Key Components
a. **Core Engine** – Python script (`hibp_comprehensive_checker.py`) that:
- Reads config (env vars or `hibp_config.conf`)
- Calls external HIBP APIs (breaches, stealer logs, pastes, pwned-passwords)
- Generates reports to local filesystem
b. **CLI Workflow** – Bash wrapper (`hibp_workflow.sh`)
- Provides commands: setup, check, schedule, email management
- Orchestrates engine execution and triggers follow-up actions
c. **Scheduler**
- Linux: systemd services (`.timer` + `.service`) and cron (via `scripts/setup-cron.sh`)
- Docker: `docker-compose.scheduled.yml` runs scheduled container jobs
d. **Web Dashboard**
- Flask app (dashboard/app.py) serving real-time stats, logs, and report browser
- Reads report files and logs from shared volume or host paths
e. **External Services**
- Have I Been Pwned API v3 endpoints
f. **Deployment Environments**
- Native Linux (systemd, cron)
- Docker (multi-container compose)
- Windows/macOS via Docker
- WSL2 on Windows

##### Component Relationships and Data Flow
1. **Scheduler → CLI Workflow**: systemd/cron/docker-scheduler triggers `hibp_workflow.sh schedule/check`.
2. **CLI Workflow → Core Engine**: wrapper invokes Python script with parameters.
3. **Core Engine ↔ HIBP API**: REST calls to breach, paste, stealer log, and pwned-passwords endpoints.
4. **Core Engine → Filesystem**: writes scan results (reports) and logs.
5. **Web Dashboard → Filesystem**: reads results and logs; serves HTML UI to user’s browser.
6. **User Browser ↔ Web Dashboard**: HTTP interaction over port 5000 or container mapping.
7. **CI/CD Pipelines** (GitHub Actions) build Docker image and publish; can also trigger security checks via CLI.

##### Architectural Patterns and Principles
- **Separation of Concerns**:
- Core logic (Python) separated from orchestration (Bash) and presentation (Flask)
- **Modularity & Composability**:
- Independent scripts for setup, check, scheduling, dashboard
- Docker Compose for cross-platform deployment
- **Infrastructure as Code**:
- systemd units and cron scripts in version control
- GitHub Actions workflows for CI/CD
- **3-Tier-ish Structure**:
- Presentation (Flask UI)
- Application Logic (Python/Bash)
- Data (reports/log files + external API)

##### Detail Level
- Conditional paths (e.g., Docker compose scheduled vs. manual cron).
- Shared volumes or host-container mounts for report/log access.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        AA["auto-approve.yml"]:::ci
        AB["auto-merge.yml"]:::ci
        AC["docker-publish.yml"]:::ci
        AD["security-checks.yml"]:::ci
    end
    AA -->|triggers| AB
    AB -->|triggers| AC
    AD -->|runs CLI checks| CLI

    %% Docker Deployment
    subgraph "Docker Deployment"
        direction TB
        DockerfileNode["Dockerfile"]:::docker
        Compose["docker-compose.yml & docker-compose.scheduled.yml"]:::docker
    end
    AC -->|build image| DockerfileNode
    DockerfileNode -->|compose up| Compose
    Compose -->|schedules container jobs| CLI

    %% Native Linux Scheduling
    subgraph "Native Linux Scheduling"
        direction TB
        SystemdService["hibp-checker.service"]:::scheduler
        SystemdTimer1["hibp-checker.timer"]:::scheduler
        SystemdTimer2["hibp-checker-weekly.timer"]:::scheduler
        ScriptsCron["setup-cron.sh"]:::scheduler
        ScriptsSystemd["setup-systemd.sh"]:::scheduler
    end
    SystemdTimer1 --> SystemdService
    SystemdTimer2 --> SystemdService
    SystemdService -->|invokes| CLI
    ScriptsCron -->|configures cron| CLI
    ScriptsSystemd -->|configures systemd| CLI

    %% Core Components
    CLI["CLI Workflow\n(hibp_workflow.sh)"]:::bash
    CoreEngine["Core Engine\n(hibp_comprehensive_checker.py)"]:::python
    Config["Config Sample\n(hibp_config.conf.example)"]:::config

    CLI -->|calls| CoreEngine
    CLI -->|reads| Config
    CoreEngine -->|reads| Config

    %% External API and Data
    CoreEngine -->|REST calls| HIBPAPI["HIBP API v3 Endpoints"]:::external
    CoreEngine -->|writes reports/logs| Filesystem["Filesystem\n(Reports & Logs)"]:::data

    %% Web Dashboard
    subgraph "Web Dashboard"
        direction TB
        DashboardApp["dashboard/app.py"]:::web
        Template["templates/index.html"]:::web
        StartDash1["start-dashboard.sh"]:::web
        StartDash2["start-dashboard-macos.sh"]:::web
        StartDash3["start-dashboard.ps1"]:::web
        DashService["hibp-dashboard.service"]:::scheduler
    end
    Filesystem -->|reads| DashboardApp
    Template --> DashboardApp
    StartDash1 --> DashboardApp
    StartDash2 --> DashboardApp
    StartDash3 --> DashboardApp
    DashService --> DashboardApp
    Browser["User Browser"]:::external
    Browser -->|HTTP| DashboardApp

    %% Click Events
    click CLI "https://github.com/greogory/hibp-checker/blob/main/hibp_workflow.sh"
    click CoreEngine "https://github.com/greogory/hibp-checker/blob/main/hibp_comprehensive_checker.py"
    click Config "https://github.com/greogory/hibp-checker/blob/main/hibp_config.conf.example"
    click DockerfileNode "https://github.com/greogory/hibp-checker/tree/main/Dockerfile"
    click Compose "https://github.com/greogory/hibp-checker/blob/main/docker-compose.yml"
    click Compose "https://github.com/greogory/hibp-checker/blob/main/docker-compose.scheduled.yml"
    click SystemdService "https://github.com/greogory/hibp-checker/blob/main/systemd/hibp-checker.service"
    click SystemdTimer1 "https://github.com/greogory/hibp-checker/blob/main/systemd/hibp-checker.timer"
    click SystemdTimer2 "https://github.com/greogory/hibp-checker/blob/main/systemd/hibp-checker-weekly.timer"
    click ScriptsCron "https://github.com/greogory/hibp-checker/blob/main/scripts/setup-cron.sh"
    click ScriptsSystemd "https://github.com/greogory/hibp-checker/blob/main/scripts/setup-systemd.sh"
    click DashboardApp "https://github.com/greogory/hibp-checker/blob/main/dashboard/app.py"
    click Template "https://github.com/greogory/hibp-checker/blob/main/dashboard/templates/index.html"
    click StartDash1 "https://github.com/greogory/hibp-checker/blob/main/dashboard/start-dashboard.sh"
    click StartDash2 "https://github.com/greogory/hibp-checker/blob/main/dashboard/start-dashboard-macos.sh"
    click StartDash3 "https://github.com/greogory/hibp-checker/blob/main/dashboard/start-dashboard.ps1"
    click DashService "https://github.com/greogory/hibp-checker/blob/main/dashboard/systemd/hibp-dashboard.service"
    click AA "https://github.com/greogory/hibp-checker/blob/main/.github/workflows/auto-approve.yml"
    click AB "https://github.com/greogory/hibp-checker/blob/main/.github/workflows/auto-merge.yml"
    click AC "https://github.com/greogory/hibp-checker/blob/main/.github/workflows/docker-publish.yml"
    click AD "https://github.com/greogory/hibp-checker/blob/main/.github/workflows/security-checks.yml"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef bash fill:#98FB98,stroke:#000,stroke-width:1px
    classDef scheduler fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef web fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef docker fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#000,stroke-width:1px
    classDef ci fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef external fill:#F08080,stroke:#000,stroke-width:1px
```
