Files

T

2GT-RichandClaude Opus 5 e10f7ba568 docs: split reference material into docs/, keeping the README a shop window (v0.23.4-beta)

Documentation only — no functional change.

The README was carrying two jobs for two different readers. Its Reference section was
the single largest block at 154 lines, and nobody deciding whether to try the project
reads an InfluxDB environment variable table — while the people who need it were
scrolling past the pitch to reach it.

Split along that seam: anything you would read before installing stays in the README,
anything you would read after installing moves to docs/.

  README.md              430 lines   sell, prove, install, feature overview
  docs/change-guard.md   193         safety system, settings, guard states
  docs/architecture.md   116         data stores, polling model, module layout
  docs/capsman.md         84         role model, radio matching, current limits
  docs/alerting.md        81         rules, channels, webhooks, maintenance windows
  docs/api.md             77         scoped tokens, preflight, scripting
  docs/configuration.md   76         environment, secrets, rotation, TLS
  docs/sso-oidc.md        71         identity provider setup and behaviour
  docs/README.md          20         index

In-repo rather than a documentation site, deliberately. A change to Change Guard's
semantics can edit its documentation in the same commit as the code — which, given how
often that behaviour has been refined recently, is the property that actually matters.
A static site generator can point at docs/ later without moving a file.

The Change Guard pitch stays on the front page: the problem framing, the verified
recovery timeline and the quoted prediction warning are what make someone care, and a
reference page is the wrong home for them.

Three sections are new rather than relocated, written because the split exposed the gaps:

  - architecture.md did not exist. It now records why there are three data stores, the
    polling cadences, and which modules are pure functions over a snapshot and why.
  - Scoped API tokens shipped without usage documentation. api.md shows preflighting a
    change from a script and reading the guard block afterwards.
  - change-guard.md records why ip-on-bridge-port is informational rather than critical
    on RouterOS 7 — reasoning that previously existed only in a commit message.

Every internal anchor and cross-file link verified to resolve, including anchors into
other documents. No content dropped, checked by keyword comparison against the previous
single file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-21 12:26:18 -07:00

5.0 KiB

Raw Blame History

Architecture

← Documentation index

For contributors, and for anyone wanting to know what happens between the UI and a device.

The shape of it

Browser ──► nginx ──► Express API ──► RouterOS API / SSH ──► devices
                          │
                          ├──► PostgreSQL   current state, config, users, audit
                          ├──► InfluxDB     time-series metrics
                          └──► Redis        job queue and locks

Three data stores, because they answer different questions:

Store	Holds	Why not the others
PostgreSQL	Devices, interfaces, VLANs, clients, users, audit log, findings	Relational, needs joins and constraints
InfluxDB	CPU, memory, traffic, client counts, RF quality	Time-series at poll cadence; would bloat Postgres
Redis	BullMQ job queues, per-device locks, poll gating	Ephemeral, needs atomic operations

Polling

A scheduler enqueues work per device on separate cadences, so a slow operation never delays a fast one:

Cycle	Default	Collects
Fast	30s	Reachability, CPU, memory, traffic counters, clients
Slow	5min	Interfaces, VLANs, addresses, neighbours, STP, wireless, CAPsMAN
Logs	60s	Device log entries, feeding log alerts
Config snapshot	60min	`/export`, deduplicated by content hash
Config health	60min	Read-only configuration audit
MAC / spectral / AP scan	configurable	Switch MAC tables, RF surveys

Devices are probed once for wireless capability and the result recorded, so non-wireless devices are skipped cheaply on every later poll.

Device communication

RouterOSClient speaks the RouterOS binary API (8728, or 8729 with TLS). It is used for essentially everything, including the safety machinery, because many deployments never configure SSH.

SSH is used only where RouterOS offers no API equivalent — /export for config snapshots, binary backup retrieval, packet capture download, and the in-browser terminal.

Where the interesting logic lives

backend/src/services/
├── mikrotik/
│   ├── RouterOSClient.ts     binary protocol client
│   ├── DeviceCollector.ts    all collection and device mutation
│   └── capsman.ts            role detection, radio matching  (pure)
├── changeGuard/
│   ├── ChangeGuard.ts        restore point, scheduler, verify, commit
│   ├── pathModel.ts          live snapshot, management-path resolution  (pure)
│   ├── invariants.ts         what must hold for management to survive  (pure)
│   ├── analyzeChange.ts      simulate a change, diff the invariants  (pure)
│   └── configHealth.ts       standing audit rules  (pure)
├── topology/
│   └── buildTopology.ts      neighbour graph construction  (pure)
├── netflow/                  NetFlow v9 / IPFIX collector and aggregator
└── PollerService.ts          scheduling and workers

Anything marked pure is a function over a snapshot with no I/O. That is deliberate: this logic is subtle, its failure mode is a plausible-looking wrong answer rather than a crash, and it must be testable without the hardware it reasons about. Those modules carry the bulk of the test suite.

Repository layout

mikrotik-manager/
├── frontend/               # React + TypeScript (Vite)
│   └── src/
│       ├── pages/          # One component per route
│       ├── components/     # Shared UI
│       ├── services/       # API client (Axios)
│       ├── hooks/          # Custom React hooks
│       └── types/          # TypeScript definitions
│
├── backend/                # Node.js + Express + TypeScript
│   └── src/
│       ├── routes/         # REST API handlers
│       ├── services/       # See above
│       ├── db/             # Schema and migrations
│       ├── config/         # Database, InfluxDB, Redis connections
│       ├── middleware/     # Auth, audit logging, error handling
│       └── utils/          # Crypto, OUI lookup, VLAN parsing
│
├── docs/                   # This documentation
├── nginx/                  # Reverse proxy config and Dockerfile
├── scripts/                # CI preflight and tooling
├── docker-compose.yml      # Build from source
├── docker-compose.ghcr.yml # Pre-built images
└── .env.example

Database migrations

A single idempotent SQL script in backend/src/db/migrate.ts runs on every backend start. Statements are written to be safe to re-run — CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS, and guarded constraint swaps — so upgrading is just starting the new image.

Before you push

scripts/ci-preflight.sh runs the same gates as CI — lint, type-check, build, tests and production audits for both packages — in about 35 seconds. Running it locally is faster than finding out from a red badge.

5.0 KiB Raw Blame History