robosystems: Instructions file for Claude Code

CLAUDE.md - RoboSystems Development Guide

Critical Rules

All Python commands MUST use uv run:

uv run python script.py    # NOT: python script.py
uv run pytest              # NOT: pytest
uv run ruff check          # NOT: ruff check

Always use Docker profile robosystems - never individual service profiles:

just start                 # Uses robosystems profile by default
just start robosystems     # Explicit form (same result)
                           # NOT: just start api

Never use os.getenv() directly - use centralized config:

from robosystems.config import env
database_url = env.DATABASE_URL  # NOT: os.getenv("DATABASE_URL")

Never create migrations manually - always autogenerate:

just migrate-create "description"  # NOT: manual alembic revision

API Endpoints (local testing)

Core platform APIs are mounted under /v1 (graphs, billing, auth, etc.). Extensions (roboledger, roboinvestor) live under /extensions and are graph-scoped at the URL level, with three sub-surfaces:

• Typed reads → POST /extensions/{graph_id}/graphql (Strawberry + GraphiQL in dev)
• Command writes → POST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name}
• Analytical view operations → POST /extensions/{domain}/{graph_id}/operations/{view_name} — graph-backed operations that query LadybugDB rather than the extensions OLTP database. Read-only, same envelope contract as command writes. build-fact-grid (pivot tables over the XBRL hypercube), financial-statement-analysis, and the pair disclosures (the map of a report's sections) / information-block (one section read whole — xbrlkit's own tools run over the report held whole: the published holon on sec, the report bundle on a tenant; the graph is not in that path); gated independently of the OLTP domain flags so deployments without the corresponding tenants can still mount them

All three surfaces take graph_id as a URL path parameter — auth + per-graph access are validated by FastAPI dependencies before the handler runs. GraphQL queries do NOT take a graphId argument; the URL is the scope.