Agent Handoff Notes

Last updated: 2026-05-24

Current Identity

Product name: OrbitalWard
Local repository path: /home/ksmith/projects/OrbitalWard
Git remote: https://git.firebugit.com/ksmith/OrbitalWard.git
Main branch: main
Latest pushed commit: check origin/main with git log -1 --oneline origin/main

The project was previously named InfraPulse. Do not reintroduce the old name in product copy, package names, environment variables, service names, or docs unless explicitly discussing historical context.

Gitea Access

Gitea API base: https://git.firebugit.com/api/v1
Repository API path: /repos/ksmith/OrbitalWard
Access token file: /home/ksmith/.codex_security/gitea_token

Never print the token value. Read it only inside commands that call the Gitea API.

Current Product State

OrbitalWard is a secure monitoring appliance focused on the v0.1 vertical slice:

Authenticated FastAPI backend with SQLAlchemy, Alembic, Pydantic, and JWT auth.
React, TypeScript, Vite, and Tailwind frontend.
Docker Compose development stack with PostgreSQL, Redis, backend, worker, and frontend.
Website monitor create/edit/delete flow.
HTTP status and expected-text checks.
Optional TLS certificate expiry checks for HTTPS monitors.
Ping and TCP port monitor create/edit/delete flow.
Alert rules, incident opening/resolution, acknowledge, silence, and webhook notifications.
Generic webhook, Mattermost, and Zoom Team Chat notification channels.
Saved webhook URLs encrypted at rest and not returned to the UI.
SNMPv2c credential profiles with encrypted community strings.
Guided SNMP device discovery with friendly device, interface, and monitorable item results.
Asset setup supports creating, selecting, and deleting assets, plus attaching ping, TCP, website, and SNMP monitors without creating alert rules automatically.
Worker collects configured SNMP uptime, interface status, traffic counter, error, and discard monitors.

Verification State

Recent Docker checks:

docker compose -f docker-compose.dev.yml exec -T backend python -m pytest tests
docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
docker compose -f docker-compose.dev.yml exec -T frontend npm run build
docker compose -f docker-compose.dev.yml exec -T worker python -m unittest discover -s tests
docker compose -f docker-compose.dev.yml exec -T worker python -m compileall app

Earlier rename and monitor work also verified:

docker compose -f docker-compose.dev.yml up -d --build
Backend health returned {"status":"ok","service":"orbitalward-backend"}.
Direct worker probes for TCP and ICMP ping checks passed inside the Docker network.
API probe created and deleted one ping monitor and one TCP monitor successfully.

The final Compose project uses orbitalward-* containers, images, network, and volumes.

Important Implementation Notes

ORBITALWARD_SECRET_KEY is the encryption/JWT secret environment variable.
DATABASE_URL now defaults to the orbitalward database/user in Compose.
The frontend local storage key is orbitalward_token.
Notification default username is OrbitalWard.
The TLS expiry check lives in worker/app/collectors/website.py and is enabled per monitor through JSON config fields:
- check_tls_expiry
- tls_warning_days

Issue Tracker Workflow

Use the Gitea API with the token file above. Useful endpoints:

List issues: GET /repos/ksmith/OrbitalWard/issues?state=all
Create issue: POST /repos/ksmith/OrbitalWard/issues
Update issue: PATCH /repos/ksmith/OrbitalWard/issues/{index}
List milestones: GET /repos/ksmith/OrbitalWard/milestones
List labels: GET /repos/ksmith/OrbitalWard/labels

Issue source docs:

docs/gitea-issues.md
docs/progress.md
docs/roadmap.md

Current completed items include TLS expiry monitor support, HTTP/website checks, ping and TCP port checks, basic alert evaluation, alert rule editing UI, incident actions, webhook notification channels, SNMPv2c credential profiles, the SNMP device discovery API, guided SNMP discovery UI, asset-based monitor setup, and initial SNMP collection for uptime plus interface counters/status. The next recommended implementation work is SNMP profile mapping and expanded CPU, memory, storage, and sensor collection.

Guardrails

Never commit or push changes without explicit user approval for that specific commit/push.
Keep monitoring separate from alerting.
Do not expose raw SNMP OIDs in the normal UI.
Use friendly names, profiles, and guided setup instead of raw configuration.
Do not include LANCache in product scope.
Avoid broad NMS features until the v0.1 vertical slice is stable.
Never log secrets or return saved secret values after creation.

4.7 KiB Raw Blame History