managarten/apps/chat/CLAUDE.md

Chat Project Guide

Project Structure

apps/chat/
├── apps/
│   ├── backend/      # NestJS API server (@chat/backend)
│   ├── landing/      # Astro marketing landing page (@chat/landing)
│   ├── web/          # SvelteKit web application (@chat/web)
│   └── mobile/       # Expo/React Native mobile app (@chat/mobile)
├── packages/
│   └── chat-types/   # Shared TypeScript types (@chat/types)
└── package.json

Commands

Root Level

pnpm chat:dev                    # Run all chat apps
pnpm dev:chat:mobile             # Start mobile app
pnpm dev:chat:web                # Start web app
pnpm dev:chat:landing            # Start landing page
pnpm dev:chat:backend            # Start backend server
pnpm dev:chat:full               # Start backend + web + auth together

Mobile App (chat/apps/mobile)

pnpm dev                         # Start Expo dev server
pnpm ios                         # Run on iOS simulator
pnpm android                     # Run on Android emulator
pnpm build:dev                   # Build development version
pnpm build:preview               # Build preview version
pnpm build:prod                  # Build production version

Backend (apps/chat/apps/backend)

pnpm start:dev                   # Start with hot reload
pnpm build                       # Build for production
pnpm start:prod                  # Start production server
pnpm db:push                     # Push schema to database
pnpm db:seed                     # Seed AI models
pnpm db:studio                   # Open Drizzle Studio

Web App (chat/apps/web)

pnpm dev                         # Start dev server
pnpm build                       # Build for production
pnpm preview                     # Preview production build

Landing Page (chat/apps/landing)

pnpm dev                         # Start dev server
pnpm build                       # Build for production
pnpm preview                     # Preview production build

Technology Stack

• Mobile: React Native 0.76.7 + Expo SDK 52, NativeWind, Expo Router
• Web: SvelteKit 2.x, Svelte 5, Tailwind CSS 4
• Landing: Astro 5.16, Tailwind CSS
• Backend: NestJS 10, OpenRouter AI + mana-llm (local), Drizzle ORM, PostgreSQL
• Auth: Mana Core Auth (JWT)
• Types: TypeScript 5.x

Architecture

Backend API Endpoints

Endpoint	Method	Description
/api/v1/health	GET	Health check
/api/v1/chat/models	GET	List available AI models
/api/v1/chat/completions	POST	Create chat completion
/api/v1/conversations	GET	List user conversations
/api/v1/conversations/:id	GET	Get conversation details
/api/v1/conversations/:id/messages	GET	Get conversation messages
/api/v1/conversations	POST	Create new conversation
/api/v1/conversations/:id/messages	POST	Add message to conversation

Environment Variables

Backend (.env)

# Cloud AI models via OpenRouter (optional if using only local models)
OPENROUTER_API_KEY=sk-or-v1-xxx    # Get at https://openrouter.ai/keys

# Local AI via mana-llm service
MANA_LLM_URL=http://localhost:3025 # mana-llm service URL
LLM_TIMEOUT=120000                 # Timeout in ms (default: 120s)

# Database (uses shared Docker PostgreSQL)
DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/chat

# Auth
MANA_CORE_AUTH_URL=http://localhost:3001

# Server
PORT=3002

Mobile (.env)

EXPO_PUBLIC_MANA_CORE_AUTH_URL=http://localhost:3001
EXPO_PUBLIC_BACKEND_URL=http://localhost:3002

Web (.env)

PUBLIC_MANA_CORE_AUTH_URL=http://localhost:3001
PUBLIC_BACKEND_URL=http://localhost:3002

Code Style Guidelines

• TypeScript: Strict typing with interfaces
• Mobile: Functional components with hooks
• Web: Svelte 5 runes mode
• Styling: Tailwind CSS everywhere
• Formatting: 100 char line limit, 2 space tabs, single quotes

AI Models Available

Local Models (Ollama - Free, runs on Mac Mini)

Model ID	Name	Best For
...440101	Gemma 3 4B (Lokal)	Everyday tasks (default)
...440102	Qwen2.5 Coder 7B (Lokal)	Code generation (92.7% HumanEval)
...440103	LLaVA 7B Vision (Lokal)	Image/screenshot analysis
...440104	Qwen3 VL 4B (Lokal)	Fast image analysis
...440105	DeepSeek OCR (Lokal)	Text recognition in images
...440106	Phi 3.5 (Lokal)	Compact, efficient
...440107	Ministral 3B (Lokal)	Very fast, simple tasks

Cloud Models (OpenRouter - Paid)

Model ID	Name	Price	Best For
...440201	Llama 3.1 8B	$0.05/M	Fast cloud alternative
...440202	Llama 3.1 70B	$0.35/M	Complex reasoning
...440203	DeepSeek V3	$0.14/M	Reasoning at low cost
...440204	Mistral Small	$0.10/M	General tasks
...440205	Claude 3.5 Sonnet	$3/M	Best quality
...440206	GPT-4o Mini	$0.15/M	Balanced performance

Adding New Local Models

# Add new models to existing database
pnpm --filter @chat/backend db:add-local-models

Quick Start

1. Get OpenRouter API key at https://openrouter.ai/keys
2. Create .env in apps/chat/apps/backend/:

   OPENROUTER_API_KEY=sk-or-v1-xxx
   DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/chat
   MANA_CORE_AUTH_URL=http://localhost:3001
   PORT=3002
   

3. Start services:

   pnpm docker:up              # Start PostgreSQL
   pnpm dev:chat:full          # Start auth + backend + web
   

4. Seed database (first time only):

   pnpm --filter @chat/backend db:push
   pnpm --filter @chat/backend db:seed
   

Important Notes

1. Security: API keys are stored in the backend only - never in client apps
2. Authentication: Uses Mana Core Auth (JWT tokens)
3. Database: PostgreSQL with Drizzle ORM (uses shared Docker container)
4. Deployment: Backend runs on port 3002