# Lilith Wisdom Platform API Documentation

This directory contains the Stoplight configuration and documentation for the
Lilith Wisdom Platform API. It provides comprehensive API documentation with
interactive examples, SDK integration guides, and automated validation.

## 🚀 Quick Start

### Prerequisites

- Node.js 16+ and npm 8+
- Access to the Lilith API documentation

### Installation

```bash
# Install dependencies
npm install

# Start local development server
npm run dev

# Build static documentation
npm run build
```

### Development

```bash
# Start development server with hot reload
npm run dev

# Lint OpenAPI specification
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Validate API documentation
npm run validate
```

## 📁 Project Structure

```
docs/stoplight/
├── .spectral.yaml          # Spectral linting configuration
├── stoplight.yaml          # Stoplight portal configuration
├── package.json            # NPM package configuration
├── README.md               # This file
├── openapi.yaml            # OpenAPI specification (symlink)
├── dist/                   # Built documentation output
├── pages/                  # Custom documentation pages
│   ├── getting-started.md
│   ├── authentication.md
│   └── guides/
├── examples/               # Code examples and tutorials
│   ├── typescript/
│   ├── swift/
│   └── kotlin/
├── assets/                 # Static assets (images, logos)
└── styles/                 # Custom CSS styles
    └── custom.css
```

## 🛠️ Available Scripts

| Script                  | Description                                 |
| ----------------------- | ------------------------------------------- |
| `npm run dev`           | Start local development server on port 3100 |
| `npm run build`         | Build static documentation for deployment   |
| `npm run lint`          | Lint OpenAPI specification with Spectral    |
| `npm run lint:fix`      | Automatically fix linting issues            |
| `npm run validate`      | Validate OpenAPI spec against custom rules  |
| `npm run test`          | Run linting and validation                  |
| `npm run preview`       | Preview documentation locally               |
| `npm run docs:generate` | Generate documentation from OpenAPI         |
| `npm run docs:serve`    | Serve documentation on port 3100            |
| `npm run clean`         | Clean build artifacts and dependencies      |

## 🔧 Configuration

### Spectral Configuration (.spectral.yaml)

The `.spectral.yaml` file configures Spectral linting rules for OpenAPI
validation:

- **OpenAPI Specification Rules**: Ensures valid OpenAPI 3.1.0 syntax
- **Custom API Design Rules**: Enforces consistent API design patterns
- **Security Rules**: Validates authentication and authorization
- **Documentation Quality Rules**: Ensures comprehensive documentation

### Stoplight Configuration (stoplight.yaml)

The `stoplight.yaml` file configures the API documentation portal:

- **Theme and Branding**: Custom colors, logos, and typography
- **Navigation**: Structured navigation with guides and references
- **SDK Documentation**: Auto-generated SDK integration examples
- **Security Documentation**: Authentication, rate limiting, and compliance
- **Deployment Configuration**: Production deployment settings

## 📚 Documentation Features

### Interactive API Reference

- **Auto-generated** from OpenAPI specification
- **Try-it-out** functionality for all endpoints
- **Authentication** examples with JWT tokens
- **Request/response** examples
- **Error handling** documentation

### SDK Integration Guides

Comprehensive guides for all official SDKs:

- **TypeScript/JavaScript**: Web and Node.js applications
- **Swift**: iOS and macOS applications
- **Kotlin**: Android applications

Each guide includes:

- Installation instructions
- Authentication setup
- Code examples
- Best practices
- Error handling

### User Guides

Step-by-step guides for common workflows:

- **Getting Started**: Quick start guide
- **Authentication**: Complete authentication flow
- **Chat Integration**: Building chat features
- **Audio Streaming**: Media content delivery
- **Push Notifications**: Real-time notifications

### Security Documentation

- **Authentication**: JWT token management
- **Rate Limiting**: API usage limits
- **Data Protection**: Encryption and compliance
- **Best Practices**: Security recommendations

## 🚀 Deployment

### Local Development

```bash
# Start development server
npm run dev

# Open in browser
open http://localhost:3100
```

