# CommonGrants Project Structure: A Complete Guide to the hhs/simpler-grants-protocol Architecture

> Explore the CommonGrants project structure in this guide to the hhs/simpler-grants-protocol architecture. Understand its eight interconnected components and specification-first design.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: architecture
- Published: 2026-03-03

---

**The CommonGrants project structure comprises eight interconnected components built around a specification-first architecture: a TypeSpec core library, command-line interface, TypeScript and Python SDKs, documentation website, project templates, code examples, and a changelog emitter.**

The `hhs/simpler-grants-protocol` repository delivers a comprehensive open-source ecosystem for standardizing grant data APIs. Understanding the CommonGrants project structure is essential for developers implementing the protocol, as each component serves a specific role in maintaining consistency across languages and tooling.

## Core Components of the CommonGrants Project Structure

### Core TypeSpec Library

The **Core TypeSpec library** located at [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts) defines the canonical data model and validation rules for the entire ecosystem. This library acts as the single source of truth for all schemas—including opportunities, grants, and custom fields—using TypeSpec syntax to ensure type safety across all downstream consumers.

### Command-Line Interface (CLI)

The **CLI** provides developer tooling to generate, validate, and preview Common Grants specifications. The entry point resides at [`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts), with individual command implementations including:

- **`cg init`** – Scaffolds new projects from templates (implementation in [`lib/cli/src/commands/init/init.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/init/init.ts))
- **`cg compile`** – Compiles TypeSpec to OpenAPI
- **`cg check`** – Validates custom schemas against the core specification
- **`cg preview`** – Launches a local preview server for generated documentation (implementation in [`lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/preview/preview.ts))

### TypeScript SDK

The **TypeScript SDK** offers a ready-to-use client library for consuming Common Grants REST APIs. Key files include [`lib/ts-sdk/src/client/client.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/client.ts) (base HTTP handling) and [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts) (typed methods for get, list, and search operations). The SDK supports pagination, custom field extensions, and runtime schema validation.

### Python SDK

The **Python SDK** mirrors the TypeScript functionality for Python developers, located in `lib/python-sdk/`. The base client implementation resides at [`lib/python-sdk/common_grants_sdk/client/client.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/python-sdk/common_grants_sdk/client/client.py), utilizing Pydantic models under `lib/python-sdk/common_grants_sdk/schemas/pydantic` for type-safe request and response handling.

### Website and Documentation

The **Website** component generates the public documentation site and OpenAPI references from TypeSpec source files. The primary specification source is located at `website/src/specs/main.tsp`, with build scripts in `src/scripts/` handling schema generation, validation, and versioned artifact creation.

### Templates and Quick-Start

**Templates** provide boilerplate implementations demonstrating how to wire the specification into real API servers. The quick-start template at `templates/quickstart/main.tsp` shows minimal setup requirements, with additional templates available for Express.js, Go, and FastAPI implementations.

### Examples

The **Examples** directory contains small, runnable programs demonstrating typical SDK usage patterns. For instance, [`lib/ts-sdk/examples/list-opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/examples/list-opportunities.ts) shows how to search opportunities and handle paginated responses using the TypeScript client.

### Changelog Emitter

The **Changelog Emitter** at [`lib/changelog-emitter/src/emitter.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/changelog-emitter/src/emitter.ts) emits structured changelog entries whenever the specification evolves. This utility enables automated release notes and tracks breaking changes across versions.

## Specification-First Architecture Workflow

The CommonGrants project structure follows a deliberate **specification-first** design where every consumer derives code from the same TypeSpec definitions:

1. **Schema Definition** – The Core library ([`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts)) establishes the canonical JSON schema for all grant-related resources.

