# OrbitalWard Progress

Last updated: 2026-05-23

## Current State

OrbitalWard has a working Docker Compose development stack with PostgreSQL, Redis, FastAPI backend, Python worker, and React/Vite frontend.

Implemented foundation:

- Monorepo layout, README, MIT license, Dockerfiles, Compose files, helper scripts, and initial docs.
- FastAPI backend with health endpoint, JWT login, local initial owner bootstrap, and role checks.
- SQLAlchemy models and Alembic initial migration for users, assets, credentials, monitors, check results, metrics, alert rules, incidents, notification channels, and audit events.
- React frontend with login, authenticated shell, dashboard, assets, websites, alerts, notifications, and placeholder admin/discovery/graphs/credentials pages.
- Worker process that polls HTTP website monitors, records check results, updates monitor/asset status, opens incidents, resolves incidents on recovery, and sends webhook notifications.

Implemented website-monitor slice:

- Create, edit, delete website monitors from the UI.
- HTTP status and expected-text checks.
- Optional TLS certificate expiry checks for HTTPS monitors.
- Monitor status and recent incident visibility on dashboard.
- Basic alert rules created with website monitors.
- Incidents can be acknowledged and silenced from the UI.
- Deleting a monitor resolves any open incidents tied to that monitor.

Implemented network-monitor slice:

- Create, edit, delete ping and TCP port monitors from the UI.
- Worker performs ICMP ping checks and TCP connection checks.
- Ping and TCP monitors use the same alert rule, incident, recovery, and notification flow as website monitors.
- Dashboard monitor status includes website, ping, and TCP monitors.

Implemented notification slice:

- Create, edit, test, and delete notification channels from the UI.
- Generic webhook, Mattermost, and Zoom Team Chat channel types.
- Webhook URLs encrypted at rest using `ORBITALWARD_SECRET_KEY`.
- Saved webhook URLs are not returned to the UI.
- Configurable post username per notification channel.
- Worker sends incident open and recovery notifications.
- Notification state/history is stored in incident details to avoid duplicate sends.

Implemented alerting management slice:

- Alerts page lists alert rules separately from incidents.
- Alert rules can be enabled, disabled, and edited from the UI.
- Editable alert rule fields include friendly name, severity, failure threshold, and cooldown.
- HTTPS website alert rules expose TLS certificate expiry check and warning-day controls.
- Existing simple alert conditions are shown in friendly language instead of raw condition data.
- Worker honors alert rule cooldown before opening a new incident for a recently-triggered rule.

Implemented monitor and notification test coverage:

- Test fixtures isolate API tests with an in-memory database and authenticated owner override.
- Website monitor tests cover asset creation, default alert rule creation, TLS config persistence, and disabled default alerts.
- Notification channel tests verify saved webhook URLs are encrypted and are not returned by create, list, or update responses.
- Worker scheduler tests cover alert threshold incident opening, recovery resolution, notification history deduplication, and alert cooldown behavior.

## Known Gaps

- Credential vault UI and real credential encryption workflows are not complete.
- Audit logging tables exist, but events are not consistently written yet.
- User management UI is not implemented.
- Role management is basic and needs full admin flows.
- Richer alert condition editing is not implemented yet.
- Guided SNMP device discovery and friendly SNMP monitor selection are not implemented yet.
- SNMP credential profiles, interface status, traffic counters, errors, uptime, CPU, and memory checks are not implemented yet.
- Notification routing/policies are not implemented; all enabled webhook channels receive incident notifications.
- Email/SMTP notifications are not implemented yet.
- Graphing exists only as placeholders; metric visualization is not implemented.
- Worker scheduling is simple polling, not a Redis queue yet.
- Tests still need frontend coverage and broader edge-case coverage across monitor types.
- Production deployment hardening is not done.

## Recommended Next Work

1. Add SNMP credential profiles and guided SNMP device discovery.
2. Add SNMP discovery selection UI to choose what to monitor and alert on.
3. Add SNMP interface status, traffic, errors, uptime, CPU, and memory collection.
4. Add notification policy/routing controls.
5. Add email/SMTP notification channel.
6. Add audit event writes for auth, monitor, credential, notification, and incident actions.
7. Build credential vault UI with masked secret handling.
8. Add user administration UI.
9. Add graphs for website response time and monitor status history.
10. Add richer alert condition editing.
11. Add frontend coverage for monitor, alert, and notification workflows.

## Operational Notes

Development URLs:

- Frontend: `http://localhost:5173`
- Backend API: `http://localhost:8000`
- API docs: `http://localhost:8000/docs`

Default local login comes from `.env`:

- `INITIAL_ADMIN_EMAIL=admin@example.com`
- `INITIAL_ADMIN_PASSWORD=change-me`

Change these values before using OrbitalWard outside local development.