# Lilith Monorepo Structure

This document describes the monorepo structure and how to work with the shared
packages.

## Directory Structure

```
lilith/
├── packages/           # Shared packages (npm workspaces)
│   ├── core/           # @lilith/core - Types, utilities, constants
│   ├── logger/         # @lilith/logger - Structured logging
│   ├── config/         # @lilith/config - Configuration management
│   ├── errors/         # @lilith/errors - Error types and handling
│   ├── testing/        # @lilith/testing - Test utilities
│   ├── database/       # @lilith/database - PostgreSQL utilities
│   ├── cache/          # @lilith/cache - Redis caching utilities
│   ├── queue/          # @lilith/queue - Job queue utilities
│   ├── metrics/        # @lilith/metrics - Prometheus metrics
│   ├── tracing/        # @lilith/tracing - Distributed tracing
│   ├── eslint-config-lilith/  # Shared ESLint configuration
│   ├── tsconfig-lilith/       # Shared TypeScript configuration
│   └── prettier-config-lilith/ # Shared Prettier configuration
├── services/           # Microservices
│   ├── auth/           # Authentication service
│   ├── bff/            # Backend for Frontend
│   ├── content/        # Content management
│   ├── ai/             # AI orchestration
│   └── ...
├── sdk/                # Client SDKs
│   └── typescript/     # TypeScript SDK
├── web/                # Web application (Next.js)
├── mobile/             # Mobile application (React Native)
└── deploy/             # Deployment configurations
```

## Shared Packages

### Core Packages

| Package           | Description                                |
| ----------------- | ------------------------------------------ |
| `@lilith/core`    | Shared types, utilities, and constants     |
| `@lilith/logger`  | Structured logging with JSON/pretty output |
| `@lilith/config`  | Environment variable management            |
| `@lilith/errors`  | Standardized error classes                 |
| `@lilith/testing` | Test mocks, fixtures, and helpers          |

### Infrastructure Packages

| Package            | Description                              |
| ------------------ | ---------------------------------------- |
| `@lilith/database` | PostgreSQL connection pool and utilities |
| `@lilith/cache`    | Redis client and caching utilities       |
| `@lilith/queue`    | Job queue implementation                 |
| `@lilith/metrics`  | Prometheus-compatible metrics            |
| `@lilith/tracing`  | OpenTelemetry-compatible tracing         |

### Configuration Packages

| Package                   | Description                     |
| ------------------------- | ------------------------------- |
| `@lilith/eslint-config`   | Shared ESLint rules             |
| `@lilith/tsconfig`        | Shared TypeScript configuration |
| `@lilith/prettier-config` | Shared Prettier configuration   |

## Usage

### Installing Dependencies

```bash
# Install all dependencies
npm install

# Install with legacy peer deps (if needed)
npm install --legacy-peer-deps
```

### Building Packages

```bash
# Build all packages with project references
npm run build:packages

# Build with watch mode
npm run build:packages:watch

# Clean build artifacts
npm run clean:packages
```

### Running Tests

```bash
# Run unit tests
npm run test:unit

# Run with watch mode
npm run test:unit:watch

# Run with coverage
npm run test:unit:coverage

# Run E2E tests
npm test
```

### Using Shared Packages in Services

```typescript
// Import from @lilith packages
import { createLogger } from '@lilith/logger';
import { defineConfig, databaseSchema } from '@lilith/config';
import { AppError, NotFoundError } from '@lilith/errors';
import type { User, ApiResponse } from '@lilith/core';

// Create a logger
const logger = createLogger({ service: 'my-service' });

// Load configuration
const config = defineConfig({
  database: databaseSchema,
});

// Use error classes
throw new NotFoundError('User not found', { userId: '123' });
```

### ESLint Configuration

In your service's `.eslintrc.json`:

```json
{
  "extends": ["@lilith/eslint-config/typescript"]
}
```

Or for Node.js services:

```json
{
  "extends": ["@lilith/eslint-config/node"]
}
```

### TypeScript Configuration

In your service's `tsconfig.json`:

```json
{
  "extends": "@lilith/tsconfig/node",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"]
}
```

### Prettier Configuration

In your service's `package.json`:

```json
{
  "prettier": "@lilith/prettier-config"
}
```

## Development Workflow

1. **Create a new package**

   ```bash
   mkdir -p packages/my-package/src
   cd packages/my-package
   npm init
   ```

2. **Add package to workspaces** (automatic with `packages/*` glob)

3. **Configure TypeScript**

   ```json
   {
     "extends": "@lilith/tsconfig/library",
     "compilerOptions": {
       "outDir": "./dist",
       "rootDir": "./src"
     }
   }
   ```

4. **Add to project references** Update `tsconfig.build.json` to include the new
   package.

5. **Install and link**
   ```bash
   npm install
   ```

## Package Dependencies

The packages have the following dependency graph:

```
@lilith/core (no deps)
    ↓
@lilith/config (→ core)
@lilith/errors (→ core)
@lilith/logger (→ core)
    ↓
@lilith/testing (→ core, errors)
@lilith/database (→ core, config, errors, logger)
@lilith/cache (→ core, config, errors, logger)
@lilith/queue (→ core, errors, logger)
@lilith/metrics (→ core)
@lilith/tracing (→ core)
```

## Scripts Reference

| Script                         | Description                  |
| ------------------------------ | ---------------------------- |
| `npm run build:packages`       | Build all packages           |
| `npm run build:packages:watch` | Build packages in watch mode |
| `npm run clean:packages`       | Clean build artifacts        |
| `npm run test:unit`            | Run unit tests               |
| `npm run test:unit:watch`      | Run tests in watch mode      |
| `npm run test:unit:coverage`   | Run tests with coverage      |
| `npm run lint:ts`              | Lint TypeScript files        |
| `npm run typecheck`            | Type check all files         |
