Skip to main content
Project tour shows the top level. This page goes one level down.

The API (apps/api)

An endpoint stays thin: it validates input and calls a service, and the service does the work through a repository in db/repositories/. apps/api/CLAUDE.md is the full contract.

The web app (apps/web)

Folders in parentheses, such as (main), are Next.js route groups: they share a layout without adding to the URL. API request and response types are generated from the API’s OpenAPI schema into @gaia/shared/api/generated, never written by hand. apps/web/CLAUDE.md covers state, components and styling.

Shared libraries

The Python apps get gaia-shared through the uv workspace, so uv sync installs it. Shared code goes here rather than being copied between apps.

Packages

packages/cli is the gaia command, published to npm as @heygaia/cli. CLI internals covers trying and releasing it. packages/gaia-ui holds only a README: the @heygaia/ui component kit lives in its own repository.

How Nx runs everything

Every app, library and package is an Nx project with a project.json that declares its targets: dev, build, lint, type-check, test and so on. The root mise tasks call Nx, and Nx runs the targets in dependency order, in parallel, and caches the result so unchanged projects are skipped.
Project names mostly match the folder (api, web, mobile, desktop, voice-agent, cli, docs, wake-word), with a few exceptions: the bots are bot-discord, bot-slack, bot-telegram, bot-whatsapp and bot-imessage, the bot simulator is bot-harness, the shared bot tests are bots-e2e, the shared libraries are shared-python and shared-typescript, and the Docker services are docker. mise can also run a task defined in an app’s own mise.toml from the root, with // syntax: mise //apps/api:mypy runs mypy from apps/api/mise.toml. Commands lists them.

Next

Conventions

How GAIA code is written: style, commits, design.