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

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 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, with individual command implementations including:

• cg init – Scaffolds new projects from templates (implementation in 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)

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 (base HTTP handling) and 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, 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 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 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) establishes the canonical JSON schema for all grant-related resources.

2. Code Generation – The CLI (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:

# 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 to copy template files and configure the project structure.

Preview generated OpenAPI specifications locally:

# 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:

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 and lib/ts-sdk/src/client/opportunities.ts.

Search for opportunities using the Python SDK:

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, with Pydantic models ensuring runtime type safety.

Summary

• The Core TypeSpec library (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) 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) 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, 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), 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). 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 and opportunity-specific methods in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}