# Lilith Platform

> **Legacy Documentation:** These docs are from the original standalone Lilith
> project before it was absorbed into the Oshun monorepo. References to `npm`,
> standalone `docker-compose`, and the `develop` branch reflect the old project
> setup. For current development instructions, see the
> [Oshun Getting Started guide](../getting-started.md) and the
> [Lilith domain overview](domains/lilith/README.md).

A comprehensive metaverse and AI learning platform combining meditation, yoga,
spiritual guidance, AI mentors, NFT marketplace, and an immersive encyclopedia
covering spirituality, philosophy, science, mysticism, and consciousness
exploration.

## Quick Start

### Prerequisites

- Node.js 20+
- npm 10+
- Docker & Docker Compose (for infrastructure services)

### Development Setup

```bash
# Clone the repository
git clone <repository-url>
cd lilith

# Install dependencies
npm install

# Start infrastructure services (PostgreSQL, Redis, etc.)
docker compose up -d

# Start a specific service
cd services/<service-name>
npm start

# Or run all services with the local development environment
npm run dev
```

### Running Tests

```bash
# Run E2E tests
npm test

# Run unit tests for a specific service
cd services/auth && npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint
```

## Project Structure

```
lilith/
├── packages/           # Shared packages
│   ├── core/          # Core types, utilities, constants
│   ├── errors/        # Error handling utilities
│   ├── fastify-core/  # Fastify service utilities
│   ├── testing/       # Test utilities, mocks, fixtures
│   └── ...
├── services/          # Microservices (81 services)
│   ├── auth/          # Authentication & authorization
│   ├── bff/           # Backend-for-Frontend
│   ├── content/       # Content management
│   ├── conversation/  # Chat & messaging
│   ├── media/         # Media processing
│   ├── ai/            # AI orchestration
│   ├── notification/  # Notifications
│   ├── moderation/    # Content moderation
│   └── ...
├── sdk/               # Client SDKs
│   └── typescript/    # TypeScript SDK
├── apps/              # Applications
│   ├── web/           # Next.js web app
│   └── mobile/        # React Native mobile app
├── deploy/            # Deployment configurations
│   ├── helm/          # Kubernetes Helm charts
│   ├── terraform/     # Infrastructure as Code
│   └── argocd/        # GitOps configurations
├── tests/             # E2E and integration tests
├── docs/              # Documentation
└── openapi/           # OpenAPI specifications
```

## Core Services

| Service      | Port | Description                             |
| ------------ | ---- | --------------------------------------- |
| auth         | 3003 | JWT authentication, OAuth2, MFA, RBAC   |
| bff          | 3000 | Backend-for-Frontend aggregator         |
| content      | 3004 | Content management, courses, versioning |
| conversation | 3005 | Chat threads, SSE streaming             |
| media        | 3006 | Media metadata, TTS/STT, signed URLs    |
| ai           | 3007 | LLM orchestration, RAG pipeline         |
| notification | 3008 | Push notifications, email dispatch      |
| moderation   | 3009 | Content filtering, safety checks        |

## Development

### Service Development

Each service follows a standard structure:

```
services/<service>/
├── src/
│   ├── app.ts          # Fastify app setup
│   ├── server.ts       # Server entry point
│   ├── types.ts        # TypeScript types
│   ├── routes/         # API routes
│   └── __tests__/      # Unit tests
├── package.json
├── tsconfig.json
└── vitest.config.ts
```

### Shared Packages

Import shared utilities from workspace packages:

```typescript
// Core types and utilities
import { generateId, HTTP_STATUS } from '@lilith/core';

// Error handling
import { AppError, ValidationError } from '@lilith/errors';

// Logging
import { LilithLogger } from '@lilith/lib';

// Testing utilities
import {
  createMockLogger,
  createUser,
  assertApiSuccess,
} from '@lilith/testing';

// Fastify utilities
import {
  createServiceServer,
  registerHealthRoutes,
} from '@lilith/fastify-core';
```

### Environment Variables

Each service supports configuration via environment variables:

```bash
# Common variables
PORT=3000
NODE_ENV=development
SERVICE_VERSION=1.0.0

# Database
DATABASE_URL=postgres://localhost:5432/lilith

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-secret-key
JWT_ACCESS_TOKEN_EXPIRY=15m
JWT_REFRESH_TOKEN_EXPIRY=7d
```

See `.env.example` in each service for service-specific variables.

### Code Quality

The project enforces strict code quality standards:

- **TypeScript**: Strict mode, no `any` types in production code
- **ESLint**: Zero errors/warnings policy
- **Prettier**: Consistent code formatting
- **Pre-commit hooks**: Automated linting and formatting

```bash
# Check formatting
npm run format:check

# Fix formatting
npm run format

# Run lint
npm run lint

# Fix lint issues
npm run lint:fix

# Type check
npm run typecheck
```

### Testing

The project uses Vitest for unit tests and Playwright for E2E tests:

```bash
# Unit tests with coverage
cd services/<service>
npm run test:coverage

# E2E tests
npm test

# Integration tests
npm run test:integration
```

Test utilities from `@lilith/testing`:

```typescript
import {
  // Mocks
  createMockLogger,
  createMockHttpClient,
  createMockRedisClient,

  // Fixtures
  createUser,
  createApiResponse,
  createPaginatedResponse,

  // Assertions
  assertDefined,
  assertApiSuccess,
  assertAppError,
  waitFor,

  // Containers (for integration tests)
  PostgresContainer,
  RedisContainer,
} from '@lilith/testing';
```

## Deployment

### Local Development

```bash
# Start all infrastructure
docker compose up -d

# Start services individually
cd services/auth && npm start
```

### Kubernetes

```bash
# Deploy with Helm
helm install lilith deploy/helm/lilith-platform -f values.yaml

# Or use ArgoCD for GitOps
kubectl apply -f deploy/argocd/app-of-apps.yaml
```

### Infrastructure

Infrastructure is managed with Terraform:

```bash
cd deploy/terraform
terraform init
terraform plan
terraform apply
```

## Documentation

- [Architecture](./ARCHITECTURE.md) - System design and architecture decisions
- [Product Specification](./PRODUCT.md) - Product requirements and features
- [Coding Standards](./docs/standards/CODING_STANDARDS.md) - Code style guide
- [Testing Standards](./docs/testing/testing-standards.md) - Testing patterns
- [API Reference](./openapi/openapi.yaml) - OpenAPI specification
- [Contributing](./CONTRIBUTING.md) - Contribution guidelines

## Technology Stack

- **Runtime**: Node.js 20 with ESM modules
- **Language**: TypeScript (strict mode)
- **Framework**: Fastify
- **Testing**: Vitest, Playwright
- **Database**: PostgreSQL
- **Cache**: Redis
- **Search**: Elasticsearch, Milvus (vector)
- **Infrastructure**: Kubernetes, Helm, Terraform
- **CI/CD**: GitHub Actions, ArgoCD

## License

MIT License - see [LICENSE](./LICENSE) for details.
