Skip to main content
A reference for working in the codebase: layout, commands, tests, builds, migrations, and operational checks. Artifacts is a Bun and Turborepo monorepo with web, API, CLI, and shared domain packages.

​
Repository Layout

apps/
  web/      Next.js app router web app
  api/      Hono API service
  cli/      Commander-based artifacts CLI
packages/
  access/   Artifact authorization helpers
  artifact/ Artifact, project, audit, profile, and share-link services
  auth/     Better Auth and API key service
  billing/  Dodo Payments plans, entitlements, usage, and webhooks
  config/   Environment loading
  db/       Drizzle schema and migrations
  mcp/      MCP tool registry and handlers
  policy/   Role, scope, and action policy
  shared/   Shared schemas, slugs, principals, and URL helpers
  storage/  S3-compatible storage adapter
  workspace/ Workspace, membership, and invitation services

​
Common Commands

CommandPurpose
bun installInstall dependencies
bun run devStart web and API dev servers
bun run buildBuild all packages/apps through Turbo
bun run typecheckType-check all workspaces
bun run lintRun repository lint command, currently TypeScript checks
bun run testRun all tests
bun run db:migrateApply Drizzle migrations
bun run db:generateGenerate Drizzle migrations
bun run cli:buildBuild the CLI
bun run cli:installInstall local CLI into ~/.local/bin
bun run cli:build:prodBuild production Node CLI with baked URLs
bun run cli:build:release:env-fileBuild public CLI installer assets from .env
node apps/cli/dist/cli.js <command>Run built CLI from repo root

​
Type Checking

Run the whole repo: 
bun run typecheck
Run one workspace: 
bun run --filter @agent-artifacts/api typecheck
bun run --filter @agent-artifacts/web typecheck
bun run --filter @agent-artifacts/cli typecheck

​
Tests

Run all tests: 
bun run test
Run package tests directly: 
bun run --filter @agent-artifacts/cli test
bun run --filter @agent-artifacts/web test
Optional browser smoke tests live in apps/web/e2e. Start dev servers first, install Playwright browsers once, then run: 
bunx playwright install
bun run --filter @agent-artifacts/web test:e2e

​
Database Workflow

Schema lives in packages/db. Migration files live in packages/db/drizzle. After changing schema: 
bun run db:generate
bun run db:migrate

​
CLI Development

Build: 
bun run cli:build
Run without installing: 
node apps/cli/dist/cli.js schema
Run from TypeScript source: 
bun run --filter @agent-artifacts/cli dev -- schema
The CLI command registry lives in apps/cli/src/commands.

​
API Development

The API is a Hono service. Route registration starts in apps/api/src/routes/index.ts. Important route modules:
  • artifacts.ts
  • projects.ts
  • profile.ts
  • workspaces.ts
  • workspace-invitations.ts
  • api-keys.ts
  • billing.ts
  • share-links.ts
Domain services are built in apps/api/src/deps.ts and mostly live under packages/.

​
MCP Development

MCP tool definitions live in packages/mcp/src/index.ts. Each tool has:
  • description
  • Zod schema
  • handler
The exported listMcpTools() function converts the registry to JSON Schema for discovery.

​
Operational Checks

Health endpoint: 
curl "$API_URL/health"
Recommended monitors:
MonitorURLPurpose
API health<api-host>/healthContainer alive
Web root<public-app-url>/Frontend reachable
OAuth callback<public-app-url>/api/auth/callback/googleDetect auth misconfiguration
SSL certificateApex domainCert expiry

​
Logging

The API logs request ID, method, path, status, duration, user or principal attribution, user agent, and optional trusted proxy IP. Audit events are mirrored to logs without metadata. The web app reports Web Vitals and client/runtime failures when Better Stack browser tokens are configured.