How stapi-spec/pystapi works
Project type and purpose
• This is a multi-package Python monorepo implementing the Satellite Tasking API (STAPI) specification.
• It contains:
• A Pydantic model library (stapi-pydantic) as the source-of-truth for STAPI data structures and JSON schemas.
• A framework-agnostic FastAPI application (stapi-fastapi) that uses those models to serve STAPI endpoints.
• A Python client and CLI (pystapi-client) for consuming any STAPI-compliant server.
• A validator tool (pystapi-validator) to check API conformance.
File structure
• Top-level:
• CI/CD & release scripts (GitHub workflows, Dockerfile, scripts/)
• Documentation site (mkdocs.yml and docs/)
• Four sub-packages, each with its own pyproject.toml, README, src/, tests/:
• stapi-pydantic: defines models, constants, schemas
• stapi-fastapi: builds on stapi-pydantic, implements routers, backends, conformance checks
• pystapi-client: provides a client API and CLI to call STAPI servers
• pystapi-validator: uses the client + schemas to validate a live server’s conformance
README relationships
stapi-pydantic → pystapi-client → pystapi-validator
stapi-pydantic → stapi-fastapi
Diagramming the architecture
a. Main components
• stapi-pydantic package (Models & Schemas)
• stapi-fastapi service (FastAPI app + routers + optional vendor backends)
• pystapi-client library & CLI
• pystapi-validator tool
• External STAPI-compliant servers or data backends
• CI/CD pipeline & documentation site (secondary)
b. Relationships & data flows
• stapi-pydantic exports models → consumed by stapi-fastapi & by client/validator
• stapi-fastapi exposes HTTP endpoints → serving JSON payloads conforming to stapi-pydantic schemas
• pystapi-client sends HTTP requests → to stapi-fastapi (or any STAPI server) → parses responses into stapi-pydantic models
• pystapi-validator uses the client + schemas → fetches server metadata & payloads → performs conformance checks
c. Architectural patterns
• Package-based modular design (four independent libraries)
• Specification-driven development: models first, code generation of OpenAPI via FastAPI
• Dependency inversion: server & client depend on shared schema package
d. Key technologies
• Python & pyproject.toml/PEP517 packaging
• Pydantic for data models & JSON schema generation
• FastAPI for web server & OpenAPI spec
• Click (or Typer) for CLI scripting in pystapi-client
• GitHub Actions + pre-commit + uv for CI/CD
Essential architectural elements
• Clearly separate model layer vs. server vs. client vs. validator.
• How the shared schema package drives both server and client.
• CI/CD and docs as part of the developer workflow.