# Packages Documentation

> Shared workspace packages and their APIs

## 📋 Overview

Izri uses a monorepo structure with shared packages that provide common functionality across the frontend and backend. This section documents each package, its purpose, and how to use it.

## 📦 Package List

### Core Packages

- **[@izri/database](./database-package.md)** - Drizzle ORM, schema, and migrations
- **[@izri/trpc](./trpc-package.md)** - tRPC router definitions and context
- **[@izri/shared](./shared-package.md)** - Shared utilities and types
- **[@izri/auth](./auth-package.md)** - Authentication utilities (Better Auth)

### Service Packages

- **[AI Service](./ai-service.md)** - Python FastAPI service for AI operations
- **[Repo Analyzer](./repo-analyzer.md)** - Repository analysis tools



## 🔧 Using Packages

### Import from Packages

```typescript
// Database
import { db, users, projects } from '@izri/database'
import { eq } from 'drizzle-orm'

// tRPC
import { appRouter } from '@izri/trpc'
import type { AppRouter } from '@izri/trpc'

// Shared
import { formatDate, logger } from '@izri/shared'

// Types
import type { Project, User } from '@izri/database'
```

### Adding Dependencies to Packages

```bash
# Add to specific package
pnpm --filter @izri/database add drizzle-orm

# Add dev dependency
pnpm --filter @izri/shared add -D @types/node
```

## 📚 Package Documentation

### [@izri/database](./database-package.md)

**Database access layer with Drizzle ORM**

- Schema definitions
- Database client
- Migration workflow
- Seed scripts
- Query patterns

### [@izri/trpc](./trpc-package.md)

**tRPC server implementation**

- Router structure
- Procedure definitions
- Context setup
- Type exports

### [@izri/shared](./shared-package.md)

**Common utilities and types**

- Utility functions
- Shared types
- Constants
- Helpers

### [@izri/auth](./auth-package.md)

**Authentication utilities**

- Better Auth setup
- Session management
- Auth helpers
- Token utilities

### [AI Service](./ai-service.md)

**Python FastAPI service**

- FastAPI setup
- AI model integration
- Analysis endpoints
- Test generation

### [Repo Analyzer](./repo-analyzer.md)

**Repository analysis tools**

- Code analysis
- Dependency detection
- Framework detection
- File structure parsing

## 🔄 Package Dependencies

```mermaid
graph TD
    A[@izri/shared] --> B[@izri/database]
    A --> C[@izri/trpc]
    A --> D[@izri/auth]
    B --> C
    B --> D
    C --> E[@izri/api]
    C --> F[@izri/web]
    D --> E
    A --> E
    A --> F
```

## 🚀 Development Workflow

### Building Packages

```bash
# Build all packages
pnpm build:packages

# Build specific package
pnpm --filter @izri/database build

# Watch mode (during development)
pnpm --filter @izri/shared dev
```

### Type Checking

```bash
# Check all packages
pnpm type:check:packages

# Check specific package
pnpm --filter @izri/trpc type:check
```

### Testing

```bash
# Test all packages
pnpm test

# Test specific package
pnpm --filter @izri/database test
```

## 📦 Creating a New Package

```bash
# 1. Create package directory
mkdir packages/my-package

# 2. Initialize package
cd packages/my-package
pnpm init

# 3. Configure package.json
{
  "name": "@izri/my-package",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "clean": "rm -rf lib"
  }
}

# 4. Create tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "./src"
  },
  "include": ["src"]
}

# 5. Create src/ directory
mkdir src
echo "export const hello = 'world'" > src/index.ts

# 6. Build
pnpm build

# 7. Use in other packages
# Add to package.json dependencies:
# "@izri/my-package": "workspace:*"
```

## 🎯 Best Practices

### Package Structure

- **src/**: Source TypeScript files
- **lib/** or **dist/**: Compiled JavaScript (gitignored)
- **types/**: Additional type definitions
- **tests/**: Unit tests
- **package.json**: Package configuration
- **tsconfig.json**: TypeScript configuration
- **README.md**: Package documentation

### Naming Conventions

- Package names: `@izri/package-name`
- Use kebab-case for package names
- Use descriptive, specific names
- Avoid generic names like "utils" or "helpers" alone

### Exports

```typescript
// src/index.ts - Single export point
export * from './utils'
export * from './types'
export * from './constants'
export { default as something } from './something'
```

### Versioning

- All packages use `workspace:*` for internal dependencies
- External dependencies use specific version ranges
- Keep dependencies up to date
- Document breaking changes

## 🔗 Related Documentation

- **Architecture**: [Monorepo Structure](../architecture/monorepo-structure.md)
- **Development**: [Development Guide](../development/README.md)
- **Backend**: [Backend Documentation](../backend/README.md)

---

*Explore individual packages →*

- [Database Package](./database-package.md)
- [tRPC Package](./trpc-package.md)
- [Shared Package](./shared-package.md)
- [Auth Package](./auth-package.md)
- [AI Service](./ai-service.md)
- [Repo Analyzer](./repo-analyzer.md)