Monitor App 🚀

Drop in a CSV, write one config file, and get a live-updating Web UI + REST API.

Monitor App is a FastAPI-based data monitoring tool designed for shop floors, labs, and small teams. Define your tables and views declaratively in a single config.py (validated by Pydantic at startup), and Monitor App serves a real-time dashboard, full CRUD REST API with Swagger docs, threshold alerts, and an Andon-style wallboard — no frontend build, no Node.js, fully offline-capable.

日本語のドキュメントは README_ja.md を参照してください。

✨ Features

• CSV → Web app in 3 commands — place CSV files, run the server, see your data
• Type-safe declarative config — tables, views, styles, alerts in one Pydantic-validated config.py; typos are caught at startup with friendly messages (monitor-app check)
• Live-updating views — Server-Sent Events push changes to the browser; polling fallback
• Full REST API — CRUD per table, bulk ingest, automatic Swagger UI at /docs
• SQLite / MySQL / PostgreSQL — switch with a single DATABASE_URL environment variable
• Conditional cell styling — color-code values by thresholds, no code required
• No frontend toolchain — vanilla JS + bundled assets; works on offline factory networks

🏭 Built for the shop floor (v2.1)

🚀 Installation

pip install monitor-app

With Excel export support:

pip install "monitor-app[xlsx]"

🔧 Quick start

# 1. Create a project (config.py + sample CSVs, ready to run)
monitor-app startproject myproject
cd myproject

# 2. Import CSVs and start the server
monitor-app runserver --import-csv

# 3. Open http://127.0.0.1:9990  (Swagger UI at /docs)

CLI commands

📝 Configuration

Everything lives in one config.py. Mistakes are reported at startup, not at runtime:

from monitor_app import (
    AlertRule, CellStyle, ChartDef, FormDef, KioskConfig,
    KpiCard, MonitorConfig, TableDef, Threshold, ViewDef,
)

config = MonitorConfig(
    app_title="Line Monitor",
    refresh_interval_ms=2000,
    # CRUD tables — column types are inferred (or written explicitly)
    tables={
        "measurements": TableDef(
            columns={"id": "int", "ts": "str", "temp": "float"},
            form=FormDef(labels={"temp": "Temperature"}),   # operator entry form
        ),
    },
    # Display views — any SELECT, including JOINs and aggregation
    views={
        "temp_trend": ViewDef(
            query="SELECT ts, temp FROM measurements ORDER BY id",
            title="Temperature trend",
            chart=ChartDef(type="line", x="ts", y="temp", ucl=80, lcl=20),
            styles={"temp": CellStyle(
                greater_than=Threshold(value=80, **{"class": "bg-danger text-white"}),
            )},
        ),
    },
    # Threshold alerts with notifications
    alerts=[
        AlertRule(view="temp_trend", column="temp", op=">", value=80,
                  level="critical", notify=["webhook"]),
    ],
    # KPI cards and Andon wallboard
    kpis={"count": KpiCard(title="Samples", query="SELECT COUNT(*) FROM measurements")},
    kiosk=KioskConfig(rotate_seconds=15, theme="dark"),
)

Environment-specific values (never in config.py) go in .env:

MONITOR_DATABASE_URL=postgresql+pg8000://user:pass@db:5432/monitor   # default: SQLite
MONITOR_API_KEY=change-me            # enables X-API-Key auth on writes
MONITOR_INGEST_WATCH=true            # auto-import csv/ on change
MONITOR_AUDIT_ENABLED=true           # record change history
MONITOR_WEBHOOK_URL=https://hooks.slack.com/services/...

🌐 Endpoints

🔌 External tool integrations (v2.2)

Connect procdiag, netdiag, and network-checker to Monitor App with a few lines — no changes to the external tools required (read-only, pull-based).

from monitor_app.integrations import procdiag, netdiag, network_checker

config = procdiag.attach(config, db_path="/opt/procdiag/data/procdiag.db")
config = netdiag.attach(config)
config = network_checker.attach(config, hosts=["plc-01", "gateway"])

Each attach() call merges tables, views, KPIs, and alert rules into your existing config. Run monitor-app sync-sources to ingest on demand, or set MONITOR_INGEST_WATCH=1 for continuous polling.

Full reference: docs/integrations_v2_2.md

🔄 Migrating from v0.x

v2 was rebuilt on FastAPI + Pydantic. The legacy dict-style config.py (ALLOWED_TABLES / VIEW_TABLES / TABLE_CELL_STYLES) still loads through a compatibility shim, but new projects should use MonitorConfig. Key changes:

• python app.py runserver → monitor-app runserver (the app no longer lives in your project)
• DB settings (DB_TYPE, passwords) → MONITOR_DATABASE_URL environment variable
• API paths: /api/<table> → /api/tables/{table}, /api/view/<v> → /api/views/{view}

Details: redesign notes · v2.1 feature design · v2.2 integrations · v2.3 UI redesign

🐳 Docker

docker build -t monitor-app -f docker/Dockerfile .
docker run -v $(pwd)/myproject:/project -p 9990:9990 monitor-app

🛠 Development

git clone https://github.com/mikawa-bushi/monitor-app.git
cd monitor-app
poetry install
poetry run pytest

Pre-push security & quality checks

A pre-commit config scans for secrets and enforces formatting locally, before code leaves your machine. Enable it once per clone:

poetry run pre-commit install          # installs the commit + pre-push hooks
poetry run pre-commit run --all-files  # optional: run across the repo now

• gitleaks — blocks hard-coded secrets (PyPI/AWS/GCP tokens, GitHub PATs, private keys)
• detect-private-key / check-added-large-files / check-merge-conflict, plus black / ruff (pinned to the CI versions)
• check-commit-identity (pre-push) — rejects commits whose author/committer e-mail is off the allowlist, keeping work/other identities out of history (scripts/check_commit_identity.py; extend via the MONITOR_ALLOWED_EMAILS env var)
• check-ai-traces (commit + pre-push) — flags traces of AI-agent tools (config dirs, file content, commit metadata) so they don't leak into the repo. Tool patterns are data-driven in scripts/check_ai_traces.py (extend the TOOLS list or MONITOR_AI_TRACE_EXTRA; ignore paths via .ai-trace-ignore)

Audit the whole working tree and full git history on demand:

python3 scripts/check_ai_traces.py --all   # exit 0 = no traces found

⚠️ Local hooks can be skipped with git commit/push --no-verify. For an unbypassable gate, also make gitleaks a required GitHub Actions check.

Contributions are welcome — see CONTRIBUTING.md.

📜 License

MIT