How sushantdasputepatil/chirpstack-api works
Project Type and Purpose
• Type: A client‐library generator for Protobuf/gRPC API definitions.
• Purpose: Maintain a single source of truth (the .proto and Swagger files), and generate idiomatic client libraries in Go, JavaScript/TypeScript, Python, Rust, and Java, plus auto-generated Swagger definitions.
File Structure
• Top-level “protobuf/” directory holds all .proto files, organized by component: as (Application Server), ns (Network Server), gw, nc, geo, common.
• “swagger/” directory holds JSON Swagger specs generated from the same .proto definitions.
• Language‐specific directories (go/, js/, python/, rust/, java/) each contain:
– Dockerfile-<lang> for containerized build environments
– Makefile or build scripts
– Generated source code (pb.go, _grpc_pb.js, _pb2.py, etc.)
• Root folders: Docker Compose file, multi-language Dockerfiles, top-level Makefile, ISSUE_TEMPLATE, CI config.
README for Additional Insights
• The README describes the overall workflow: use Docker & Docker Compose + make targets to regenerate all clients or per-language subsets.
• Lists supported languages and how to install the published artifacts.
• Shows dependency on protoc, protoc-gen-go, protoc-gen-grpc-gateway, protoc-gen-grpc-java, protoc-gen-swagger, grpc_tools, etc.
Main Components & Their Roles
a. Input Layer (Source Definitions)
• protobuf/ (Protobuf definitions)
• swagger/as, swagger/internal tools (Swagger JSON)
b. Orchestration Layer
• Root Makefile (entry point: make all, make go, make js, …)
• docker-compose.yml defines services per language
• Individual Dockerfiles (Dockerfile-go, ‑js, ‑python, ‑rust, ‑java)
c. Processing Layer (Code-gen Containers)
For each language:
• Container mounts protobuf/ + swagger/ to /defs
• Runs protoc with the appropriate plugins (e.g. protoc-gen-go, grpc-gateway, grpc-java)
• Generates client code under a mounted volume pointing to language directory
d. Output Layer (Generated Clients & Specs)
• go/… generated Go modules
• js/… generated JS/TS modules + package.json
• python/src/chirpstack_api… generated Python package + setup.py
• rust/src… and Cargo.toml for Rust crate
• java/template/… for Maven artifact
• swagger/… regenerated Swagger JSON files
Architectural Patterns & Design Principles
• Pipeline pattern: single source → parallel code-gen tasks → multi-language outputs
• Containerization for reproducible builds
• Clear separation of concerns: definitions vs. orchestration vs. generated code
• Extensibility: adding a new language involves adding a Dockerfile, compose service, and Makefile rule
Technologies & Frameworks
• Protobuf & gRPC
• Docker & Docker Compose
• protoc plugins: protoc-gen-go, grpc-gateway, grpc-gen-swagger, protoc-gen-grpc-java
• Build systems: Make, Maven, Cargo, npm, setup.py
Essential Elements to Capture
• All language services (Go, JS/TS, Python, Rust, Java)
• The central Makefile & docker-compose orchestrator
• Protobuf directory as the single source of truth
• Generated Swagger files under swagger/
• The publishing endpoints (optional overlay)