# stapi-spec/pystapi architecture

> Architecture diagram of the GitHub repository stapi-spec/pystapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stapi-spec/pystapi
- Repository: https://github.com/stapi-spec/pystapi

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Packages"
        A["stapi-pydantic\n(Models & Schemas)"]:::green
        B["stapi-fastapi\n(FastAPI Service & Routers)"]:::blue
        C["pystapi-client\n(Client Library & CLI)"]:::orange
        D["pystapi-validator\n(Validator Tool)"]:::purple
    end

    A -->|import| B
    A -->|import| C
    C -->|HTTP request/response| B
    C -->|invokes| D
    D -->|validate via HTTP| B

    E["External STAPI Server / Data Backend"]:::gray
    C -->|HTTP request/response| E
    D -->|HTTP validate| E

    subgraph "CI/CD Pipelines"
        CI1[".github/workflows/ci.yaml"]:::brown
        CI2[".github/workflows/release.yaml"]:::brown
        CI3["scripts/"]:::brown
    end

    subgraph "Documentation Site"
        DOC1["mkdocs.yml"]:::brown
        DOC2["docs/"]:::brown
    end

    CI1 -->|"build & test"| A
    CI1 -->|"build & test"| B
    CI1 -->|"build & test"| C
    CI1 -->|"build & test"| D
    DOC1 -->|"generate docs"| A
    DOC2 -->|"site content"| A

    click A "https://github.com/stapi-spec/pystapi/tree/main/stapi-pydantic/src/stapi_pydantic/"
    click B "https://github.com/stapi-spec/pystapi/tree/main/stapi-fastapi/src/stapi_fastapi/"
    click C "https://github.com/stapi-spec/pystapi/tree/main/pystapi-client/src/pystapi_client/"
    click D "https://github.com/stapi-spec/pystapi/tree/main/pystapi-validator/src/pystapi_validator/"
    click CI1 "https://github.com/stapi-spec/pystapi/blob/main/.github/workflows/ci.yaml"
    click CI2 "https://github.com/stapi-spec/pystapi/blob/main/.github/workflows/release.yaml"
    click CI3 "https://github.com/stapi-spec/pystapi/tree/main/scripts/"
    click DOC1 "https://github.com/stapi-spec/pystapi/blob/main/mkdocs.yml"
    click DOC2 "https://github.com/stapi-spec/pystapi/tree/main/docs/"

    classDef green fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef blue fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef orange fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef purple fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef gray fill:#eceff1,stroke:#455a64,stroke-width:2px
    classDef brown fill:#efebe9,stroke:#5d4037,stroke-width:2px
```
