> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the SDK is organized — proto sources, build pipeline, and the generated artifacts you actually consume.

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](https://buf.build) and [sebuf](https://github.com/SebastienMelki/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`:

```protobuf theme={null}
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](/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](/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`](https://github.com/bufbuild/protovalidate)) 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.