### Staging Deployment

```bash
# Build and deploy to staging
npm run deploy:staging
```

### Production Deployment

```bash
# Build and deploy to production
npm run deploy:production
```

### CI/CD Integration

The documentation is automatically built and deployed via GitHub Actions:

- **On Push**: Build and validate documentation
- **On Pull Request**: Build staging version
- **On Main**: Deploy to production

## 🔍 Validation and Quality

### Automated Checks

- **OpenAPI Validation**: Ensures valid API specification
- **Documentation Quality**: Validates descriptions and examples
- **Link Validation**: Checks all internal and external links
- **Code Examples**: Validates all code snippets

### Quality Gates

The documentation must pass all quality gates before deployment:

1. ✅ **Spectral Linting**: No linting errors
2. ✅ **OpenAPI Validation**: Valid specification
3. ✅ **Content Validation**: All descriptions present
4. ✅ **Example Testing**: All code examples work
5. ✅ **Link Checking**: No broken links

## 🎨 Customization

### Theme Customization

Edit `stoplight.yaml` to customize:

- **Colors**: Primary, secondary, accent colors
- **Typography**: Font families and sizes
- **Logo**: Custom logo and favicon
- **Layout**: Navigation and page structure

### Custom Pages

Add custom markdown pages in the `pages/` directory:

1. Create `.md` file with frontmatter
2. Add to navigation in `stoplight.yaml`
3. Include in build process

### Custom Styles

Add custom CSS in `styles/custom.css`:

```css
/* Custom styles for Lilith branding */
.api-docs {
  --primary-color: #6366f1;
  --secondary-color: #8b5cf6;
  --accent-color: #ec4899;
}
```

## 📊 Monitoring and Analytics

### Performance Monitoring

- **Page Load Times**: Core Web Vitals tracking
- **API Response Times**: Documentation API performance
- **User Analytics**: Google Analytics integration
- **Error Tracking**: Sentry error monitoring

### Usage Analytics

- **Page Views**: Most popular documentation pages
- **Search Queries**: Common user searches
- **SDK Downloads**: Package download statistics
- **API Usage**: Endpoint usage patterns

## 🤝 Contributing

### Adding New API Documentation

1. **Update OpenAPI spec** in `../../openapi/openapi.yaml`
2. **Add examples** in appropriate SDK directories
3. **Update guides** if new features are added
4. **Run validation** with `npm run test`
5. **Submit pull request**

### Documentation Style Guide

- **Clear descriptions**: Use simple, clear language
- **Code examples**: Provide working examples for all SDKs
- **Error handling**: Document common errors and solutions
- **Version compatibility**: Note version requirements

### Review Process

All documentation changes require:

1. **Automated validation**: Pass all quality gates
2. **Manual review**: Technical accuracy review
3. **User testing**: Validate user experience
4. **Approval**: Documentation team approval

## 🆘 Support

### Getting Help

- **Documentation**: https://docs.lilith.ai
- **API Support**: api-support@lilith.ai
- **GitHub Issues**: https://github.com/lilith-ai/lilith-platform/issues
- **Community**: https://community.lilith.ai

### Common Issues

**Build Errors:**

- Check Node.js version (16+ required)
- Run `npm install` to update dependencies
- Clear cache with `npm run clean`

**Linting Errors:**

- Run `npm run lint:fix` to auto-fix issues
- Check `.spectral.yaml` for rule definitions
- Update OpenAPI spec if validation fails

**Deployment Issues:**

- Verify AWS credentials for deployment
- Check build output in `dist/` directory
- Review CI/CD logs for errors

## 📄 License

This documentation is licensed under the MIT License. See LICENSE file for
details.

## 🔗 Related Links

- **Lilith Platform**: https://lilith.ai
- **API Portal**: https://portal.lilith.ai
- **Status Page**: https://status.lilith.ai
- **Developer Blog**: https://blog.lilith.ai
- **GitHub Repository**: https://github.com/lilith-ai/lilith-platform

---

**Generated with ❤️ by the Lilith Platform Team**
