typescript-project

# TypeScript Project Architecture

## Core Principles

- **Type safety first** — Strict mode, no `any`, Zod for runtime validation
- **ESM native** — ES Modules by default, Node 22+ / Bun
- **Layered architecture** — Separate lib/services/adapters
- **200-line limit** — No file exceeds 200 lines (see elegant-architecture skill)
- **Test reality** — Vitest/Bun test, minimal mocks
- **No backwards compatibility** — Delete, don't deprecate. Change directly, no shims
- **LiteLLM for LLM APIs** — Use LiteLLM proxy for all LLM integrations, unless specific SDK required

---

## No Backwards Compatibility

> **Delete unused code. Change directly. No compatibility layers.**

### Why

- Dead code is tech debt
- Compatibility shims add complexity
- Old patterns spread through copy-paste
- "Temporary" workarounds become permanent

### Anti-Patterns to Avoid

```typescript
// ❌ BAD: Renaming but keeping old export
export { newName };
export { newName as oldName }; // "for backwards compatibility"

// ❌ BAD: Unused parameter with underscore
function process(_legacyParam: string, data: Data) { ... }

// ❌ BAD: Deprecated comments instead of deletion
/** @deprecated Use newMethod instead */
export function oldMethod() { ... }

// ❌ BAD: Re-exporting removed functionality
export { removed } from './legacy'; // Keep for existing consumers

// ❌ BAD: Feature flags for old behavior
if (config.useLegacyMode) { ... }
```

### Correct Approach

```typescript
// ✅ GOOD: Just delete and update all usages
// Old: export { fetchData as getData }
// New: export { fetchData }
// Then: Find & replace all getData → fetchData

// ✅ GOOD: Remove unused parameters entirely
function process(data: Data) { ... }

// ✅ GOOD: Delete deprecated code, update callers
// Don't mark as deprecated, just remove it

// ✅ GOOD: Breaking changes are fine in active development
// Semantic versioning handles this for libraries
```

### When Changing Interfaces

```typescript
// ❌ BAD: Adding optional fields "for compatibility"
interface User {
  id: string;
  name: string;
  firstName?: string; // New field, name kept for compatibility
  lastName?: string;
}

// ✅ GOOD: Clean break, update all usages
interface User {
  id: string;
  firstName: string;
  lastName: string;
}
// Then update ALL code that uses User.name
```

### Migration Strategy

1. **Find all usages** — `grep -r "oldName" src/`
2. **Update all at once** — Single commit, no transition period
3. **Delete old code** — No deprecation warnings, just remove
4. **Run tests** — Ensure nothing breaks

---

## LiteLLM for LLM APIs

> **Use LiteLLM proxy for all LLM integrations. Don't call provider APIs directly.**

### Why LiteLLM

- **Unified interface** — One API for 100+ LLM providers (OpenAI, Anthropic, Azure, Bedrock, etc.)
- **Provider agnostic** — Switch models without code changes
- **Cost tracking** — Built-in usage and cost monitoring
- **Load balancing** — Automatic failover between providers
- **Rate limiting** — Protect against quota exhaustion

### Setup

```bash
# Run LiteLLM proxy (Docker)
docker run -p 4000:4000 ghcr.io/berriai/litellm:main-stable

# Or install locally
pip install litellm[proxy]
litellm --model gpt-4o
```

### TypeScript Usage

```typescript
// adapters/llm.adapter.ts
import { OpenAI } from 'openai';

// Connect to LiteLLM proxy using OpenAI SDK
const llm = new OpenAI({
  baseURL: process.env.LITELLM_URL || 'http://localhost:4000',
  apiKey: process.env.LITELLM_API_KEY || 'sk-1234', // Proxy API key
});

export async function complete(prompt: string, model = 'gpt-4o'): Promise<string> {
  const response = await llm.chat.completions.create({
    model, // Can be any model: gpt-4o, claude-3-opus, gemini-pro, etc.
    messages: [{ role: 'user', content: prompt }],
  });
  return response.choices[0]?.message?.content ?? '';
}
```

### When NOT to Use LiteLLM

- Streaming with provider-specific features (e.g., Anthropic's tool use streaming)
- Provider-specific APIs not in OpenAI format (embeddings with metadata, etc.)
- Direct SDK required for compliance/security reasons

### Anti-Patterns

```typescript
// ❌ BAD: Direct provider SDKs everywhere
import Anthropic from '@anthropic-ai/sdk';
import OpenAI from 'openai';
import { GoogleGenerativeAI } from '@google/generative-ai';

// ❌ BAD: Provider-specific code scattered across codebase
if (provider === 'anthropic') { ... }
else if (provider === 'openai') { ... }

// ✅ GOOD: Single LiteLLM adapter, switch models via config
const response = await llm.chat.completions.create({
  model: config.llmModel, // "gpt-4o" or "claude-3-opus" or "gemini-pro"
  messages,
});
```

---

## Quick Start

### 1. Initialize Project

```bash
# Using Bun (recommended)
bun init
bun add zod
bun add -d typescript @types/bun @biomejs/biome

# Using Node.js
npm init -y
npm i zod
npm i -D typescript @types/node tsx @biomejs/biome
```

### 2. Apply Tech Stack

| Layer | Recommendation |
|-------|----------------|
| Runtime | Bun / Node 22+ |
| Language | TypeScript (latest) |
| Validation | Zod (latest) |
| Testing | Bun test / Vitest |
| Build | bun build / tsup |
| Linting | Biome (latest) |

### Version Strategy

> **Always use latest. Never pin versions in templates.**

```json
{
  "dependencies": {
    "zod": "latest"
  },
  "devDependencies": {
    "@biomejs/biome": "latest",
    "typescript": "latest"
  }
}
```

- `bun add` / `npm i` automatically fetches latest
- Use `bun update --latest` to upgrade all dependencies
- Lock files (`bun.lockb`, `package-lock.json`) ensure reproducible builds
- Breaking changes are handled by reading changelogs, not by avoiding updates

### 3. Use Standard Structure

```
project/
├── src/
│   ├── index.ts           # Entry point
│   ├── lib/               # Core utilities
│   │   ├── config.ts      # Configuration management
│   │   ├── errors.ts      # Custom error classes
│   │   ├── logger.ts      # Logging infrastructure
│   │   └── types.ts       # Shared type definitions
│   ├── service