---

name: backend-core description: "FastAPI backend routes, auth credentials, data services, migrations, tests, and service-layer troubleshooting for Open Wearables." disable-model-invocation: true metadata: disco-role: operating license: MIT

Backend Core

Use this sub-skill for Open Wearables FastAPI backend work: API routes, developer auth, API keys, SDK applications, users, connections, summaries, events, health scores, timeseries, sync status, seed data, outgoing webhooks, service/repository/model/schema patterns, configuration, migrations, Celery/Redis orchestration, and backend tests.

Route the task

• For endpoint families, auth requirements, route registration, OpenAPI/docs navigation, and API-change checklists, read api-routes.md.
• For data models, repositories, service layer patterns, schemas, summaries/events/timeseries flow, sync status, seed data, and outgoing webhook internals, read data-model-and-services.md.
• For concrete backend commands, local Docker/uv workflows, migrations, seeding, targeted pytest selection, and endpoint implementation steps, read workflows.md.
• For PostgreSQL/Redis/testcontainers, auth/API-key, Svix, AWS, Celery, OpenAPI, pagination/date, and migration failures, read troubleshooting.md.
• When a checkout is available, run the safe static checker before or after backend edits: python skills/disco/open-wearables/sub-skills/backend-core/scripts/check_backend_core.py --repo-root .. Add --import-openapi only when backend dependencies and config are ready; it still avoids network and writes.

Boundaries

This sub-skill owns generic backend/API behavior. Route provider-specific OAuth, provider factory registration, coverage constants, vendor workout parsing, provider webhook parsing, historical backfill internals, and provider-specific import normalization to provider-integrations. Route React portal pages, API hooks, query keys, runtime frontend config, and UI presentation to frontend-portal. Route FastMCP tools, assistant configs, and MCP REST-client behavior to mcp-server.

When work crosses boundaries, keep the shared endpoint contract, auth, database schema, service/repository changes, migrations, and external API docs navigation here; ask the owning sibling sub-skill to handle provider internals or frontend/MCP callers.

Non-negotiable backend rules

• Preserve the route hierarchy: module routers are prefix-free, the v1 router attaches prefixes/tags, the head router attaches the API version prefix, and app.main includes the head router.
• Do not use trailing slash route roots on prefixed routers. Use "" for a prefixed router's root endpoint; "/" can create 307 redirects behind reverse proxies.
• Keep route handlers thin. Validate/parse request inputs, call services, and return Pydantic response models; do not call repositories directly from routes.
• Keep repositories database-only and model-only. Pydantic schemas and business decisions belong in services or route schemas, not repository methods.
• Use SQLAlchemy 2.0 Mapped[...] model fields and the existing app.mappings aliases for IDs, FKs, constrained strings, dates, decimals, JSON, and relationships.
• Use Pydantic v2 schema style with ConfigDict(from_attributes=True) for ORM reads and schema defaults for generated IDs/timestamps where appropriate.
• Protect public/external data APIs with ApiKeyDep unless the route is intentionally token/SDK/OAuth/system-specific; protect dashboard/admin routes with DeveloperDep.
• If you add, remove, rename, or retag an endpoint tagged External: *, update the API Reference navigation in docs/docs.json in the same change.
• Treat credentials as secrets. Never log API keys, JWTs, application secrets, provider OAuth tokens, Svix tokens, AWS keys, or master encryption material.
• Run focused backend quality checks after changes when dependencies are available: targeted pytest, ruff check, ruff format --check or format, and ty check for type-impacting work.

Fast start for future agents

1. Classify the task as route/API contract, data-service/model, background/sync/webhook, migration/config, test failure, or troubleshooting.
2. Read the nearest reference in this sub-skill; avoid reopening source files unless you are implementing or verifying drift.
3. For endpoint changes, update the route module, schemas, service, repository/model/migration if needed, route registration/tags, tests, and external API docs navigation together.
4. For data ingestion or sync changes, verify the affected data-source identity, event/timeseries upsert semantics, sync-status events, and outgoing webhook side effects.
5. Prefer the smallest safe test set first, then expand to the native candidate files listed in workflows.md when the change scope requires it.