# 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" />
  </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": "3.57.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 configures SDK generation in the `groups` section. For OpenAPI/AsyncAPI, you must also declare your API spec location in the `api.specs` section.

<Tabs>
  <Tab title="OpenAPI/AsyncAPI">
    ```yaml title="generators.yml"
    # API declaration (required for OpenAPI/AsyncAPI)
    api:
      specs:
        - openapi: ./openapi/openapi.yml

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

      python-sdk:
        generators:
          - name: fernapi/fern-python-sdk
            version: 4.50.1
            github:
              repository: your-organization/python-sdk-repo
    ```
  </Tab>

  <Tab title="Fern Definition">
    For Fern Definition, the `api` section isn't needed. Fern auto-detects your API from the `definition/` directory.

    ```yaml title="generators.yml"
    groups:
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
            version: 3.46.3
            github:
              repository: your-organization/typescript-sdk-repo

      python-sdk:
        generators:
          - name: fernapi/fern-python-sdk
            version: 4.50.1
            github:
              repository: your-organization/python-sdk-repo
    ```
  </Tab>
</Tabs>

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

## Setup instructions

1. **Create repositories**: Set up your source repository, plus one repository for each SDK
2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories
3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.