Monorepo Structure

ship-ai is a workspace monorepo managed by Bun and Turborepo.

Top-Level Layout

ship-ai/
  apps/
    app/
    admin/
    web/
  packages/
    analytics/  auth/  billing/  branding/  converter/  db/  email/
    features/   i18n/  jobs/     kv/        logger/     memory/
    storage/    stripe/ tracing/ ui/
  tooling/
    typescript/
  docs/
  docker/
  scripts/
  turbo.json
  package.json
  docker-compose.yml

Workspace Model

Root package.json declares:

• workspaces: apps/*, packages/*, tooling/*
• root scripts for orchestration (dev, build, typecheck, lint, db:*, docker:*)
• root package as private and tool-oriented

Key expectation from project docs: add runtime dependencies to the specific app/package that needs them, not to root.

Turbo Pipeline Behavior

turbo.json defines task-level behavior:

• build depends on upstream ^build, has explicit env inputs, caches outputs
• dev, worker, worker:dev, test, clean, start are non-cached/persistent as appropriate
• typecheck depends on ^topo
• .env is included in relevant task inputs/global dependencies

This means changes in shared packages correctly invalidate dependent app tasks, and local dev runs stay uncached where needed.

App and Package Boundaries

• apps/* own UI routes, request entrypoints, and app-specific orchestration.
• packages/* own reusable capabilities (db, auth, billing, jobs, tracing, storage, ui, and more).
• Cross-app shared logic should generally live in packages/* unless it is tightly app-specific.

Infrastructure Shape

docker-compose.yml defines local backing services:

• Postgres, Redis, MinIO (+ bucket bootstrap), MailDev
• SearXNG, unstructured-api, Qdrant, Neo4j, converter
• optional worker service profile for BullMQ workers

Core product can run in reduced mode by disabling optional feature/service flags.