Monorepo & Local Development

Layout

• apps/ — deployable applications (client, server, docs)
• crons/ — scheduled/background services (backup, cleanup)
• packages/ — shared libraries (db, types)
• Root configs: package.json, turbo.json, bunfig.toml, biome.json, docker-compose.yml

Package management

• Package manager: Bun 1.x (root packageManager: bun@1.3.0)
• Workspaces: workspaces: apps/*, packages/*, crons/*
• Bun install strategy:
  • Prefer workspace references ("workspace:*") for internal deps

Root scripts (from package.json)

• bun dev — sets .env from environments/.env.development then runs Turbo dev
• bun run db_push:<env> — sets env then runs Drizzle Kit push (packages/db/drizzle.config.ts)
• bun build — docker-compose build
• bun start — docker-compose up
• bun clean — removes all node_modules

Turbo tasks (turbo.json)

• dev depends on compile, persistent, uncached
• Client dev depends on server dev (dev#@sharingexcess/client depends on @sharingexcess/server#dev)
• compile outputs: dist/**, .next/**, build/**, out/**

Running locally

• Prereqs: Bun 1.x, Docker (optional), /environments files
• Live development: bun dev at repo root (Turbo orchestrates workspace dev tasks)
• Docker Compose (closer to prod images): bun start (server, client, docs)

Dependencies between workspaces

• apps/server → @sharingexcess/db, @sharingexcess/types
• apps/client → @sharingexcess/types and server build artifacts (Hono exports consumed at runtime/build)
• apps/docs → standalone
• crons/* → standalone; share envs (DB, S3, Sentry)

Environment management

• Local: copy from /environments/.env.<env> to root .env using root scripts
• Docker Compose injects envs per service (docker-compose.yml)
• Railway manages envs per service and environment