AGENTS.md

This document provides comprehensive instructions for AI coding agents to work effectively on the AI SaaS Boilerplate project. It covers the architecture, setup, development workflow, and coding conventions.

1. Project Overview

AI SaaS Boilerplate is an AI-powered SaaS platform built as a monorepo. It provides intelligent web search, deep research capabilities, document creation, audio-to-text processing, and document comparison features.

1.1. Architecture

The repository is managed by Turborepo and Bun.

Applications (apps/):
- app: The core Next.js application (Dashboard, Chat, Projects, Tools). Handles AI streaming, user data, and search workflows.
- admin: Internal admin dashboard for moderation, user management, and analytics. Includes chat/message flagging system.
- web: The public marketing site.
Packages (packages/):
- @ai/db: PostgreSQL schema and queries (Drizzle ORM).
- @ai/auth: Authentication logic (Better Auth).
- @ai/ui: Shared UI components (Shadcn UI + Tailwind v4).
- @ai/i18n: Internationalization (next-intl). Supports English and Russian.
- @ai/tracing: Distributed tracing infrastructure for workflow observability.
- @ai/email: Transactional emails (React Email).
- @ai/kv: Redis client and Rate Limiting.
- @ai/storage: S3/MinIO client for file management.
- @ai/analytics: OpenPanel integration for user analytics.
- @ai/jobs: Background jobs (BullMQ + Redis). Worker system for scheduled and async tasks.
- @ai/logger: Structured logging (Pino) + OpenTelemetry metrics export.
- @ai/billing: Usage tracking, cost calculation, limit checking, and subscription management.
- @ai/stripe: Stripe payment gateway integration.
- @ai/memory: Memory and context management (Qdrant + Mem0AI). Vector storage for conversation memory.
- @ai/converter: Document conversion utilities (JSZip). File format transformations.

1.2. Technology Stack

Runtime: Bun 1.1.26
Framework: Next.js 16+ (App Router)
Styling: Tailwind CSS v4 (Configuration in CSS variables, not JS config)
Database: PostgreSQL 17 + Drizzle ORM 0.44
Auth: Better Auth 1.3 (Magic Links, Phone OTP)
AI: Vercel AI SDK v6 (Core + React), Groq, OpenAI, DeepSeek
Search/Scraping: SearXNG (Self-hosted), BrowserUse (Scraping API)
Payment Processing: Stripe
Background Jobs: BullMQ + Redis
Memory/RAG: Qdrant (Vector DB) + Neo4j (Graph DB) + Mem0AI
Observability: OpenTelemetry + SigNoz (metrics export)
Internationalization: next-intl (English default, Russian supported)
Infrastructure: Docker Compose (PostgreSQL, Redis, MinIO, SearXNG, MailDev, unstructured-api, Qdrant, Neo4j, converter, optional worker service)

2. Development Workflow

2.1. Package Management

Always use Bun. Do not use npm or yarn.

bun install

Adding dependencies to packages:

The root package.json is private and should only have devDependencies. Always declare dependencies in the specific package that needs them.

IMPORTANT: The --filter flag does NOT work for adding dependencies to specific packages. You must cd into the package directory:

# CORRECT: Navigate to package and add dependency
cd packages/billing
bun add js-tiktoken

# Add dev dependency
cd apps/app
bun add -D @types/node

Then run:

bun install

DO NOT add dependencies to root package.json — it should only contain devDependencies for tooling (biome, husky, turbo, typescript).

2.2. Running the Project

Start the development environment:

# 1. Start backing services
docker compose up -d

# 2. Run migrations (if needed)
bun db:migrate

# 3. Start dev server
bun dev

2.3. Database Management

Schema changes must be made in packages/db/src/schema.ts.

# Push changes for prototyping (destructive)
bun db:push

# Generate migration files (production)
bun db:generate

# Apply migrations
bun db:migrate

2.4. Background Jobs

Technology: BullMQ + Redis (NOT Trigger.dev)

Location: packages/jobs/

Architecture:

