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

# SDK Integration

> How the frontend stays in sync with the backend API

## Overview

PyqDeck uses an **API-first** development model. Instead of manually writing API calling logic, we generate a TypeScript SDK directly from the backend's OpenAPI (Swagger) definition.

## The Pipeline

The synchronization process follows these steps:

1. **JSDoc Annotations**: Backend routes and models are annotated with `@openapi` (via `swagger-jsdoc`).
2. **Export Spec**: Running `pnpm run openapi:export` in the `backend/` directory generates a static `openapi.json` file.
3. **Generate SDK**: Running `pnpm run gen:api` in the `frontend/` directory consumes the `openapi.json` and generates `frontend/src/lib/api-generated.ts`.

## Tools Used

* **swagger-jsdoc**: Extracts OpenAPI definitions from source code comments.
* **swagger-typescript-api**: Generates the TypeScript classes, interfaces, and request logic from the OpenAPI spec.

## Using the SDK

The generated SDK provides a typed `Api` class.

```typescript theme={null}
import { Api } from "@/lib/api-generated";

const api = new Api({ baseURL: "..." });

// Fully typed request and response
const res = await api.universities.listUniversities({ page: 1 });
const universities = res.data.data.items;
```

## Maintenance

Whenever a backend route is added or a model schema changes:

1. Update the JSDoc in the backend.
2. Run the export command in the backend.
3. Run the generation command in the frontend.
4. Commit the updated `api-generated.ts`.

This ensures that frontend-backend contracts are always in sync and catches type mismatches at compile time rather than runtime.