Protocol Buffer definitions repositoiry powering the @Spounge ecosystem services.

---

Universal schema translator for LLM microservices. Automated code generation for Go, TypeScript, and Python clients.

Table of Contents

• Quick Start
• Installation
• Project Structure
• Usage Examples
• Code Generation
• Design Conventions
• API Evolution Rules
• Testing
• Development Workflow
• CI/CD Pipeline
• Prerequisites
• Contact & Support
• References

Quick Start

git clone https://github.com/spounge-ai/spounge-proto
cd spounge-proto
make docker-setup 

Installation

Language	Command
Go	go get github.com/spoungeai/spounge-proto@latest
TypeScript	npm install @spounge/proto-ts
Python	pip install spounge-proto-py

Project Structure

proto/
├── <domain>/<version>/     # Domain definitions (auth/v1/)
├── common/v1/              # Shared definitions  
└── api/v1/                 # API Gateway definitions

gen/                        # Generated code
├── go/                     # Go protobuf + gRPC/Connect
├── ts/                     # TypeScript + Connect-Web
├── py/                     # Python protobuf
└── openapi/                # OpenAPI specs

Usage Examples

Go Client

package main

import (
    "context"
    "log"
    "time"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    apiv1 "github.com/spounge-ai/spounge-protos/gen/go/api/v1"
    authv1 "github.com/spounge-ai/spounge-protos/gen/go/auth/v1"
)

func main() {
    conn, err := grpc.Dial("localhost:8080", 
        grpc.WithTransportCredentials(insecure.NewCredentials()),
        grpc.WithBlock())
    if err != nil {
        log.Fatalf("connection failed: %v", err)
    }
    defer conn.Close()

    client := apiv1.NewAuthGatewayServiceClient(conn)
    
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    ctx = metadata.AppendToOutgoingContext(ctx, 
        "authorization", "Bearer your_token",
        "x-request-id", "unique-request-id")

    req := &apiv1.AuthGatewayServiceLoginRequest{
        LoginRequest: &authv1.LoginRequest{
            Email:    "[email protected]",
            Password: "SecurePassword123",
        },
    }

    res, err := client.Login(ctx, req)
    if err != nil {
        log.Fatalf("login failed: %v", err)
    }

    log.Printf("Token: %s", res.GetLoginResponse().GetToken())
}

TypeScript Client

import { createConnectTransport } from '@bufbuild/connect-web';
import { AuthGatewayServiceClient } from '../gen/ts/api/v1/auth_gateway_service.client';
import { AuthGatewayServiceLoginRequest } from '../gen/ts/api/v1/auth_gateway_service';
import { LoginRequest } from '../gen/ts/auth/v1/auth_service';

const transport = createConnectTransport({
    baseUrl: 'http://localhost:8080',
    interceptors: [
        (next) => async (req) => {
            req.header.set('Authorization', 'Bearer YOUR_TOKEN');
            return next(req);
        },
    ],
});

const client = new AuthGatewayServiceClient(transport);

async function login() {
    try {
        const request = new AuthGatewayServiceLoginRequest({
            loginRequest: new LoginRequest({
                email: '[email protected]',
                password: 'SecurePassword!',
            }),
        });

        const response = await client.login(request);
        console.log('Token:', response.loginResponse?.token);
    } catch (error) {
        console.error('Login failed:', error);
    }
}

Code Generation

Command	Purpose
make gen	Generate all clients
make gen-go	Go only
make gen-ts	TypeScript only
make gen-py	Python only
make docker-gen	Docker-based generation

Design Conventions

Naming Standards

Element	Convention	Example
Packages	lower.snake.case	api.v1
Services	PascalCase + Service	AuthGatewayService
RPC Methods	PascalCase	Login, GetUserProfile
Messages	ServiceMethodRequest/Response	AuthGatewayServiceLoginRequest
Fields	lower_snake_case	workflow_id
Enums	PascalCase	ExecutionStatus
Enum Values	PREFIX_VALUE_NAME	EXECUTION_STATUS_PENDING

Field Modifiers

• repeated - Arrays/lists
• optional - Nullable scalars (recommended for new fields)
• oneof - Mutually exclusive field groups

API Evolution Rules

✅ Allowed	❌ Breaking Changes
Add new fields, services, methods	Remove/rename fields, services, methods
Add optional fields	Change field types or numbers
Add enum values (append only)	Reorder enum values

Testing

gRPC Testing

# List services
grpcurl localhost:8080 list

# Test RPC
grpcurl -plaintext -d '{
    "loginRequest": {
        "email": "[email protected]", 
        "password": "password"
    }
}' localhost:8080 api.v1.AuthGatewayService/Login

HTTP/REST Testing

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"loginRequest": {"email": "[email protected]", "password": "password"}}' \
  http://localhost:8080/v1/auth/login

Command	Purpose
make test-go	Go integration tests
make test-ts	TypeScript client tests
make test-py	Python client tests

Development Workflow

1. Edit .proto files following conventions
2. buf format -w proto/ - Format
3. make lint - Lint
4. make gen - Generate
5. make test - Test
6. Commit (include generated code)

CI/CD Pipeline

• Protobuf linting (buf lint)
• Breaking change detection (buf breaking --against origin/main)
• Code generation verification
• Client library testing

Prerequisites

Tool	Version	Installation
Go	1.24+	go.dev/doc/install
Node.js	LTS	nodejs.org
protoc	v30+	protobuf.dev/installation/
buf	v2.x.x+	docs.buf.build/installation
Docker	Latest	docs.docker.com/get-docker

Contact & Support

• Issues: GitHub Issues
• Support: [email protected]
• License: MIT

References

Documentation Links

Protocol Buffers & gRPC

• Protocol Buffers Documentation
• Proto3 Language Guide
• gRPC Documentation

Buf Ecosystem

• Buf Documentation
• Buf Style Guide
• Buf Lint Rules

Connect & Gateway

• ConnectRPC Documentation
• grpc-gateway

API Design

• Google API Design Guide