Skip to main content

Git Repository Structure

This document details best practices for structuring projects within a git repository.

info

The following content is recommended.

Rationale​

Having a consistent git repo structure makes identifying and maintaining git repositories easier for engineers.

Separating applications from shared packages and libraries allows engineers to quickly identify what parts of the repository are core to the application and what parts are part of the repository management itself.

By following this approach we also prepare the repo to use monorepo tools such as Lerna or Nx which favour this structure.

One common pattern was to include every package within the root of the repository. This makes it difficult to group application packages together and makes it unclear where the starting point of the application is.

Description​

The structure of a git repository should be consistent across all projects. This allows for easy navigation and understanding of the project structure. By following the conventions outlined in this document it will be easier to identify and maintain git repositories.

Structure Guidelines​

Overview​

root/
├─ apps/
│  ├─ my-amazing-app/
│  │  ├─ infrastructure/
│  │  │  ├─ package.json
│  │  │  └─ lib/
│  │  └─ client/
│  │     ├─ package.json
│  │     └─ src/
│  └─ our-superb-app/
│     ├─ infrastructure/
│     │  ├─ package.json
│     │  └─ lib/
│     └─ client/
│        ├─ package.json
│        └─ src/
├─ docs/
├─ packages/
│  ├─ ui-components/
│  │  ├─ button/
│  │  └─ carousel/
│  ├─ data-api-lambda/
│  │  ├─ package.json
│  │  └─ src/
│  │     └─ index.ts
│  └─ notification-lambda/
│     ├─ package.json
│     └─ src/
│        └─ index.ts
├─ .gitignore
├─ package.json
└─ README.md

Root files​

The root of the repository should contain repository-wide configuration files. This includes, for example:

  • .gitignore
  • .prettierrc
  • .eslintrc
  • package.json
  • README.md
  • .nvmrc

These files are shared across all packages within the repository and do not contain any application specific configuration. They are used to manage the repository itself.

Docs​

The root of the repository should also contain a docs directory. This is used to store documentation on the products that this repository contains. More information on documentation can be found in the documentation best practice.

Apps​

The root of the repository should contain an apps directory. This is used to store the applications that this repository contains. Each sub-directory of the apps directory should contain a single application. It is recommended that each application directory has a descriptive name such that it is clear what the application is and can be referenced in the documentation. Within each application directory the package that is the entry point of the application should be contained here. It is also customary to put the frontend entry point here if also applicable. By doing this we keep the backend and frontend parts of the application together.

Packages​

The root of the repository should contain an packages directory (sometimes also referred to as libs). This is used to store the packages that this repository contains. Each sub-directory of the packages directory should contain a single package. These packages will contain the business logic, lambdas, UI components, tools, typings etc for the applications within the repository. It is recommended to have this approach such that there is clear separation between components. Each component should have it's own tests, documentation, dependencies and versioning. This allows for each component to be developed and maintained independently.

You may also wish to group packages here into sub-directories if this is convenient for your product. For example, you may wish to group all of your UI components together.

Examples​