2. **Code Generation** – The CLI ([`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts)) reads the core spec to compile OpenAPI documents, validate custom implementations, and scaffold new projects.

3. **SDK Implementation** – Both TypeScript and Python SDKs consume generated models (via TypeScript/Zod or Pydantic) to provide type-safe client APIs that handle HTTP transport, pagination, and error handling consistently.

4. **Documentation** – The website (`website/src/specs/main.tsp`) pulls the identical TypeSpec source to generate static documentation, guaranteeing that published API references match the actual implementation schemas.

## Working with the CommonGrants CLI

Scaffold a new project using the quick-start template:

```bash

# Initialize a fresh repository with boilerplate files

cg init --template quickstart

```

The `init` command delegates to `DefaultInitService` within [`lib/cli/src/commands/init/init.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/init/init.ts) to copy template files and configure the project structure.

Preview generated OpenAPI specifications locally:

```bash

# Start a local preview server at http://localhost:3000

cg preview ./openapi.yaml

```

## Implementing Grant Data Access with SDKs

Fetch opportunities with custom field validation using the TypeScript SDK:

```typescript
import { Client } from "@common-grants/ts-sdk";
import { withCustomFields } from "@common-grants/ts-sdk/extensions";
import { OpportunityBaseSchema } from "@common-grants/ts-sdk/schemas";
import { z } from "zod";

const client = new Client({ baseUrl: "https://api.common-grants.org" });

async function getOpportunity(id: string) {
  // Extend base schema with custom fields for typed access
  const OpportunitySchema = withCustomFields(OpportunityBaseSchema, [
    { key: "legacyId", fieldType: "integer", valueSchema: z.number().int() }
  ] as const);

  const opp = await client.opportunities.get(id, { schema: OpportunitySchema });
  console.log(`Title: ${opp.title}`);
  console.log(`Legacy ID: ${opp.customFields?.legacyId?.value}`);
}

```

The `Client` class and `Opportunities` namespace are defined in [`lib/ts-sdk/src/client/client.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/client.ts) and [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts).

Search for opportunities using the Python SDK:

```python
from common_grants_sdk.client import Client
from common_grants_sdk.schemas import OpportunityBaseSchema

client = Client(base_url="https://api.common-grants.org")

# Search for open opportunities with pagination

results = client.opportunities.search(
    query="education",
    statuses=["open"],
    max_items=50
)

for opp in results.items:
    print(f"{opp.title}: {opp.id}")

```

The Python client resides in [`lib/python-sdk/common_grants_sdk/client/client.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/python-sdk/common_grants_sdk/client/client.py), with Pydantic models ensuring runtime type safety.

## Summary

- The **Core TypeSpec library** ([`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts)) defines the canonical schema and validation rules as the single source of truth.
- The **CLI** ([`lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/index.ts)) provides code generation, schema validation, and project scaffolding through commands like `cg init` and `cg preview`.
- **TypeScript** and **Python SDKs** in `lib/ts-sdk/` and `lib/python-sdk/` deliver type-safe HTTP clients with pagination and custom field support.
- The **Website** (`website/src/specs/main.tsp`) generates versioned documentation and OpenAPI specifications directly from TypeSpec source.
- **Templates** (`templates/quickstart/main.tsp`) offer boilerplate implementations for Express.js, Go, and FastAPI servers.
- **Examples** demonstrate real-world SDK usage patterns for searching and manipulating grant data.
- The **Changelog Emitter** ([`lib/changelog-emitter/src/emitter.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/changelog-emitter/src/emitter.ts)) tracks specification changes for automated release management.

## Frequently Asked Questions

### What is the purpose of the TypeSpec core library in CommonGrants?

The TypeSpec core library serves as the single source of truth for all grant-related data models and validation rules. Located in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), it defines the canonical JSON schema for opportunities, custom fields, and grant structures using TypeSpec syntax, ensuring all downstream consumers—including SDKs, documentation, and templates—reference identical type definitions.

### How does the CommonGrants CLI support developers?

The CLI provides essential developer tooling including project scaffolding via `cg init` (implemented in [`lib/cli/src/commands/init/init.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/init/init.ts)), schema validation with `cg check`, TypeSpec compilation to OpenAPI via `cg compile`, and local preview servers through `cg preview` (found in [`lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/preview/preview.ts)). These commands streamline the process of implementing and validating Common Grants APIs against the core specification.

### Where are the SDK implementations located in the repository?

The TypeScript SDK resides in `lib/ts-sdk/` with the base client at [`lib/ts-sdk/src/client/client.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/client.ts) and opportunity-specific methods in [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/opportunities.ts). The Python SDK is located in `lib/python-sdk/` with its core client implementation in [`lib/python-sdk/common_grants_sdk/client/client.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/python-sdk/common_grants_sdk/client/client.py), utilizing Pydantic models for runtime validation that mirror the TypeScript/Zod schemas generated from the core TypeSpec library.

### How do the website and templates utilize the core specification?

The website sources TypeSpec definitions from `website/src/specs/main.tsp` to generate static documentation and OpenAPI references. Templates such as `templates/quickstart/main.tsp` provide boilerplate implementations that demonstrate how to structure real API servers using the same TypeSpec schemas, ensuring consistency between published documentation and actual API implementations.