ADR 0001: Monorepo with Turborepo + pnpm

Status: Accepted
Date: 2026-04-14
Deciders: Ideony team

Context

Ideony ships a mobile app (Expo), a NestJS API, and several shared packages (types, validators, api-client, design-tokens). These layers share TypeScript types, Zod schemas, and build tooling. Keeping them in separate repositories would require versioned package publishing for every shared-type change during early MVP iteration.

Decision

Use a single monorepo managed by Turborepo 2.9 + pnpm workspaces. Shared packages live under packages/; applications under apps/. Turborepo remote cache (Vercel) is enabled for build, typecheck, lint, and test tasks.

Consequences

Single pnpm install bootstraps the whole stack; type changes propagate immediately without publishing.
Turborepo remote cache cuts CI wall time significantly on cache hits.
pnpm deploy produces a flat node_modules snapshot for Docker builds (no symlinks).

All packages share one lock-file; a dep conflict in any package affects the whole tree.
Turborepo cache invalidation is opaque; stale cache hits can hide real build failures.
CI matrix complexity increases (lint / typecheck / build / test per workspace).

Alternatives considered

Separate repos per app — rejected: shared types require npm publish loop on every change, adds overhead during MVP sprint.
Nx — rejected: higher config surface area; Turborepo sufficient for this scale.