Metro Warden

Industrial dark metro map Network Operations Centre — Python Textual TUI

Metro Warden is a keyboard-driven terminal UI for monitoring network interfaces, routing tables, firewall rules, DNS health, and system resources. It is built on Textual and follows a pub/sub event-bus architecture with a single source of truth state store and a plugin system.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        MetroWarden (App)                    │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────────────┐ │
│  │ EventBus │  │StateStore │  │    PluginRegistry         │ │
│  │ pub/sub  │◄─│ reactive  │  │ network dns firewall sys  │ │
│  └──────────┘  └───────────┘  └──────────────────────────┘ │
│       ▲                ▲                  │                  │
│       │                │    publishes     │                  │
│  ┌────┴───────────────────────────────┐  │                  │
│  │              UI Tabs               │◄─┘                  │
│  │  Lines · Routes · Signals          │                      │
│  │  Chronicle · Registry · Garrison   │                      │
│  │  Settings                          │                      │
│  └────────────────────────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

Core

Module	Purpose
core/bus.py	Asyncio pub/sub event bus with wildcard topic support
core/state.py	Reactive state store; watchers + bus publication on change
core/registry.py	Plugin discovery, loading, lifecycle management
core/app.py	Main MetroWarden(App) class — wires everything together

Plugins

Plugin	Topics published
network	network.interfaces, network.stats
dns	dns.resolvers, dns.health, dns.query.result
firewall	firewall.rules, firewall.chains
system	system.cpu, system.memory, system.disk, system.load, system.snapshot

Tabs

Tab	Key	Content
Lines	1	Network interfaces — name, status, IP, RX/TX
Routes	2	System routing table
Signals	3	Live scrolling event monitor
Chronicle	4	Persistent log viewer with filtering
Registry	5	Plugin status and toggle
Garrison	6	Firewall chains and rules
Settings	7	Configuration form

---

Installation

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -e ".[dev]"

Running

python main.py

# With debug logging
python main.py --debug

# Log to file
python main.py --log-file metro-warden.log

# Custom config
python main.py --config /path/to/config.toml

Or via the installed script:

metro-warden

Keybindings

Key	Action
1–7	Switch tab
q	Quit
Ctrl+R	Reload all plugins
r	Refresh current tab (where supported)
c	Clear log (Signals / Chronicle)
p	Pause Signals stream
f	Focus filter input (Chronicle)
Enter	Toggle plugin load (Registry)
s	Save settings (Settings)

Testing

pytest
pytest --cov

Configuration

Edit config/defaults.toml to adjust poll intervals, enable/disable plugins, and set display limits. The Settings tab writes back to this file on save.

Theme

The industrial dark metro map aesthetic uses:

Role	Colour
Background	#1a1a2e deep charcoal
Surface / panels	#16213e
Primary / electric blue	#00d4ff
Active / green	#00ff88
Warning / amber	#ff8c00
Error / red	#ff4444

CSS overrides live in assets/styles/metro.tcss.