AI Document Processing System Expert

Expert guidance for developing and maintaining an AI-powered document processing and chat system with multiple RAG pipelines, vector stores, and LLM providers.

System Overview

This is a monorepo project that enables PDF document upload, processing, and intelligent chat conversations using:

Development Workflow

1. Understand the Workspace Structure

When working with this codebase, first identify the workspace organization:

```

ollama-prompting/

├── package.json # Root workspace with catalog

├── bun.config.ts # Advanced Bun configuration

├── biome.json # Code quality configuration

├── scripts/ # Workspace utilities

└── packages/

├── backend/ # @ollama-prompting/backend

└── frontend/ # @ollama-prompting/frontend

```

**Key concept**: This project uses **Bun workspaces with catalogs** for centralized dependency management. All dependencies are versioned in the root `package.json` catalog.

2. Set Up Development Environment

From the project root:

```bash

Install all dependencies (uses catalog versions)

bun install

Validate environment configuration

bun run validate-env.ts

Start both backend and frontend

bun run dev

Or start individually

bun run dev:backend # Port 3001

bun run dev:frontend # Port 5174

```

3. Understand the RAG Architecture

The system implements **three separate RAG pipelines**:

#### **Pipeline 1: Standard Pinecone RAG**

#### **Pipeline 2: Session-Based Document RAG**

#### **Pipeline 3: Couchbase Vector RAG**

4. Working with Backend Services

Backend services are located in `/packages/backend/src/services/`:

**Core Services:**

**Development commands** (from `/packages/backend`):

```bash

bun run dev # Hot reload development

bun run build # Production build

bun run test # Run tests

bun run typecheck # TypeScript validation

bun run lint # Code quality check

```

5. Working with Frontend Components

Frontend is located in `/packages/frontend/src/`:

**Key Routes:**

**Key Components:**

**Development commands** (from `/packages/frontend`):

```bash

bun run dev # Vite dev server

bun run check # SvelteKit sync + type checking

bun run build # Production build

bun run test # Vitest tests

bun run preview # Preview production build

```

6. Code Quality Standards

This project uses **Biome** for linting and formatting:

```bash

From root

bun run lint # Check all packages

bun run lint:fix # Auto-fix issues

bun run format # Format all code

Workspace-wide checks

bun run workspace:check # Typecheck + lint

bun run typecheck # TypeScript only

```

**Important**: Code must follow Bun runtime patterns with proper runtime detection:

```typescript

// Runtime-aware pattern

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'));

```

7. Testing Strategy

```bash

Root-level tests

bun run test

bun run test:watch

bun run test:coverage

Package-specific tests

bun run test:packages

Frontend tests (Vitest)

cd packages/frontend && bun run test

Backend tests (Bun native)

cd packages/backend && bun run test

```

8. Building for Production

```bash

Build everything

bun run build

Build with watch mode (parallel)

bun run build:watch

Build individual packages

bun run build:backend

bun run build:frontend

```

The `bun.config.ts` provides environment-aware optimization with minification for production and inline source maps for development.

Common Development Tasks

Adding a New Dependency

```bash

Add to catalog (root package.json)

bun add <package> --cwd .

Update catalog reference in workspaces.catalog

Then update package.json in backend/frontend:

{

"dependencies": {

"<package>": "catalog:"

}

}

```

Creating a New API Endpoint

1. Add route handler in `/packages/backend/src/index.ts`

2. Create service in `/packages/backend/src/services/`

3. Add TypeScript types

4. Update API documentation

5. Test with `bun run dev:backend`

Adding a New Frontend Route

1. Create route in `/packages/frontend/src/routes/`

2. Add components in `/packages/frontend/src/components/`

3. Update navigation in `Navigation.svelte`

4. Test with `bun run dev:frontend`

Working with Vector Stores

**Pinecone:**

**Couchbase:**

Debugging LangSmith Traces

1. Ensure `LANGCHAIN_TRACING_V2=true` in environment

2. Set `LANGCHAIN_API_KEY` and `LANGCHAIN_PROJECT`

3. Use `LangSmithTraceViewer.svelte` component in frontend

4. View traces at `/rag-chat` interface

5. Check `langsmithService.ts` for trace creation logic

Important Constraints

1. **Dependency Management**: Always use catalog versions from root `package.json`

2. **Runtime Detection**: Use Bun-aware patterns for compatibility

3. **TypeScript**: Workspace composite projects with path mapping

4. **Code Quality**: All code must pass Biome lint/format checks

5. **Testing**: Maintain 80%+ coverage threshold (configured in `bun.config.ts`)

6. **Security**: Follow validated globals in `biome.json`

7. **Performance**: Use Bun-native APIs when available (file I/O, HTTP, etc.)

Architecture References

Key API Endpoints Reference

Document Upload

Chat

Configuration

Kafka Integration

Maintenance Commands

```bash

Clean all artifacts

bun run clean

bun run clean:packages

Update dependencies

bun run workspace:update

Workspace information

bun run workspace:info

```