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:

  1. How many languages or frameworks does your project use?
  2. How many independently deployable units do you have?
  3. Are all your services in one repository or separate repositories?

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
Plugin 1 marketplace 1--2 environments solo or small-team
Library 1 registry (npm, PyPI, etc.) 1--2 environments solo or small-team
CLI 1 Homebrew / GitHub Releases 1--2 environments solo or small-team
Mobile App 1--2 iOS / Android 2--3 environments small-team or standard
Container Image 1 container registry 1--2 environments solo or small-team
Static Site 1 CDN / static host 1--2 environments solo or small-team

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

Multi-Repo / Per-Service

Each service lives in its own git repository. GAIA projects a per-service config slice into each repo so that /gaia-config-ci can generate self-contained workflows without reading the central config.

Plugin

A Claude Code plugin (or any marketplace-distributed extension). Phase 5 routes to /gaia-publish rather than /gaia-deploy because there is no server to deploy to.

Library

A package published to a registry (npm, PyPI, Maven Central, etc.). The release workflow pushes the built artifact to the registry via the configured distribution channel.

CLI

A command-line tool distributed via Homebrew, GitHub Releases, or a custom channel. Phase 5 routes to /gaia-publish.

Mobile App

An iOS or Android application distributed through an app store. Phase 5 routes to /gaia-publish and validates the store submission payload.

Container Image

A Docker image pushed to a container registry. Phase 5 routes to /gaia-publish and tags the image.

Static Site

An HTML/CSS/JS site deployed to a CDN or static-hosting provider. Phase 5 routes to /gaia-publish because there are no smoke endpoints to verify against.

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: