Project Shapes Overview
The stacks and platforms sections of
project-config.yaml differ depending on what you are
building. A Python CLI tool, a React + Express web application, and
a microservices platform each need different configurations. This
tutorial helps you identify your project shape and links you to the
right shape-specific guide.
What is a project shape?
A project shape describes the structure of your codebase: how many deployable units it contains, which languages and frameworks it uses, and how those units relate to each other.
GAIA uses the stacks configuration to understand your
project shape. Each stack entry represents a distinct part of your
codebase with its own language, test command, and (optionally) its
own path within the repository. The number of stacks and their
relationship determines your shape.
Decision tree
Answer these questions to find your shape:
-
How many languages or frameworks does your project use?
- One → probably Single Repo.
- Two (frontend + backend) → probably Full-Stack.
- Three or more → probably Microservices.
-
How many independently deployable units do you have?
- One → Single Repo.
- Two (frontend deployed separately from backend) → Full-Stack.
- Three or more → Microservices.
-
Are all your services in one repository or separate repositories?
- One repo with one service → Single Repo.
- One repo with multiple services → Full-Stack or Microservices (monorepo).
- Multiple repos → Microservices (polyrepo).
Comparison table
| Project shape | Stacks | Platforms | Promotion chain depth | Recommended CI preset |
|---|---|---|---|---|
| Single Repo | 1 | 1 (web, CLI, or mobile) | 1--2 environments | solo or small-team |
| Full-Stack | 2 | 1--2 (web + API) | 2--3 environments | small-team or standard |
| Microservices (monorepo) | 3+ | 1+ (web, mobile, API) | 3 environments | standard or enterprise |
| Microservices (polyrepo) | 1 per repo | 1+ per repo | 3+ environments | standard or enterprise |
The three shapes
Single Repo
One language, one deployable unit, one directory. Examples: a Python microservice, a Go CLI tool, a Rails web application. This is the simplest shape and needs minimal configuration.
Full-Stack
Two stacks in one repository: a frontend (React, Vue, Angular) and a backend (Express, Django, Rails). Each has its own test runner, build step, and deployment target. The key configuration challenge is path-based CI filters so changes to one stack do not trigger tests for the other.
Microservices
Three or more independently deployable services. Can be organized as a monorepo (all services in one repository) or a polyrepo (each service in its own repository). The key challenges are contract testing between services and coordinated deployments.
What to read next
Pick the shape-specific tutorial that matches your project, then return to the CI and test tutorials to fine-tune your configuration: