robosystems CLAUDE.md

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 is the first one (pivot tables over the XBRL hypercube); 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.

Per-domain feature flags: ROBOLEDGER_ENABLED and ROBOINVESTOR_ENABLED gate the corresponding GraphQL resolvers and operation routers. The schema is built dynamically per flag combo, so a ledger-only deployment exposes only ledger fields (no INVESTOR_NOT_INITIALIZED runtime errors).