This folder contains the essential documentation for understanding, developing, and operating the Lilith platform - a comprehensive Metaverse & AI Learning Platform.
How to Use This Folder#
This documentation is organized to support different audiences and use cases. Start with the reading order that matches your role:
For New Team Members (Onboarding)#
- overview.md - Understand the business context and high-level technical vision
- features.md - Learn what the platform does and its major capabilities
- architecture.md - Understand system design, components, and data flow
- glossary.md - Reference for domain terms and abbreviations
For Developers#
- architecture.md - System design and service boundaries
- data-model.md - Key entities and relationships
- api/ - API documentation (HTTP, CLI)
- specs/ - Feature specifications
- algorithms.md - Non-trivial algorithms and their rationale
- decisions/ - Architecture Decision Records
For Product Managers & Designers#
- overview.md - Business context and product vision
- features.md - Feature catalog and capabilities
- user-stories/ - User stories organized by epic
- specs/ - Detailed feature specifications
For Operations & SRE#
- operations.md - How to run, monitor, and debug in production
- architecture.md - Infrastructure and deployment architecture
- decisions/ - Key architectural decisions and their rationale
Document Index#
| Document | Description | Primary Audience |
|---|---|---|
| overview.md | Business context, product vision, high-level technical overview | Everyone |
| architecture.md | System design, service boundaries, infrastructure, data flow | Engineers, SRE |
| data-model.md | Database entities, relationships, schemas | Backend Engineers |
| features.md | Major features and capabilities | Product, Engineers |
| algorithms.md | Non-trivial algorithms with rationale | Engineers |
| operations.md | Running, monitoring, debugging production systems | SRE, DevOps |
| glossary.md | Domain terms and abbreviations | Everyone |
Subdirectories#
| Directory | Description | Contents |
|---|---|---|
| specs/ | Feature specifications | Detailed feature specs organized by domain |
| api/ | API documentation | HTTP API reference, CLI documentation |
| user-stories/ | User stories by epic | Epic-organized user stories and journeys |
| decisions/ | Architecture Decision Records | ADRs documenting key technical decisions |
Quick Reference Links#
External Resources#
- OpenAPI Specification:
../openapi/openapi.yaml - Architecture Overview:
../ARCHITECTURE.md - Product Specification:
../PRODUCT.md - Local Development Guide:
../docs/LOCAL_DEVELOPMENT_GUIDE.md - Runbooks:
../docs/runbooks/
Service Documentation#
Each service has its own README in ../services/<service-name>/:
- Auth Service:
../services/auth/ - BFF Service:
../services/bff/ - Content Service:
../services/content/ - Conversation Service:
../services/conversation/ - AI Service:
../services/ai/ - Media Service:
../services/media/ - And 60+ more services...
Keeping Documentation Updated#
When to Update#
- New Feature: Add to
features.md, create spec inspecs/, update relevant user stories - Architecture Change: Update
architecture.md, create ADR indecisions/ - New Entity: Update
data-model.md - New Algorithm: Document in
algorithms.md - New Term: Add to
glossary.md - Operational Change: Update
operations.md
Documentation Standards#
- Keep it Current: Documentation should reflect the actual system
- Be Specific: Include concrete examples, not just abstractions
- Link Liberally: Cross-reference related documentation
- Version References: Note when features/APIs are version-specific
- Include Diagrams: Visual representations aid understanding
Contact#
For documentation questions or updates, contact the Engineering team or submit a PR with improvements.
Last Updated: December 2025