Repository tour

Ghost is one Bun workspace managed by Turborepo. The root package.json lists apps/* and packages/* as workspaces; turbo.json runs dev, build, test, lint and check-types across all of them.

Top level

apps/
  api/        NestJS: the REST API, the git transport (HTTP and SSH), GitHub compatibility
  web/        Next.js: everything a person clicks
  docs/       Fumadocs: the user guide (port 3003)
  learn/      This course (port 3005)
  delivery/   Go: sends email and webhooks from a Postgres queue
  importer/   Bun: imports a repository from GitHub
  zoekt/      A Dockerfile and script running the Zoekt code search server
packages/
  db/           Drizzle schema, migrations, the migrator and the seed
  permissions/  The role ladder shared by API and web
  references/   Parses `#123`, `owner/repo#123`, `@user`, `@org/team` and closing keywords
  languages/    Linguist-style language detection and colors
docs/           One file per design decision (ADR), code standards, roadmap
docker/         Self-hosting: compose file, Caddyfile, setup scripts
.railway/       Railway infrastructure as code
scripts/        Repository scripts: the standards checker, the version bump

The API is the only thing that touches git, the bucket or most of the database. The web app talks to the API over HTTP like any other client. delivery and importer are separate processes with narrow jobs; each has a lesson in the later chapters.

Inside the API

apps/api/src is organized by what a folder holds, not by feature. This is a rule (code standards, rule 6), and knowing it tells you where to look for anything:

So: a function that parses a git packet is in lib/git/protocol/; the service that spawns git receive-pack is in services/git/pack-process/; the controller for /api/repositories/:owner/:repo/issues is in resources/issues/.

Errors: one pattern everywhere

Expected failures are classes that extend DomainError and carry an HTTP status:

// apps/api/src/domain/errors.ts
export abstract class DomainError extends Error {
  abstract readonly status: number;
}

// apps/api/src/lib/pull-requests/pull-requests.errors.ts
export class PullRequestNotOpenError extends DomainError {
  status: number = HttpStatus.CONFLICT;
  constructor(state: string) {
    super(`This pull request is ${state}`);
  }
}

Services throw them; nothing in a service knows about HTTP. The global DomainErrorFilter renders the status and message. The GitHub compatibility layer has its own filter that renders GitHub's error shape instead. Error classes always live under lib/, never next to the service that throws them.

Packages

packages/db/src/schema/ is the whole data model, one file per area (auth.ts, repository.ts, issues.ts, pull-requests.ts, …). Both the API and the delivery service read the same tables; only packages/db defines them or migrates them.

packages/permissions/src/index.ts holds roleHierarchy and atLeast. The web uses it to hide buttons, the API to decide; one ladder, two consumers.