Architecture

The SDK is proto-first: nothing in the public surface is hand-written. Every client, doc, and HTTP handler is generated from a single set of .proto files using buf v2 and sebuf.

Repository layout

Source of truth (edited by hand)

sdk/shared/v1/        # Pagination, errors, identifiers, content types, media, rate limit
sdk/auth/v1/          # OAuth — exchange, refresh, revoke
sdk/developer/v1/     # API key management
sdk/catalog/v1/       # MusicCatalogService — songs, albums, artists, lyrics
sdk/video/v1/         # VideoCatalogService — shows, seasons, episodes, movies
sdk/playlist/v1/      # PlaylistService
sdk/library/v1/       # LibraryService — liked, saved, followed, history
sdk/search/v1/        # DiscoveryService — search + browse
sdk/streaming/v1/     # StreamingService — stream acquisition (billable)
sdk/soundtrack/v1/    # SoundtrackService — cross-content linking
sdk/user/v1/          # UserService — current user profile
buf.yaml              # Lint + breaking rules (STANDARD + COMMENTS)
buf.gen.yaml          # Generation pipeline (Go, TS, Swift, Java, Python, OpenAPI)

Generated (never edited, but committed)

api/sdk/              # Go protobuf types + sebuf HTTP handlers
web/sdk/              # TypeScript interfaces (consumed via @anghami/sdk)
swift/Generated/      # Swift protobuf types (SPM target: AnghamiSDK)
java/generated/       # Java protobuf lite classes
python/sdk/           # Python protobuf modules + mypy stubs
docs/api/             # Bundled OpenAPI 3.1 (YAML + JSON)

Generated code is committed so consumers can depend on the repo directly without running the toolchain.

Build pipeline

make generate runs buf generate, which fans out to nine plugins:

#	Plugin	Output
1	`protoc-gen-go`	Go types
2	`protoc-gen-go-http` (sebuf)	Go HTTP handlers
3	`protoc-gen-openapiv3` (yaml, bundled)	`docs/api/anghami-sdk.openapi.yaml`
4	`protoc-gen-openapiv3` (json, bundled)	`docs/api/anghami-sdk.openapi.json`
5	`protoc-gen-swift`	Swift types
6	`protoc-gen-ts_proto`	TypeScript interfaces
7	`protoc` (java, lite)	Java classes
8	`protoc` (python)	Python modules
9	`protoc-gen-mypy`	Python type stubs

Post-processing scripts inject HTTP path metadata into the TypeScript interfaces, strip @Generated annotations from Java, and emit __init__.py files for Python packages.

HTTP shape

Every RPC compiles into a stable path defined in the proto via sebuf.http. Reads are GET, mutations and batch operations are POST:

service MusicCatalogService {
  option (sebuf.http.service_config) = { base_path: "/v1/music" };

  // GET /v1/music/songs/{id}
  rpc GetSong(GetSongRequest) returns (GetSongResponse) {
    option (sebuf.http.config) = { path: "/songs/{id}" method: HTTP_METHOD_GET };
  }

  // POST /v1/music/songs:batchGet
  rpc BatchGetSongs(BatchGetSongsRequest) returns (BatchGetSongsResponse) {
    option (sebuf.http.config) = { path: "/songs:batchGet" method: HTTP_METHOD_POST };
  }
}

The convention follows AIP-style: single-resource reads are GET with path parameters; multi-resource batch reads use POST with :batchGet suffix and a typed body. The full path/method mapping for every operation is in the API Reference.

Versioning

Proto packages are versioned — every package is sdk.{service}.v1. Breaking changes ship as v2 packages alongside v1 until consumers migrate.
make breaking runs against main — any breaking change to v1 fails CI.
Generated code follows proto versioning — TS/Go/Swift packages export typed namespaces matching the proto packages.

See Versioning for the deprecation policy.

Why proto-first

One source, many surfaces. OpenAPI, REST clients, and HTTP handlers stay in lock-step — they’re all derivatives of the same .proto.
Strict contracts. Validation rules (buf.validate) live in the proto and apply identically on every client and server.
Documentation by construction. Every field/message/RPC has a leading comment (enforced by buf lint COMMENTS), so the OpenAPI you import already has descriptions on every operation.

Getting Started

Usage

Platform & Features

Music

Video & Soundtrack

User & Developer

AI & Agents

Developer Guide

Legal

Repository layout

Source of truth (edited by hand)

Generated (never edited, but committed)

Build pipeline

HTTP shape

Versioning

Why proto-first

​Repository layout

​Source of truth (edited by hand)

​Generated (never edited, but committed)

​Build pipeline

​HTTP shape

​Versioning

​Why proto-first

Repository layout

Source of truth (edited by hand)

Generated (never edited, but committed)

Build pipeline

HTTP shape

Versioning

Why proto-first