# pf-robotics/kachaka-api architecture

> Architecture diagram of the GitHub repository pf-robotics/kachaka-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pf-robotics/kachaka-api
- Repository: https://github.com/pf-robotics/kachaka-api

## Overview

##### Main Components Identification
- API Communication Layer:
- GRPC services (as defined in the protos directory, e.g., kachaka-api.proto).
- How the API layer is exposed across different languages.
- SDK Modules:
- Python SDK (found under “python/kachaka_api” and “python/demos” directories) that encapsulate API calls, asynchronous operations (aio sub-module), and utility functions.
- ROS 2 SDK (under “ros2” directory, with demos, description, interfaces, and bridges) which articulates how the robot’s capabilities (such as movement, vision, sensor data) are integrated.
- Frontend/Web Demo:
- Under “web/demos” – note the sample web panel for interacting with the API.
- Robotics Bridge Components:
- ROS2 bridge implementation (“ros2/kachaka_grpc_ros2_bridge”) that converts ROS 2 topics and messages to gRPC and vice versa.
- Supporting Tools and Scripts:
- Tools for generating proto files, syncing data/maps, linting, and updating API components (under “tools”).
- Configuration & Build Scripts:
- Various Dockerfiles, scripts, and config files (like .clang-format, .cmake-format.yaml) that suggest a robust build, test, and deployment process.

##### Relationships and Interactions
- Directional data flow from the end-user (or client application) invoking the API via gRPC.
- Calls branching into the two main SDK implementations: one targeting Python (with asynchronous and synchronous support) and one targeting ROS 2.
- Integration points where the frontend demo interacts with the API client libraries (via REST/gRPC or direct calls).
- Portray the toolings as auxiliary components that feed into or support the main builds and deployments.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Emphasize the division between interface (gRPC API), SDK layers (Python, ROS 2), and client applications (web demos).
- Modular Design: The clear directory separation for demos, API definitions, and utilities reflect an architecture designed to be extended across multiple languages/environments.
- Communication Abstraction via gRPC: Highlight how gRPC acts as a unified interface to bridge different ecosystems.
- Robotics Integration: Detail how the ROS 2 components (including interfaces and bridges) interact with real-time sensor, control, and visualization modules.

##### Relevant Technologies, Frameworks, and Libraries
- gRPC (for communication between client and server and for enabling multi-language support).
- ROS 2 (as a robotics middleware; see integration in demos and ROS2 packages).
- Python 3.10+ (for the SDK and various Python demos and utilities).
- Docker (multiple Dockerfiles indicate containerized development/deployment).
- Web Frameworks (the frontend demo is built with modern JS/TS tools like Vite, React [inferred from file names with .tsx and tsconfig]).

- Clear labels for every component (e.g., “gRPC API,” “Python SDK,” “ROS 2 Bridge,” “Web Demo,” etc.).
- From clients (user interfaces, scripts, etc.) to API calls, then branch into the Python side or into the ROS 2 system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level Client
    CLIENT("Client Applications"):::client

    %% API Communication Layer
    subgraph "API Communication Layer"
        RPC("gRPC API Service"):::api
    end

    %% SDK Modules
    subgraph "SDK Modules"
        PYS("Python SDK Module"):::sdk
        PYD("Python Demo Applications"):::demo
        ROS("ROS 2 SDK Module & Demos"):::sdk
        RBR("ROS 2 Bridge Component"):::sdk
    end

    %% Client Interfaces
    subgraph "Client Interfaces"
        WEB("Frontend/Web Demo"):::demo
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        TOOLS("Supporting Tools & Scripts"):::infra
        CONFIG("Configuration & Build Scripts"):::infra
    end

    %% Relationships and Data Flow
    CLIENT -->|"invokes"| RPC
    WEB -->|"interacts"| RPC

    RPC -->|"calls"| PYS
    RPC -->|"calls"| ROS

    PYS -->|"integrates with"| PYD
    ROS -->|"bridged by"| RBR

    %% Auxiliary support relationships
    TOOLS ---|"supports"| RPC
    TOOLS ---|"supports"| PYS
    CONFIG ---|"builds"| RPC
    CONFIG ---|"builds"| ROS

    %% Click Events
    click RPC "https://github.com/pf-robotics/kachaka-api/blob/main/protos/kachaka-api.proto"
    click PYS "https://github.com/pf-robotics/kachaka-api/tree/main/python/kachaka_api"
    click PYD "https://github.com/pf-robotics/kachaka-api/tree/main/python/demos"
    click ROS "https://github.com/pf-robotics/kachaka-api/tree/main/ros2"
    click RBR "https://github.com/pf-robotics/kachaka-api/tree/main/ros2/kachaka_grpc_ros2_bridge"
    click WEB "https://github.com/pf-robotics/kachaka-api/tree/main/web/demos/kachaka_api_web_sample"
    click TOOLS "https://github.com/pf-robotics/kachaka-api/tree/main/tools"
    click CONFIG "https://github.com/pf-robotics/kachaka-api/blob/main/Dockerfile.ros2"

    %% Style Definitions
    classDef client fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef api fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef sdk fill:#90EE90,stroke:#228B22,stroke-width:2px;
    classDef demo fill:#ADD8E6,stroke:#1E90FF,stroke-width:2px;
    classDef infra fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
