Eve library

Lilith Platform

Guide

Revision 1

On this page

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 and the Lilith domain overview.

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#

text
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:

text
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#

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 for details.