worker.ts: Main worker entry point
src/workers/: Individual worker implementations
src/schedulers/: Scheduled job registration
Dockerfile for containerized worker deployment

Available Workers:

hello-world: Test/example worker
audio-processing: Audio-to-text processing
file-indexing: File indexing for search/RAG
log-cleanup: Database log cleanup and maintenance

Running Workers:

# Development (local)
bun run dev:worker

# Development (watch mode)
bun --watch run worker.ts

# Production (Docker)
docker compose --profile worker up -d

Adding a New Job:

Create worker in packages/jobs/src/workers/my-worker.ts
Register in worker.ts
Define job types and queue configuration
Queue from app: await myQueue.add("job-name", { data })

3. Architectural Patterns & Conventions

3.1. Server Actions (Mutations & Data)

We use next-safe-action located in apps/app/src/actions/.

Pattern:

Define Schema: In schema.ts (Zod).
Define Logic: In actions.ts.
Use Raw Helpers: Complex DB logic goes into raw.ts to be reusable.
Clients:
- authActionClient: For authenticated user actions.
- actionClient: For public actions.

Example:

// apps/app/src/actions/project/actions.ts
export const createProjectAction = authActionClient
  .inputSchema(createProjectSchema)
  .outputSchema(getUserProjectOutputSchema)
  .metadata({ name: "create-project" })
  .action(async ({ parsedInput, ctx: { user } }) => {
    // Logic here
  });

3.2. AI & Chat Architecture

The chat implementation (apps/app/src/app/api/chat/route.ts) is complex and sophisticated. This section breaks down its modular architecture.

3.2.1. Overview

Key Components:

Resumable Streams: We use resumable-stream to handle network interruptions
Handler-Based Architecture: Modular handlers for different execution paths
Memory System: Conversation memory with Qdrant + Neo4j integration
Tracing: Distributed tracing via @ai/tracing for observability
Usage Tracking: Automatic token tracking for billing and metrics

Complexity Note: The AI system has multiple execution paths with conditional routing based on user settings and workflow classification.

3.2.2. Handler-Based Architecture

The AI system uses a modular handler architecture in apps/app/src/lib/ai/handlers/:

Handlers:

search-classifier.ts: Classifies search requests and determines execution path
search-plan-handler.ts: Generates search execution plans
search-agent-handler.ts: Executes search workflows (search → scrape → process)
clarification-handler.ts: Manages clarification questions for ambiguous intent
deep-search-handler.ts: Manages deep research with extreme_search integration
final-reasoning-handler.ts: Generates final responses from gathered context
rerank-handler.ts: Reranks search results for relevance
document-creation-handler.ts: Handles document/artifact creation and editing
complexity-detector.ts: Auto-routes complex questions to deep search based on heuristics
deep-search-document-handler.ts: Creates documents from deep research results
document-processing-handler.ts: Prepares messages with file processing progress

Request Flow:

Request arrives at /api/chat/route.ts
Check usage limits (@ai/billing)
Optimize messages for context window (summarization if needed)
Build memory context (if enabled)
Complexity detection: Auto-route to deep search if complex patterns detected
Evaluate deep search decision: Determine if deep research is needed
If deepResearch enabled or auto-triggered:
- Ask clarification if needed
- handleDeepSearch() → Optional: executeDeepSearchDocumentCreation() → RETURN
If standard mode:
- classifySearchRequest() → determine path
- If document creation → Optional: executeSearchForContext() → executeDocumentCreation() → RETURN
- Else → executeSearchAgent() → executeFinalReasoning()
Clarification questions can interrupt at any decision point
Memory extraction runs post-response (fire-and-forget)

3.2.3. Memory System

Location: apps/app/src/lib/ai/memory/

Purpose: Manages conversation memory and context for personalized responses.

Components:

context-builder.ts: Builds memory context from previous conversations
extraction-handler.ts: Extracts and stores memories from conversations
summarization-handler.ts: Handles message summarization for context windows

Memory Scopes (via @ai/memory):

