This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Sign in to like and favorite skills
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is an AI-powered document processing and chat system built as a monorepo. The system allows users to upload PDF documents, process them using AI models, and engage in intelligent conversations about the document content.
Core Components:
Key Features:
# Installation and workspace management bun install # Install all workspace dependencies using catalog bun run workspace:info # Show workspace package information bun run workspace:update # Update all dependencies to latest versions bun run workspace:check # Run typecheck and lint across workspace # Development bun run dev # Start both backend and frontend in parallel bun run dev:backend # Start only backend (port 3001) bun run dev:frontend # Start only frontend (port 5174) # Building bun run build # Build both backend and frontend sequentially bun run build:watch # Build both packages in watch mode (parallel) bun run build:backend # Build only backend bun run build:frontend # Build only frontend # Testing bun run test # Run root-level Bun tests bun run test:packages # Run tests in all packages bun run test:watch # Run tests in watch mode bun run test:coverage # Run tests with coverage reporting # Code quality bun run typecheck # Run TypeScript checking across all packages bun run lint # Lint all packages with Biome bun run lint:fix # Lint and auto-fix issues bun run format # Format all code with Biome # Maintenance bun run clean # Clean all build artifacts and caches bun run clean:packages # Clean only package-level artifacts
cd packages/backend # Dependencies managed by workspace catalog - install from root # Development bun run dev # Start development server with hot reload (port 3001) bun run start # Start production server # Building bun run build # Build optimized bundle for Bun runtime bun run build:watch # Build in watch mode # Testing and Quality bun run test # Run Bun native tests bun run test:watch # Run tests in watch mode bun run test:coverage # Run tests with coverage bun run typecheck # TypeScript type checking bun run lint # Lint with Biome bun run lint:fix # Lint and auto-fix bun run format # Format code with Biome # Maintenance bun run clean # Clean build artifacts
cd packages/frontend # Dependencies managed by workspace catalog - install from root # Development bun run dev # Start Vite dev server (port 5174) bun run preview # Preview production build # Building bun run build # Build for production bun run build:watch # Build in watch mode # SvelteKit specific bun run check # SvelteKit sync and type checking bun run check:watch # Continuous SvelteKit checking # Testing and Quality bun run test # Run Vitest tests bun run test:watch # Run tests in watch mode bun run test:coverage # Run tests with coverage bun run typecheck # TypeScript type checking bun run lint # Lint with Biome bun run lint:fix # Lint and auto-fix bun run format # Format code with Biome # Maintenance bun run clean # Clean build artifacts and cache
This project uses Bun workspaces with catalogs for optimal dependency management and development experience. The workspace follows bun-reviewer.md best practices for production-ready patterns.
bun.config.tsollama-prompting/ ├── package.json # Root workspace with catalog ├── tsconfig.json # Root TypeScript configuration ├── bun.config.ts # Advanced Bun configuration ├── biome.json # Code quality configuration ├── scripts/ # Workspace utilities │ ├── validate-env.ts # Environment validation │ ├── dev-utils.ts # Development tools │ └── prod-monitoring.ts # Production monitoring └── packages/ ├── backend/ # @ollama-prompting/backend └── frontend/ # @ollama-prompting/frontend
// Root package.json - Centralized version management "workspaces": { "packages": ["packages/*"], "catalog": { "typescript": "^5.9.2", "elysia": "^1.4.5", "svelte": "^5.38.10" // ... all shared dependencies } } // Package usage - Always in sync "dependencies": { "elysia": "catalog:", "typescript": "catalog:" }
The
bun.config.ts// Key configuration highlights export default { preload: ["./scripts/validate-env.ts"], test: { coverage: { enabled: true, threshold: 80 } }, build: { target: "bun", minify: isProduction, sourcemap: isDevelopment ? "inline" : "external" } }
tsconfig.json// Path mapping for workspace packages "paths": { "@ollama-prompting/backend/*": ["packages/backend/src/*"], "@ollama-prompting/frontend/*": ["packages/frontend/src/*"] }
Comprehensive linting and formatting configuration:
BunglobalThisAll code includes proper runtime detection for Bun/Node compatibility:
// Runtime-aware utilities const isBun = () => typeof Bun !== 'undefined'; // Performance measurement const timer = isBun() ? Bun.nanoseconds() : performance.now() * 1_000_000; // File operations const data = isBun() ? await Bun.file('config.json').json() : JSON.parse(await fs.readFile('config.json', 'utf-8'));
Based on the architecture documentation (@docs/architecture.md), this system follows a modern, scalable design:
Core Goals:
/packages/backend/packages/backend/src/services/chatService.tsragService.tspineconeService.tspineconeDocumentService.tsstreamService.tslangsmithService.tskafkaDbService.tsmodelFactory.ts/packages/frontend/packages/frontend/src/routes///ollama-chat/rag-chat/simon/packages/frontend/src/components/LangSmithTraceViewer.svelteNavigation.svelte@tailwindcss/typography@tailwindcss/forms@tailwindcss/container-queries@tailwindcss/aspect-ratioThe system implements three separate RAG pipelines for different use cases:
/api/rag/chat/pineconepineconeService.ts/api/rag/upload-pdf/pinecone/api/rag/chat/pinecone/api/rag/chat/pinecone-documentpineconeDocumentService.ts/api/rag/upload-pdf/pinecone-document/api/rag/chat/pinecone-document/api/rag/chat/couchbaseragService.ts/api/rag/upload-pdf/couchbase/api/rag/chat/couchbaseDocument Processing Flow:
PDF Upload → PDF Loading (LangChain) → Text Splitting → Token Estimation → Text Chunking → AWS Bedrock Embeddings → Vector Storage (Pinecone/Couchbase) → Session/Metadata Storage
Chat Query Flow:
User Query → Query Enhancement → Embedding Generation → Vector Similarity Search → Context Retrieval → Prompt Construction → LLM Generation → Streaming Response
Advanced Features:
GET /api/ollama/modelsGET /api/ollama/chat/historyPOST /api/ollama/chatGET /api/rag/model-infoPOST /api/rag/upload-pdf/pineconePOST /api/rag/upload-pdf/pinecone-documentPOST /api/rag/upload-pdf/couchbasePOST /api/rag/chat/pinecone{ message, sessionId, filename }{ queryType }POST /api/rag/chat/pinecone-document{ message, sessionId, filename }POST /api/rag/chat/couchbase{ message, sessionId, filename }POST /api/kong/chatGET /api/kong/kafka/:topicGET /api/kafkaGET /api/kafka/topics/api/*.envThe backend uses a factory pattern (
modelFactory.tsBased on @docs/architecture.md and @docs/adr/0003-use-pinecone-vector-database.md:
# Pinecone Configuration (Primary Vector Database) PINECONE_API_KEY=your_pinecone_api_key PINECONE_INDEX_NAME=your_index_name PINECONE_NAMESPACE=your_namespace # AI Model Configuration OPENAI_API_KEY=your_openai_api_key HUGGINGFACE_API_KEY=your_huggingface_api_key HUGGINGFACE_MODEL=facebook/opt-1.3b HUGGINGFACE_EMBEDDING_MODEL=nlpaueb/legal-bert-base-uncased # LangSmith Configuration (for AI tracing) LANGCHAIN_TRACING_V2=true LANGCHAIN_API_KEY=your_langchain_api_key LANGCHAIN_PROJECT=your_project_name # AWS Bedrock Configuration AWS_REGION=eu-central-1 AWS_ACCESS_KEY_ID=your_access_key_or_DUMMY AWS_SECRET_ACCESS_KEY=your_secret_key_or_DUMMY AWS_BEARER_TOKEN_BEDROCK=your_bearer_token # Bedrock Models BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v1 BEDROCK_CHAT_MODEL=anthropic.claude-3-5-sonnet-20240620-v1:0 BEDROCK_MAX_TOKENS=4096 BEDROCK_TEMPERATURE=0.7 BEDROCK_TOP_P=0.9 # Model Selection CHAT_MODEL=OpenAI|HuggingFace|Ollama|Bedrock OPENAI_MODEL=gpt-3.5-turbo EMBEDDING_MODEL=Bedrock # Ollama Configuration (if using local models) OLLAMA_HOST=http://localhost:11434 OLLAMA_MODEL=llama2 # Optional: Couchbase (for chat history) COUCHBASE_URL=couchbase://localhost COUCHBASE_USERNAME=your_username COUCHBASE_PASSWORD=your_password COUCHBASE_CHAT_BUCKET=chat COUCHBASE_CHAT_SCOPE=_default COUCHBASE_CHAT_COLLECTION=_default # Application Configuration PORT=3001
This workspace is designed as a production-ready template that can be easily adapted for new Bun projects. It follows the comprehensive patterns outlined in bun-reviewer.md and serves as an agnostic template for:
To use this workspace structure for a new project:
Copy Configuration Files:
# Essential template files cp package.json bun.config.ts tsconfig.json biome.json new-project/ cp -r scripts/ new-project/scripts/
Update Package Names and Catalog:
// Update root package.json { "name": "your-project-monorepo", "workspaces": { "catalog": { // Add your project-specific dependencies "your-framework": "^1.0.0" } } }
Adapt Package Structure:
# Create your packages following the pattern mkdir -p packages/your-backend packages/your-frontend # Copy and adapt package.json templates from existing packages
Customize Bun Configuration:
// Update bun.config.ts for your specific needs export default { workspace: { packages: { "your-backend": { target: "bun" }, "your-frontend": { target: "browser" } } } }
When adapting this template:
bun run scripts/workspace-validator.ts@ollama-prompting/*scripts/bun run workspace:checkBEFORE modifying any TypeScript configurations, run:
bun run scripts/workspace-validator.ts --detect-frameworks
SvelteKit Projects:
// ❌ NEVER DO THIS - Causes configuration conflicts { "extends": ["../../tsconfig.json", "./.svelte-kit/tsconfig.json"], "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } // CONFLICT! } } // ✅ CORRECT - SvelteKit-first approach { "extends": "./.svelte-kit/tsconfig.json", "compilerOptions": { "composite": true, "declaration": true // NO baseUrl/paths - use svelte.config.js instead } } // ✅ Path aliases in svelte.config.js export default { kit: { alias: { '@': './src', '@/components': './src/components' } } }
React/Next.js Projects:
// ✅ SAFE - Can extend root workspace config { "extends": "../../tsconfig.json", "compilerOptions": { "jsx": "react-jsx", "baseUrl": ".", "paths": { "@/*": ["./src/*"] // Single wildcard OK } } }
Node.js/Express/Elysia Projects:
// ✅ SAFE - Full workspace integration { "extends": "../../tsconfig.json", "compilerOptions": { "types": ["bun-types", "node"], "baseUrl": ".", "paths": { "@/*": ["./src/*"], "@/services/*": ["./src/services/*"] } } }
The template provides these reusable patterns:
1. Dependency Management:
// Centralized version control through catalog "catalog": { "shared-dep": "^1.0.0" } // Package references always stay in sync "dependencies": { "shared-dep": "catalog:" }
2. Cross-Package TypeScript:
// Root tsconfig with workspace references "references": [ { "path": "./packages/package-a" }, { "path": "./packages/package-b" } ]
3. Runtime Detection:
// Universal pattern for Bun/Node compatibility const isBun = () => typeof Bun !== 'undefined';
4. Performance Monitoring:
// Built-in performance measurement const measure = isBun() ? Bun.nanoseconds() : performance.now() * 1_000_000;
5. Environment Validation:
// Automatic environment validation on startup // Configurable per project in scripts/validate-env.ts
For Different Project Types:
Technology Adaptations:
This template is designed to work seamlessly with the
@bun-reviewer# When requesting workspace setup: "Set up a Bun workspace with catalogs following the ollama-prompting template" # Agent will understand: - Catalog-based dependency management - Production-ready bun.config.ts - Comprehensive TypeScript setup - Quality assurance tooling - Performance monitoring patterns
The workspace structure serves as a reference implementation that agents can follow for consistent, production-ready Bun workspace setups.
Error 1: TypeScript Path Pattern Wildcards
# ❌ ERROR MESSAGE: # Invalid pattern "packages/*/src/*", must have at most one "*" character # 🔍 ROOT CAUSE: # Multiple wildcards in TypeScript path patterns are invalid # ✅ PREVENTION: bun run scripts/workspace-validator.ts # Run BEFORE implementation # ✅ FIX: # Replace generic patterns with explicit ones: "@backend/*": ["packages/backend/src/*"] # ✅ Single wildcard "@frontend/*": ["packages/frontend/src/*"] # ✅ Single wildcard
Error 2: SvelteKit Configuration Conflicts
# ❌ ERROR MESSAGE: # "baseUrl and/or paths in your tsconfig.json interferes with SvelteKit" # 🔍 ROOT CAUSE: # SvelteKit auto-generates tsconfig.json and conflicts with custom baseUrl/paths # ✅ PREVENTION: # Detect SvelteKit before applying workspace patterns: bun run scripts/workspace-validator.ts --detect-frameworks # ✅ FIX: # 1. Remove baseUrl/paths from tsconfig.json # 2. Add aliases to svelte.config.js instead: export default { kit: { alias: { '@': './src', '@/components': './src/components' } } }
Error 3: Catalog Reference Loops
# ❌ ERROR: Dependencies not resolving from catalog # 🔍 ROOT CAUSE: # Circular references or missing catalog entries # ✅ PREVENTION: bun install --dry-run # Test before committing bun run workspace:info # Check catalog status # ✅ FIX: # Verify catalog syntax in root package.json: "workspaces": { "catalog": { "typescript": "^5.9.2", // ✅ Valid version "zod": "catalog:" // ❌ Circular reference } }
MANDATORY Steps for ALL Workspace Implementations:
# Run BEFORE making ANY changes bun run scripts/workspace-validator.ts
# Detect frameworks to apply correct patterns grep -r "@sveltejs/kit" packages/*/package.json # SvelteKit grep -r '"react"' packages/*/package.json # React grep -r '"next"' packages/*/package.json # Next.js
# Test configuration works bun run typecheck bun run workspace:check bun run dev:backend & sleep 5 && kill %1 # Quick startup test bun run dev:frontend & sleep 5 && kill %1
# Ensure no errors before completion bun run scripts/workspace-validator.ts echo "✅ Workspace validation passed"
Problem: Dependencies not resolving from catalog
Solution:
# Verify catalog configuration bun run workspace:info # Reinstall with catalog rm -rf node_modules packages/*/node_modules bun.lockb bun install # Check for catalog syntax errors bun run workspace:check
Problem: Cross-package imports not working
Solution:
# Rebuild TypeScript references bun run typecheck --build # Check path mapping in tsconfig.json # Verify package references are correct
Problem:
bun.config.tsSymptoms:
Solution:
# Verify config syntax bun --config ./bun.config.ts --help # Check for TypeScript compilation errors bun run typecheck # Ensure scripts/ directory exists with proper permissions ls -la scripts/
Problem: Linting errors in Svelte or test files
Solution:
# Check Biome configuration overrides cat biome.json | grep -A 10 "overrides" # Run with specific configuration bun run lint --config-path ./biome.json # Fix auto-fixable issues bun run lint:fix
Problem: Development or production monitoring scripts failing
Solution:
# Check Zod validation in validate-env.ts bun run scripts/validate-env.ts # Verify environment variables bun run workspace:check # Test runtime detection node -e "console.log(typeof Bun)" # Should be 'undefined' bun -e "console.log(typeof Bun)" # Should be 'object'
Problem: Frontend shows "Failed to fetch models" with "Available Models: 0"
Root Cause: Frontend cannot reach backend API endpoints
Solution:
Verify Vite Proxy Configuration in
frontend/vite.config.tsserver: { port: 5174, proxy: { '/api': { target: 'http://localhost:3001', changeOrigin: true, secure: false, }, }, }
Use Relative URLs in frontend code:
// ✅ Correct const MODELS_URL = "/api/ollama/models"; // ❌ Incorrect (causes CORS/proxy issues) const MODELS_URL = "http://localhost:3001/api/ollama/models";
Restart Frontend Server after Vite config changes:
bun run devPinecone is the PRIMARY database (per ADR-0003). If Pinecone fails:
Amazon Titan Text Embeddings has an 8,192 token limit. The system automatically handles this by:
If you see "Too many input tokens" errors:
Symptoms: Backend logs show
UnambiguousTimeoutError: unambiguous timeoutImpact: With graceful error handling implemented, this should NOT crash the application.
Expected Behavior:
Error Handling Implementation:
ChatService.saveChatHistory()ChatService.getChatHistory()The project uses Tailwind CSS v4.1+ with modern configuration:
Current Configuration (
postcss.config.jsexport default { plugins: { '@tailwindcss/postcss': {}, autoprefixer: {} } };
CSS Import (
app.css@import 'tailwindcss';
If you encounter PostCSS errors:
@tailwindcss/postcssbun add -D @tailwindcss/postcssThis project is optimized for Bun runtime (per ADR-0002):
bun run src/index.tsbun run devnpm run devbun installProblem: "I couldn't find any relevant information in the documents"
Root Cause: Using wrong RAG service endpoint or document not uploaded to correct service
Solution:
Verify Correct Service Pairing:
/api/rag/upload-pdf/pinecone-document/api/rag/chat/pinecone-documentCheck Session and Filename Matching:
# Ensure sessionId and filename match exactly between upload and chat curl -X POST http://localhost:3001/api/rag/chat/pinecone-document \ -H "Content-Type: application/json" \ -d '{ "message": "Your question here", "sessionId": "exact-session-id-from-upload", "filename": "exact-filename-from-upload.pdf" }'
Problem: "Retrieved 0 chunks with scores: []"
Solutions:
Standard Pinecone RAG (
/api/rag/chat/pineconeSession-Based RAG (
/api/rag/chat/pinecone-documentCouchbase RAG (
/api/rag/chat/couchbase# Test backend directly curl http://localhost:3001/api/ollama/models # Test frontend proxy (should return same result) curl http://localhost:5174/api/ollama/models # Test RAG document upload curl -X POST http://localhost:3001/api/rag/upload-pdf/pinecone-document \ -H "Content-Type: application/json" \ -d '{"file":"base64-encoded-pdf", "filename":"test.pdf"}' # Test RAG chat curl -X POST http://localhost:3001/api/rag/chat/pinecone-document \ -H "Content-Type: application/json" \ -d '{"message":"test question", "sessionId":"session-id", "filename":"test.pdf"}' # Check servers are running lsof -i :3001 # Backend (Native Bun HTTP) lsof -i :5174 # Frontend (Vite dev server) lsof -i :11434 # Ollama (if running locally) # Monitor LangSmith traces # Visit: https://smith.langchain.com/
Based on past issues with traceable wrapper implementations, ALL changes to RAG services must follow these mandatory testing requirements:
1. Syntax Validation (MANDATORY)
# ALWAYS run these checks BEFORE implementing changes cd packages/backend bun run typecheck bun run lint
2. Backup Working State
# Create a branch backup before making changes git checkout -b backup-before-traceable-fixes git add . && git commit -m "Backup working state before traceable changes"
3. Traceable Wrapper Pattern Requirements
traceable});});Example of CORRECT traceable wrapper pattern:
// ✅ CORRECT Pattern const documentProcessingTracer = langsmithService.createDocumentProcessingTracer(); const processingResult = await documentProcessingTracer(async () => { console.log("Starting processing..."); // ALL processing logic goes here with proper indentation const result = await processDocument(); return result; // Return INSIDE wrapper }); // 🔥 CRITICAL: Close the traceable wrapper // Error handling OUTSIDE wrapper } catch (error) { console.error("Error:", error); throw error; }
4. Incremental Testing
# Test syntax after EACH service modification bun run typecheck # If errors found, STOP and fix before continuing
5. Comprehensive Testing (MANDATORY)
# Test all RAG services can start without syntax errors cd packages/backend bun run dev & sleep 5 # If no startup errors, kill the process pkill -f "bun run dev" # Test frontend can connect to backend cd packages/frontend bun run dev & sleep 5 curl http://localhost:5174/api/ollama/models pkill -f "bun run dev"
6. RAG Pipeline Integration Testing
# Test document upload (use provided test PDF) curl -X POST http://localhost:3001/api/rag/upload-pdf/pinecone-document \ -F "file=@Formula One World Drivers' Champions (1950-2024).pdf" \ -H "Accept: application/json" # Test RAG chat with uploaded document curl -X POST http://localhost:3001/api/rag/chat/pinecone-document \ -H "Content-Type: application/json" \ -d '{ "message": "Who won the championship in 1950?", "sessionId": "SESSION_ID_FROM_UPLOAD", "filename": "Formula One World Drivers' Champions (1950-2024).pdf" }'
7. LangSmith Trace Verification
RAG Services with Traceable Wrappers:
packages/backend/src/services/ragService.tspackages/backend/src/services/pineconeService.tspackages/backend/src/services/pineconeDocumentService.tsCommon Error Patterns to Avoid:
await documentProcessingTracer(async () => {});return});If Implementation Breaks the Pipeline:
# Immediately revert to working state git checkout backup-before-traceable-fixes git branch -D failed-traceable-implementation # Restart from working baseline # Re-read this testing guide before attempting fixes again
"Test Early, Test Often, Never Break Production"
This testing protocol exists because traceable wrapper syntax errors can completely break the RAG pipeline, making the application unusable. Following these requirements prevents such critical failures.