---

name: server description: "Operate on Observal FastAPI backend routes, data services, auth, migrations, jobs, insights, and route-focused tests." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

server

Use this sub-skill when a task touches the Observal FastAPI backend: REST or GraphQL route registration, PostgreSQL models and Pydantic schemas, service-layer behavior, auth/JWT/SSO/SCIM, registry and agent/component APIs, telemetry ingest storage, ClickHouse versus PostgreSQL migrations, dynamic settings, background jobs, insights, or route-focused tests.

Do not use this sub-skill for Typer CLI command hierarchy, frontend React/TanStack Router work, harness adapter/hook-spec/session-parser additions, or repo-wide release/compliance workflow except where they call into server APIs.

Start here

1. Identify the backend surface:
   • New or changed REST route: read references/server-architecture.md and references/api-data-workflows.md.
   • SQLAlchemy model, Alembic, ClickHouse, dynamic settings, or arq jobs: read references/migrations-and-settings.md.
   • Auth, SSO, SCIM, route registration, ingest, insights, or failing backend tests: read references/troubleshooting.md first, then the focused reference above.
2. Verify the route graph before and after route registration changes with this sub-skill's bundled helper scripts/check_server_routes.py.
3. Keep changes in the server-owned layers: observal-server/api, models, schemas, services, jobs, alembic/versions, and clickhouse/migrations.
4. Add or update focused tests/test_*routes*.py, tests/test_clickhouse_*.py, tests/test_migration*.py, or tests/test_insights*.py coverage for the exact behavior.

Hard boundaries

• Server owns FastAPI, data models, migrations, settings, jobs, auth/admin routes, insights, and the ingest endpoint.
• Harness telemetry owns harness registry/adapters/hook specs/session parsers/session delivery. Server work may use ingest and ClickHouse storage patterns, but harness-specific parsing or hook installation belongs there.
• CLI owns Typer commands and bundled CLI skills.
• Web owns Vite/React/TanStack Router and Playwright/e2e guidance.
• Repo-development owns contributor policy, global lint/test/release workflow, and change-review process.

Non-negotiable backend invariants

• Register new top-level routers in routes.py; package routers such as api.routes.agent and api.routes.admin must import submodules so decorators attach to the shared router.
• Authenticated HTTP APIs use Authorization: Bearer <token> and dependencies from api.deps; do not add an X-API-Key bypass without confirming a deliberate auth design change.
• PostgreSQL schema changes require Alembic migrations. ClickHouse schema changes require SQL files in observal-server/clickhouse/migrations/. Do not add new ClickHouse DDL to startup code.
• Runtime-tunable settings go through services.dynamic_settings, not direct env-var reads. Boot-time infrastructure and crypto settings stay in config.py.
• Use Loguru (from loguru import logger as optic) with positional placeholders; never log secrets, JWTs, keys, or bearer tokens.
• Outbound network from server services must pass the existing SSRF guard patterns.