Chat-scoped: Memories tied to specific conversations
Project-scoped: Memories shared across all chats in a project
File content: Indexed file contents for RAG

Integration:

Uses @ai/memory package (Qdrant + Mem0AI)
Memory context injected into system prompts
Memories extracted after response generation (fire-and-forget)
High-importance facts auto-promoted to project scope
Enhanced search with relevance filtering

3.2.4. Usage Tracking & Billing Integration

Location: apps/app/src/lib/ai/middleware/usage-tracking.ts

Automatic Token Tracking: Middleware intercepts all AI SDK calls for billing and metrics:

Middleware: usageTrackingMiddleware on all model clients
Helper: withUsageTracking(userId, operation, opts) in providerOptions
Dual Recording:
- @ai/billing: Usage limits and cost calculation
- OpenTelemetry: Metrics export to SigNoz

Tracked Operations:

chat: Standard messages
deep_search: Deep research
classifier: Workflow classification
workflow_execution: Tool execution
deep_search_synthesis: Final synthesis
prompt_enhancement: AI-powered prompt improvement

Example:

const { object } = await generateObject({
  model: getGenerateObjectModel(),
  schema: MySchema,
  providerOptions: {
    groq: getDefaultGroqOptions(),
    ...withUsageTracking(userId, "classifier", { chatId }),
  },
});

Pre-request Limits: /api/chat/route.ts calls checkUsageLimits() before processing.

3.2.5. Tools & Prompts

Core Tools (apps/app/src/lib/ai/tools.ts):

search: Multi-query web search via SearXNG with site filtering
scrape: Website content extraction via BrowserUse API with iterative chunking
reasoning: Final answer/analysis tool (marks completion)

Domain-Specific Tools (apps/app/src/lib/ai/tools/):

artifact-tools.ts: Document creation and editing
- createArtifactTool(): Creates new documents
- createUpdateArtifactTool(): Updates existing documents
document-tools.ts: File attachment handling
- extractFileAttachmentsFromMessages(): Extracts file content from messages

Tool Factories:

createSearchTool(contexts): Creates search with context filtering
createScrapeWebsiteTool(usedUrls, query, writer, tracking): Creates scraping with deduplication

Prompts:

Main: apps/app/src/lib/ai/prompts.ts (systemPrompt, titlePrompt, classifierPrompt)
Additional prompts: codePrompt, sheetPrompt, updateDocumentPrompt, searchClassifierPrompt

Model Configuration (apps/app/src/lib/ai/clients.ts):

Primary: groq("openai/gpt-oss-120b") with usage tracking middleware
Fallback: openai("gpt-5-nano") with usage tracking middleware
Unwrapped: openai("gpt-5-nano") without tracking (for tool repair)

Extreme Search: Location: apps/app/src/lib/ai/extreme-search.ts

Multi-step autonomous research workflow with planning, execution, and synthesis phases.

3.3. Artifact System

Location: apps/app/src/lib/ai/artifacts/

Purpose: Manages document creation, editing, and patching.

Components:

text-handler.ts: Handles text document creation
patch-handler.ts: Handles document updates via patches
index.ts: Exports and utilities

Integration:

Used by document-creation-handler.ts
Tools in tools/artifact-tools.ts
API route at /api/artifact/*

3.4. UI & Styling (Tailwind v4)

Crucial: This project uses Tailwind CSS v4.

Configuration: Theme variables are defined in packages/ui/src/globals.css using the @theme directive.
Do not look for tailwind.config.js for theme extension.
Dark Mode: Handled via oklch color variables and the .dark class.

Example globals.css:

@theme inline {
  --color-background: var(--background);
  --color-sidebar: var(--sidebar);
  /* ... */
}

3.5. State Management (SWR)

Client-side data fetching uses SWR.

Global app state is managed in apps/app/src/components/use-app-state.ts.
Use useDashboardApp() hook to access global state (chats, projects, modals).

3.6. File Storage

