Legacy Documentation: These docs are from the original standalone Lilith project before it was absorbed into the Oshun monorepo. References to
npm, standalonedocker-compose, and thedevelopbranch 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#
# 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#
# 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:
// 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:
# 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
anytypes in production code - ESLint: Zero errors/warnings policy
- Prettier: Consistent code formatting
- Pre-commit hooks: Automated linting and formatting
# 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:
# 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:
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#
# Start all infrastructure
docker compose up -d
# Start services individually
cd services/auth && npm start
Kubernetes#
# 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:
cd deploy/terraform
terraform init
terraform plan
terraform apply
Documentation#
- Architecture - System design and architecture decisions
- Product Specification - Product requirements and features
- Coding Standards - Code style guide
- Testing Standards - Testing patterns
- API Reference - OpenAPI specification
- Contributing - 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 for details.