# Lilith Key Documentation

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)

1. **[overview.md](./overview.md)** - Understand the business context and
   high-level technical vision
2. **[features.md](./features.md)** - Learn what the platform does and its major
   capabilities
3. **[architecture.md](./architecture.md)** - Understand system design,
   components, and data flow
4. **[glossary.md](./glossary.md)** - Reference for domain terms and
   abbreviations

### For Developers

1. **[architecture.md](./architecture.md)** - System design and service
   boundaries
2. **[data-model.md](./data-model.md)** - Key entities and relationships
3. **[api/](./api/)** - API documentation (HTTP, CLI)
4. **[specs/](./specs/)** - Feature specifications
5. **[algorithms.md](./algorithms.md)** - Non-trivial algorithms and their
   rationale
6. **[decisions/](./decisions/)** - Architecture Decision Records

### For Product Managers & Designers

1. **[overview.md](./overview.md)** - Business context and product vision
2. **[features.md](./features.md)** - Feature catalog and capabilities
3. **[user-stories/](./user-stories/)** - User stories organized by epic
4. **[specs/](./specs/)** - Detailed feature specifications

### For Operations & SRE

1. **[operations.md](./operations.md)** - How to run, monitor, and debug in
   production
2. **[architecture.md](./architecture.md)** - Infrastructure and deployment
   architecture
3. **[decisions/](./decisions/)** - Key architectural decisions and their
   rationale

## Document Index

| Document                             | Description                                                     | Primary Audience   |
| ------------------------------------ | --------------------------------------------------------------- | ------------------ |
| [overview.md](./overview.md)         | Business context, product vision, high-level technical overview | Everyone           |
| [architecture.md](./architecture.md) | System design, service boundaries, infrastructure, data flow    | Engineers, SRE     |
| [data-model.md](./data-model.md)     | Database entities, relationships, schemas                       | Backend Engineers  |
| [features.md](./features.md)         | Major features and capabilities                                 | Product, Engineers |
| [algorithms.md](./algorithms.md)     | Non-trivial algorithms with rationale                           | Engineers          |
| [operations.md](./operations.md)     | Running, monitoring, debugging production systems               | SRE, DevOps        |
| [glossary.md](./glossary.md)         | Domain terms and abbreviations                                  | Everyone           |

### Subdirectories

| Directory                        | Description                   | Contents                                   |
| -------------------------------- | ----------------------------- | ------------------------------------------ |
| [specs/](./specs/)               | Feature specifications        | Detailed feature specs organized by domain |
| [api/](./api/)                   | API documentation             | HTTP API reference, CLI documentation      |
| [user-stories/](./user-stories/) | User stories by epic          | Epic-organized user stories and journeys   |
| [decisions/](./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 in `specs/`, update
  relevant user stories
- **Architecture Change**: Update `architecture.md`, create ADR in `decisions/`
- **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

1. **Keep it Current**: Documentation should reflect the actual system
2. **Be Specific**: Include concrete examples, not just abstractions
3. **Link Liberally**: Cross-reference related documentation
4. **Version References**: Note when features/APIs are version-specific
5. **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_