Uploads: Use the API route /api/files/upload-url to get a presigned URL.
Storage: Files are stored in MinIO (S3 compatible).
Database: File metadata is stored in the file table in Postgres.

3.7. Billing & Subscription System

Location: packages/billing/

Core Modules:

cost-calculator.ts: Calculates LLM usage costs in microcents
limit-checker.ts: Checks if user is within plan limits
usage-tracker.ts: Records and aggregates usage data
types.ts: Plan definitions and limit structures

Integration Points:

/api/billing/*: Plans, subscriptions, usage, payments, webhooks
/api/chat/route.ts: Pre-request limit checking via checkUsageLimits()
middleware/usage-tracking.ts: Automatic token recording
@ai/stripe: Payment processing

Plan Limits: Plans define limits for:

Messages per period
Deep searches per period
Max file size uploads
Token usage quotas

Usage Flow:

User sends chat request
checkUsageLimits() validates against plan
Request processes if allowed
usageTrackingMiddleware records tokens
recordUsage() saves to database
recordLLMUsage() exports to SigNoz

3.8. Internationalization (i18n)

Location: packages/i18n/

Technology: next-intl v4.8

Supported Locales:

en (English) - Default
ru (Russian)

Structure:

packages/i18n/src/config.ts: Locale configuration
packages/i18n/src/messages/: Package-level message definitions
apps/app/messages/: App-specific JSON translations
apps/admin/messages/: Admin-specific JSON translations

Usage:

import { useTranslations } from "next-intl";

function MyComponent() {
  const t = useTranslations("common");
  return <div>{t("greeting")}</div>;
}

3.9. Tracing System

Location: packages/tracing/

Purpose: Distributed tracing for AI workflow observability.

Key Components:

span-manager.ts: Span creation and lifecycle management
context.ts: Tracing context propagation
streaming.ts: Real-time span/trace updates via SSE

Wrappers:

traceHandler(): Wrap AI handlers
traceAction(): Wrap server actions
withRouteTracing(): Wrap API routes

Integration: Traces are stored in PostgreSQL and can be viewed in the admin dashboard at /traces.

4. Infrastructure & Services

4.1. Docker Services

docker-compose.yml services:

postgres: PostgreSQL 17 (main database)
redis: Redis 7.4 (cache, rate limiting, BullMQ)
minio: S3-compatible object storage
createbuckets: MinIO bucket initialization
maildev: Email testing (captures outgoing emails)
searxng: Self-hosted search engine
unstructured-api: Document parsing API
qdrant: Vector database for memory/RAG system
neo4j: Graph database for memory relationships (Neo4j 5.26)
converter: Document converter service
worker: BullMQ background job processor (optional profile)

Commands:

# Start all services
docker compose up -d

# Start with worker
docker compose --profile worker up -d

# View logs
docker compose logs -f [service-name]

# Restart service
docker compose restart [service-name]

4.2. Observability & Monitoring

OpenTelemetry Integration: Location: packages/logger/src/

Logger Components:

pino-logger.ts: Structured logging setup
metrics-exporter.ts: OTLP metrics export to SigNoz
db-exporter.ts: Database log export for persistence
telegram-exporter.ts: Telegram notification export for alerts

Metrics Exported:

LLM usage (tokens, provider, model, operation, user, chat)
Token counts (input/output)
Per-user, per-operation aggregations

Functions:

initializeMetricsExporter(): Sets up OTLP export to SigNoz
recordLLMUsage(attributes, usage): Records LLM metrics
shutdownMetricsExporter(): Graceful shutdown
exportLogToDb(): Exports logs to database
sendTelegramAlert(): Sends critical alerts to Telegram

5. Coding Rules for Agents

"Use Server": Always add "use server" at the top of Server Actions.
Type Safety:
- No any. Use Zod schemas for runtime validation.
- Share types via apps/app/src/lib/types.ts.
Imports:
- Use @/ alias for app-local imports.
- Use @ai/* for package imports.
Error Handling:
- Server Actions should return errors, not throw them (handled by next-safe-action).
- UI should use sonner for toast notifications.
Components:
- Place page-specific components in apps/app/src/components/pages/.
- Place shared/atomic components in packages/ui/src/components/.
Internationalization:
- The app defaults to English with Russian as secondary.
- Use useTranslations() hook for UI text.
- Add new strings to apps/app/messages/en.json and apps/app/messages/ru.json.
Server Actions Pattern (Important):
- The documented pattern (schema.ts, actions.ts, raw.ts) is IDEAL
- Reality: Only project/ and chat/ actions fully follow this pattern
- user/ actions: Direct action files (no raw.ts)
- Guideline: Prefer full pattern for NEW actions, but adapt to existing conventions in each domain
AI Usage Tracking (Critical):
- Always wrap AI SDK calls with withUsageTracking() in providerOptions
- Include: userId and operation type (required)
- Optional: chatId, provider, model
- Ensures proper billing and metrics export
Background Jobs:
- Use BullMQ for async/scheduled tasks (NOT Trigger.dev)
- Define jobs in packages/jobs/src/workers/
- Register in worker.ts
- Jobs run in separate worker process (not Next.js)
Payment Integration:
- Use @ai/stripe for payment processing
- Handle webhooks in /api/billing/webhook
- Always verify webhook signatures (Stripe signature verification)
- Stripe handles subscription renewals automatically
- Use Stripe Customer Portal for self-service subscription management
Memory System:
- Use @ai/memory for storing/retrieving conversation memories
- Memory context is built via context-builder.ts
- Extraction happens post-response via extraction-handler.ts
Tracing:
- Use @ai/tracing wrappers for observability
- Wrap handlers with traceHandler()
- Wrap actions with traceAction()

6. Directory Structure Reference

Application Structure

apps/app/src/
├── actions/                # Server Actions
│   ├── chat/              # Chat actions (full pattern)
│   │   ├── schema.ts
│   │   ├── actions.ts
│   │   └── raw.ts
│   ├── project/           # Project management (full pattern)
│   │   ├── schema.ts
│   │   ├── actions.ts
│   │   └── raw.ts
│   ├── audio-processing/     # Audio Processing actions
│   │   ├── schema.ts
│   │   ├── actions.ts
│   │   └── raw.ts
│   └── user/              # User actions
│       ├── schema.ts
│       └── usage-action.ts
├── app/                   # Next.js App Router
│   ├── (dashboard)/       # Authenticated pages
│   ├── (public)/          # Public pages
│   └── api/               # API routes
│       ├── artifact/      # Artifact management
│       ├── auth/          # Better Auth endpoints
│       ├── billing/       # Plans, subscriptions, payments, webhooks
│       ├── chat/          # Chat streaming + resumable
│       ├── files/         # Upload/download
│       ├── tools/   # Audio Processing, comparison
│       └── share/         # Sharing functionality
├── components/            # React components
│   ├── message/           # Chat UI components
│   ├── pages/             # Page-specific components
│   ├── providers/         # Context providers
│   └── use-app-state.ts   # Global SWR state (useDashboardApp hook)
├── i18n/                  # App i18n configuration
│   ├── navigation.ts
│   ├── request.ts
│   └── routing.ts
├── messages/              # Translation files
│   ├── en.json
│   ├── ar.json
│   ├── de.json
│   ├── es.json
│   ├── fr.json
│   ├── pt.json
│   └── ru.json
└── lib/                   # Core utilities
    ├── ai/                # AI system (COMPLEX)
    │   ├── artifacts/     # Document creation/editing
    │   ├── config/        # Provider options
    │   ├── evaluation/    # Content evaluation
    │   ├── handlers/      # Handler architecture (11 handlers)
    │   ├── memory/        # Memory system
    │   ├── middleware/    # Usage tracking middleware
    │   ├── tools/         # Domain-specific tools
    │   ├── types/         # AI type definitions
    │   ├── utils/         # AI utilities
    │   ├── clients.ts     # Model clients (groq, openai)
    │   ├── extreme-search.ts  # Deep research engine
    │   ├── prompts.ts     # System prompts
    │   └── tools.ts       # Core tool definitions
    ├── auth.ts            # Better Auth setup
    ├── mappers.ts         # DB to UI type mappers
    └── types.ts           # Shared types

Admin Application Structure

apps/admin/src/
├── actions/              # Admin Server Actions
│   └── moderation/       # Chat/message moderation
├── app/                  # Next.js App Router
│   ├── (auth)/           # Admin authentication
│   ├── (dashboard)/      # Admin dashboard pages
│   │   ├── chats/        # Chat browsing & moderation
│   │   ├── traces/       # Trace viewing
│   │   ├── users/        # User management
│   │   ├── subscriptions/# Subscription tracking
│   │   ├── payments/     # Payment history
│   │   ├── usage/        # Usage analytics
│   │   └── logs/         # System logs
│   └── api/              # Admin API routes
├── components/           # Admin UI components
├── i18n/                 # Admin i18n configuration
├── messages/             # Admin translations
└── lib/                  # Admin utilities

Package Structure

packages/
├── analytics/         # OpenPanel integration
├── auth/              # Better Auth
├── billing/           # Usage tracking, limits, costs
├── converter/         # Document conversion (JSZip)
├── db/                # Drizzle ORM + PostgreSQL
├── email/             # React Email templates
├── i18n/              # Centralized internationalization
│   └── src/
│       ├── config.ts      # Locale configuration
│       ├── request.ts     # Server-side utilities
│       ├── navigation.ts  # Client-side navigation
│       └── messages/      # Package-level messages
├── jobs/              # BullMQ background jobs
│   ├── src/workers/   # Worker implementations
│   ├── worker.ts      # Main worker entry
│   └── Dockerfile     # Worker container
├── kv/                # Redis + rate limiting
├── logger/            # Pino + OpenTelemetry
├── memory/            # Memory/RAG system (Qdrant + Mem0AI)
├── storage/           # S3/MinIO client
├── tracing/           # Distributed tracing
│   └── src/
│       ├── span-manager.ts    # Span lifecycle
│       ├── context.ts         # Context propagation
│       ├── streaming.ts       # Real-time updates
│       └── wrappers/          # Handler/action wrappers
├── ui/                # Shared components (60+ components)
│   └── src/
│       ├── components/    # Shadcn components
│       └── globals.css    # Tailwind v4 config
└── stripe/            # Stripe payment gateway

7. Common Tasks

Working with UI Components

Adding a new UI Component:

Create in packages/ui/src/components/my-component.tsx
Export in packages/ui/package.json exports field
Run bun build (or rely on Turbo)
Import in app: import { MyComponent } from "@ai/ui/my-component"

Database Operations

Adding a Database Table:

Edit packages/db/src/schema.ts
Run bun db:generate (creates migration)
Run bun db:migrate (applies migration)
Add queries to packages/db/src/queries.ts if needed

Quick prototyping (destructive):

bun db:push  # Skip migrations, push schema directly

AI Logic Modifications

Modifying AI Logic:

Tools: Edit apps/app/src/lib/ai/tools.ts or add to tools/ subdirectory
Prompts: Edit apps/app/src/lib/ai/prompts.ts
Chat flow: Edit apps/app/src/app/api/chat/route.ts
Handlers: Edit apps/app/src/lib/ai/handlers/*
Memory: Edit apps/app/src/lib/ai/memory/*

Adding a new AI Handler:

Create apps/app/src/lib/ai/handlers/my-handler.ts
Follow existing patterns (accept writer, log, tracking context)
Use withUsageTracking() for all AI calls
Integrate into /api/chat/route.ts main flow

Background Jobs

Creating a Background Job:

Create worker: packages/jobs/src/workers/my-worker.ts
Register in packages/jobs/worker.ts
Export queue from package if needed

Queue from app code:

import { myQueue } from "@ai/jobs";
await myQueue.add("job-name", { data });

Run worker: bun run dev:worker

Adding Translations

Adding new translated strings:

Add to apps/app/messages/en.json:

{
  "myFeature": {
    "title": "My Feature",
    "description": "Description here"
  }
}

Add Russian translation to apps/app/messages/ru.json

Use in component:

const t = useTranslations("myFeature");
return <h1>{t("title")}</h1>;

Infrastructure Management

Docker Services:

# Start all services
docker compose up -d

# Start with worker
docker compose --profile worker up -d

# View logs
docker compose logs -f postgres
docker compose logs -f redis
docker compose logs -f worker
docker compose logs -f qdrant
docker compose logs -f neo4j

# Restart service
docker compose restart searxng

# Stop all
docker compose down

Available services:

postgres, redis, minio, createbuckets, maildev, searxng, unstructured-api, qdrant, neo4j, converter, worker (optional)

API Routes Structure

apps/app/src/app/api/
├── artifact/          # Artifact management
│   ├── route.ts       # Create artifact (POST), Get artifact (GET)
│   ├── export/        # Export artifact to file (POST)
│   └── [id]/
│       ├── route.ts   # Get/update artifact (GET/PATCH)
│       └── patch/     # Apply patches to artifact (PATCH)
├── auth/              # Better Auth endpoints (auto-generated)
│   └── [...all]/
├── billing/           # Billing & subscription management
│   ├── plans/         # GET available plans
│   ├── subscription/  # GET/DELETE user subscription
│   ├── usage/         # GET usage stats
│   ├── checkout/      # POST create Stripe Checkout session
│   ├── portal/        # POST create Stripe Customer Portal session
│   └── webhook/       # POST Stripe webhooks
├── chat/              # AI chat streaming
│   ├── route.ts       # Main chat endpoint (POST)
│   └── [id]/
│       └── stream/    # Resumable stream endpoint (GET)
├── enhance-prompt/    # AI-powered prompt enhancement (POST)
├── files/             # File upload/download
│   ├── upload/        # Direct upload (POST)
│   ├── upload-url/    # Presigned URL generation (POST)
│   └── [id]/          # Get file by ID (GET)
├── tools/       # Domain tools
│   ├── compare/       # Document comparison (POST)
│   └── audio-processing/ # Audio processing
│       ├── route.ts   # Submit audio processing (POST)
│       ├── [id]/      # Get audio-processing status (GET)
│       └── export/    # Export processed output (POST)
└── share/             # Sharing functionality
    └── [token]/       # Share by token
        └── artifact/  # Get shared artifact (GET)

Key Endpoints:

Chat:

POST /api/chat - Send message, get streamed response
GET /api/chat/[id]/stream - Resume interrupted stream

Prompt Enhancement:

POST /api/enhance-prompt - AI-powered prompt improvement

Files:

POST /api/files/upload - Direct file upload
POST /api/files/upload-url - Get presigned S3 URL
GET /api/files/[id] - Download file by ID

Billing:

GET /api/billing/plans - Fetch subscription plans
GET /api/billing/subscription - Get user's subscription
DELETE /api/billing/subscription - Cancel subscription (via Stripe)
GET /api/billing/usage - Get usage statistics
POST /api/billing/checkout - Create Stripe Checkout session
POST /api/billing/portal - Create Stripe Customer Portal session
POST /api/billing/webhook - Handle Stripe webhooks

Artifacts:

POST /api/artifact - Create new artifact
GET /api/artifact/[id] - Get artifact by ID
PATCH /api/artifact/[id] - Update artifact
PATCH /api/artifact/[id]/patch - Apply patches to artifact
POST /api/artifact/export - Export artifact to file format

Tools:

POST /api/tools/compare - Document comparison (PDF, DOCX, DOC, TXT, MD)
POST /api/tools/audio-processing - Submit audio for processing
GET /api/tools/audio-processing/[id] - Get audio-processing status
POST /api/tools/audio-processing/export - Export audio-processing

Sharing:

GET /api/share/[token]/artifact - Get shared artifact by token (public, no auth)

Built for the Age of AI Agents