# boston-dynamics/spot-sdk architecture

> Architecture diagram of the GitHub repository boston-dynamics/spot-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boston-dynamics/spot-sdk
- Repository: https://github.com/boston-dynamics/spot-sdk

## Overview

##### Project type and purpose
- This is not a single‐application codebase but a comprehensive **SDK repository** (“Spot SDK”) for the Boston Dynamics Spot robot. It includes:
- Protobuf definitions of the Spot API (“protos/…”) and code-generation tooling (“choreography_protos/…”).
- A suite of **Python packages** (bosdyn-core, bosdyn-client, bosdyn-mission, bosdyn-orbit, bosdyn-scout, bosdyn-choreography-client) under “python/…”, each with its own setup.py.
- Thousands of Python **example programs** under “python/examples/…”.
- **Documentation** sources in Markdown under “docs/…” and generated HTML under “docs/html/…”.
- Prebuilt wheel distributions under “prebuilt/…”.

##### File structure
- Top-level directories:
- “protos”: canonical .proto service definitions ➔ code-gen for server & client stubs.
- “python”: per-package Python modules grouping core utilities, API clients, mission/orbit/scout extensions, choreography.
- “python/examples”: dozens of small demo applications.
- “docs”: conceptual, payload, proto, Python tutorials + Sphinx build output.
- “prebuilt”: precompiled wheel artifacts for easy install.
- “choreography_protos”: specialized protos & packaging for choreography features.
- Build scripts and packaging: setup.py & setup.cfg in each package, requirements files for examples, Sphinx conf for docs.

##### Architecture overview
1. **Spot Robot Onboard Services**
– gRPC servers implementing services defined in protos/…
2. **Protobuf API Definition Layer**
– .proto files under “protos/” & “choreography_protos/”
– protoc code-generation pipeline producing Python stubs
3. **Core Python SDK Libraries**
– bosdyn-core (geometry, data formats)
– bosdyn-client (auth, channel, generic client classes)
– bosdyn-mission, bosdyn-orbit, bosdyn-scout (domain-specific clients)
– bosdyn-choreography-client (animation & choreographer client)
4. **Example Applications & Payload Extensions**
– Python scripts & Docker-based plugins demonstrating usage
– Payload ICD docs & payload developer code
5. **Documentation Generation**
– Markdown sources under docs/
– Sphinx build producing HTML under docs/html/
6. **Packaging & Distribution**
– setup.py/Cfg per package
– prebuilt wheel files under prebuilt/

c. Architectural patterns & principles:
– **Layered architecture**:
- API Definition (Protos)
- Transport & Stub Generation (gRPC + codegen)
- Core Library & Clients
- Example & Application Layer
- Documentation Layer
– **Separation of Concerns**: each Python package focuses on one domain (auth & channels vs. mission vs. orbit).
– **Extensibility**: examples and payload plugins live in their own directories with Docker/requirements manifest.

d. Key technologies/frameworks:
– gRPC & Protocol Buffers (codegen)
– Python packaging (setuptools, wheels)
– Sphinx (documentation)
– Docker (for payload & example containers)
– Flask or simple Python servers (in some examples)

##### Details to capture
- **multi-package** nature of the SDK monorepo.
- Both the **code generation** and **packaging** pipelines.
- How **prebuilt wheels** allow immediate install without local build.
- Versions (e.g., v5.0.1.2).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and Components

    subgraph "API Definition Layer"
        direction TB
        ProtoDefs["Proto Definitions"]:::proto
        ChoreoProto["Choreography Proto Definitions & Packaging"]:::proto
    end

    Codegen["Code Generation"]:::proto

    subgraph "Core Python SDK Libraries"
        direction TB
        Core["bosdyn-core"]:::sdk
        Client["bosdyn-client"]:::sdk
        Mission["bosdyn-mission"]:::sdk
        Orbit["bosdyn-orbit"]:::sdk
        Scout["bosdyn-scout"]:::sdk
        ChoreoClient["bosdyn-choreography-client"]:::sdk
    end

    Examples["Example Applications & Payload Extensions"]:::examples

    subgraph "Documentation Pipeline"
        direction TB
        DocsSrc["Documentation Sources (Markdown)"]:::docs
        Sphinx["Sphinx Build"]:::docs
        DocsHtml["Documentation Output (HTML)"]:::docs
    end

    Prebuilt["Prebuilt Wheel Distributions"]:::packaging

    SpotServices["Spot Robot Onboard Services (gRPC)"]:::robot

    %% Relationships
    ProtoDefs --> Codegen
    ChoreoProto --> Codegen

    Codegen --> Core
    Codegen --> Client
    Codegen --> Mission
    Codegen --> Orbit
    Codegen --> Scout
    Codegen --> ChoreoClient

    Core --> SpotServices
    Client --> SpotServices
    Mission --> SpotServices
    Orbit --> SpotServices
    Scout --> SpotServices
    ChoreoClient --> SpotServices

    Examples --> Core
    Examples --> Client
    Examples --> Mission
    Examples --> Orbit
    Examples --> Scout
    Examples --> ChoreoClient

    DocsSrc --> Sphinx --> DocsHtml

    Core --> Prebuilt
    Client --> Prebuilt
    Mission --> Prebuilt
    Orbit --> Prebuilt
    Scout --> Prebuilt
    ChoreoClient --> Prebuilt
    ProtoDefs --> Prebuilt

    %% Click Events
    click ProtoDefs "https://github.com/boston-dynamics/spot-sdk/tree/master/protos/"
    click ChoreoProto "https://github.com/boston-dynamics/spot-sdk/tree/master/choreography_protos/"
    click Core "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-core/"
    click Client "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-client/"
    click Mission "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-mission/"
    click Orbit "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-orbit/"
    click Scout "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-scout/"
    click ChoreoClient "https://github.com/boston-dynamics/spot-sdk/tree/master/python/bosdyn-choreography-client/"
    click Examples "https://github.com/boston-dynamics/spot-sdk/tree/master/python/examples/"
    click DocsSrc "https://github.com/boston-dynamics/spot-sdk/tree/master/docs/"
    click DocsHtml "https://github.com/boston-dynamics/spot-sdk/tree/master/docs/html/"
    click Prebuilt "https://github.com/boston-dynamics/spot-sdk/tree/master/prebuilt/"

    %% Styles
    classDef proto fill:#D0E6FF,stroke:#1E70BF,color:#1E70BF;
    classDef sdk fill:#E1FFE1,stroke:#28A828,color:#28A828;
    classDef examples fill:#FFE6CC,stroke:#FF8C1A,color:#FF8C1A;
    classDef docs fill:#F2F2F2,stroke:#737373,color:#737373;
    classDef packaging fill:#EAD6FF,stroke:#9C4A9B,color:#9C4A9B;
    classDef robot fill:#FFD6D6,stroke:#C82A2A,color:#C82A2A;
```
