Agent Handoff Notes

Last updated: 2026-05-23

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 at last update: 3b75075 Rename project to OrbitalWard

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.

Verification State

After the rename and TLS expiry work, these checks passed in Docker:

docker compose -f docker-compose.dev.yml up -d --build
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 worker python -m compileall app
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, incident actions, and webhook notification channels. The next recommended implementation issue is alert rule editing UI.

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.

3.9 KiB Raw Blame History