high-level-structure.md

High-level file system organization for company-wide monorepo

The following are some high level options for organizing a company-wide monorepo.

This is assuming use of a multi-package system like Yarn, Bolt, or Lerna.

Option 1: Flat

Keep all of the packages at the top level so that you don't have to navigate deep into folders to find the package you are looking for. It's always one cd package-name away. It does mean that you have to name folders carefully so that related ones get grouped together.

/repo/
  /bitbucket-app-foo/
  /bitbucket-app-bar/
  /bitbucket-component-button/
  /bitbucket-component-modal/
  /jira-app-baz/
  /jira-app-bat/
  /jira-component-button/
  /jira-component-dropdown/
  /.../

Option 2: Org first, category second

Grouping things together by org means that members of that org can focus just on the parts they care about. It also means that there's no question about what org a given package belongs to.

/repo/
  /bitbucket/
    /apps/
      /foo/
      /bar/
    /components/
      /button/
      /modal/
  /jira/
    /apps/
      /baz/
      /bat/
    /components/
      /button/
      /dropdown/
  /.../

Option 3: Category only

/repo/
  /apps/
    /bitbucket-foo/
    /bitbucket-bar/
    /jira-baz/
    /jira-bat/
  /components/
    /button-bitbucket/
    /button-jira/
    /modal/
    /dropdown/
  /.../

Option 4: Org only, custom inside

/repo/
  /bitbucket/
    /app-foo/
    /app-bar/
    /component-button/
    /component-modal/
  /jira/
    /apps/
      /foo/
      /bar/
    /components/
      /buttons/
        /button/
      /dropdowns/
        /dropdown/
  /.../

Option 5: Org only, flat inside

/repo/
  /bitbucket/
    /app-foo/
    /app-bar/
    /component-button/
    /component-modal/
  /jira/
    /app-baz/
    /app-bat/
    /component-button/
    /component-dropdown/
  /.../