ShipAI Documentation

Implementation-focused docs for building, extending, and operating the ship-ai monorepo.

Scope

These docs describe the ship-ai monorepo. This website repository hosts the docs and marketing experience, while implementation details come from the main ship-ai codebase.

ship-ai is a Bun + Turborepo monorepo for an AI chat/research product with billing, admin operations, background jobs, and optional integrations (search, memory, Telegram).

This documentation is reference-first: it maps source files, runtime boundaries, and operational workflows directly to implementation.

Documentation Map

Getting Started

Bootstrap local runtime, configure environments, and fix first-run issues.

Codebase

Understand boundaries across apps, packages, and end-to-end data paths.

Features

Review auth, AI pipeline, billing, search, memory, Telegram, and branding.

Operations

Run migrations, monitor workers/services, and perform maintenance safely.

Deployment

Deploy via Docker or GitLab/Swarm with environment and release checklists.

Recipes

Execute common implementation changes with concise, task-oriented playbooks.

Repository Snapshot

app/

admin/

web/

auth/

billing/

db/

features/

jobs/

memory/

storage/

stripe/

tracing/

ui/

OPTIONAL_SERVICES.md

TELEGRAM_BOT.md

TROUBLESHOOTING.md

package.json

turbo.json

docker-compose.yml

docker-stack.yml

Start Quickly

bun install
bun run setup
bun dev

Use this for fastest reliable first boot on a new machine.

bun install
cp .env.example apps/app/.env
cp .env.example apps/admin/.env
cp .env.example apps/web/.env
docker compose up -d
bun db:migrate
bun db:seed
bun dev

Use this when you want explicit control over each startup stage.

Start by Goal

Go to Getting Started
Follow Setup
Validate env in Configuration
Use Troubleshooting if boot fails

Start with Codebase
Read Monorepo Structure
Continue with Apps and Packages
Finish with Data Flow

Review Features
Review Operations
Apply Deployment guidance
Use Recipes for common implementation tasks

Command Reference

bun dev
bun dev:app
bun dev:admin
bun dev:web
bun dev:worker

bun db:migrate
bun db:generate
bun db:seed
bun db:seed:plans
bun db:studio

bun health
bun health:wait
docker compose ps
docker compose logs -f

bun lint
bun typecheck
bun test
bun build

API Surface (App)

Major route groups in apps/app/src/app/api/*:

auth: Better Auth entrypoint (/api/auth/[...all])
chat: message streaming (/api/chat, /api/chat/[id]/stream)
billing: plans/usage/subscription/checkout/portal/webhook
files: upload URL, upload, file by id
instruments: transcription and compare endpoints
artifact: create, patch, export
webhooks: Telegram webhook endpoint

Use the Features and Data Flow sections for request-level behavior and dependencies.

Reference Baseline

Feature flags (FEATURE_*): control user-visible capabilities like search, memory, and billing enforcement.
Service availability (SERVICE_*): represent whether backing services are deployed/reachable.
Development mode (DEVELOPMENT_MODE): relaxes selected production constraints for local iteration.
Workspace boundaries: apps/* own route/UI orchestration, packages/* own reusable domain/platform logic.
Ground truth docs: authoritative docs in ship-ai that this site should mirror.