MonsterOps logo MonsterOps
Docs / Reference / Architecture

Architecture

Overview

MonsterOps is a modular FastAPI application with a vanilla-JS frontend. Each feature area is a self-contained module — a mini FastAPI router with its own models, schemas, and frontend bundle. Enabling or disabling a module is a config change; disabled modules are never imported.

Layout

monsterops/
├── app.py                  # FastAPI application factory
├── config.py               # Settings (env-based, pydantic-settings)
├── database.py             # Async SQLAlchemy engine + session
├── events.py               # In-process event bus
├── cli.py                  # `monsterops` command-line entry point
├── plugins/                # Plugin loader & registry
├── modules/                # Built-in feature modules (each a mini FastAPI router)
│   ├── auth/               # Admin auth, JWT, RBAC, audit log
│   ├── dashboard/
│   ├── users/ groups/ nas/ nas_manager/ ip_pools/
│   ├── accounting/ auth_logs/ radius_logs/ reports/
│   ├── realms/             # RADIUS proxy & realm management
│   ├── vpn/                # WireGuard + L2TP/IPsec tunnels
│   ├── firewall/           # nftables firewall manager (safe apply + rollback)
│   ├── automation/ scheduler/ webhooks/ notifications/ integrations/
│   ├── apikeys/ system/ health/
└── static/                 # Vanilla JS frontend (ES Modules + Web Components)
    ├── index.html
    ├── js/  (app.js, router.js, api.js, components/)
    └── css/theme.css       # Design tokens — single source of truth

Module contract

Every module exposes a router (FastAPI APIRouter), models.py (SQLAlchemy), schemas.py (Pydantic), and static/manifest.json (which declares the frontend nav entries and JS bundle). This is also the contract that plugins follow.

Request pipeline

Request → Security Headers MW → Auth dependency → Permission dependency → Router → Service → Database

Roles are enforced by the permission dependency server-side on every route, not just hidden in the UI (see Roles).

Frontend

The UI is vanilla JS — ES Modules + Web Components, no build step. static/css/theme.css is the single source of truth for the visual language; CSS custom properties inherit through the Shadow DOM, so changing one token reskins every component at once. (This site reuses those same tokens.)