Skip to main content

​
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. 
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.