> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI3M2NlMGI5OC1mOTg3LTRjYmMtODk3MS1lNmE1MmM5YWE1MDUiLCJleHAiOjE3Nzg1MzQ0OTcsImlhdCI6MTc3ODUzNDE5N30.ixRb_oZ0N67pXOeVC9JU7mX35_7USJ4YTTBZgWLdYdo
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# Project structure

> Learn how to structure your SDK project with Fern. Set up multi-repo architecture, configure generators.yml, and organize API definitions.

Before generating SDKs with Fern, set up the proper GitHub repository structure to house your API definitions and SDK code so it's intuitive for you and your users to access, maintain, and update code.

## Repository architecture

Fern recommends a multi-repository structure containing:

* **Source repository** with your API definitions and SDK generation configuration
* **SDK repositories** for each SDK (TypeScript, Python, Go, etc.)

<Files>
  <Folder name="company-repo" defaultOpen comment="Source repository">
    <Folder name=".github" defaultOpen>
      <Folder name="workflows" comment="Publishing workflows for all SDKs" />
    </Folder>

    <Folder name="fern" defaultOpen>
      <File name="fern.config.json" comment="Root-level config" />

      <File name="generators.yml" comment="References SDK repos" />

      <Folder name="definition">
        <File name="overrides.yml" comment="Optional overrides file" />

        <File name="api.yml" comment="Your API definition" />
      </Folder>
    </Folder>
  </Folder>

  <Folder name="typescript-sdk-repo" comment="SDK repository">
    <Folder name=".github">
      <Folder name="workflows" comment="Generated by Fern" />
    </Folder>

    <Folder name="scripts" />

    <Folder name="src" />

    <Folder name="tests" />

    <File name=".fernignore" comment="Files Fern shouldn't modify (custom code)" />
  </Folder>

  <Folder name="python-sdk-repo" comment="SDK repository" />

  <Folder name="go-sdk-repo" comment="SDK repository" />
</Files>

This separation allows you to manage API definitions centrally while keeping each SDK in its own repository for independent versioning and distribution.

<Info title="Examples">
  See Cohere's [fern folder](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) and [TypeScript](https://github.com/cohere-ai/cohere-typescript) and [Python](https://github.com/cohere-ai/cohere-python) SDK repositories.
</Info>

## Core configuration files

The source repository contains a `fern/` folder  that is initialized with your API definitions and a top-level `generators.yml` file.

### `fern.config.json`

The `fern.config.json` file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds.

```json title="fern.config.json"
{
  "organization": "plant-catalog",
  "version": "5.12.0"
}
```

<Info>
  When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.
</Info>

### `generators.yml`

The `generators.yml` file declares your API spec location in the `api.specs` section and configures SDK generation in the `groups` section.

```yaml title="generators.yml"
# API declaration
api:
  specs:
    - openapi: ./openapi/openapi.yml

# SDK generation
groups:
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 3.69.0
        github:
          repository: your-organization/typescript-sdk-repo

  python-sdk:
    generators:
      - name: fernapi/fern-python-sdk
        version: 5.10.0
        github:
          repository: your-organization/python-sdk-repo
```

<Info title="Examples">
  See Cohere's [`generators.yml` file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) and Vapi's [`generators.yml` file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml).
</Info>

See the [`generators.yml` reference page](/sdks/reference/generators-yml) for complete configuration options.

### API definition file

See [Project structure (API Definitions)](/api-definitions/overview/project-structure) for details on organizing your API definition files and working with multiple APIs.