# Known Limitations

This document provides an honest assessment of current limitations, known
issues, and areas under active development. We believe in transparency about
what works well and what needs improvement.

## Table of Contents

- [Platform Maturity](#platform-maturity)
- [AI Generation Limitations](#ai-generation-limitations)
- [3D Generation Limitations](#3d-generation-limitations)
- [Engine Integration Limitations](#engine-integration-limitations)
- [Performance Limitations](#performance-limitations)
- [Scalability Considerations](#scalability-considerations)
- [Security Considerations](#security-considerations)
- [API Limitations](#api-limitations)
- [Known Bugs](#known-bugs)
- [Roadmap Items](#roadmap-items)

---

## Platform Maturity

### Current State

Yemaya is under **active development**. While many features are implemented and
functional, the platform should be considered:

- **Alpha/Beta quality** for production use
- **Suitable for evaluation**, prototyping, and development
- **Not yet recommended** for mission-critical production workloads without
  thorough testing

### What Works Well

- Core API infrastructure and authentication
- Database layer (PostgreSQL, Redis, MinIO)
- AI text generation with multiple providers
- 3D model generation pipeline
- GPU job dispatch system
- Real-time collaboration foundation

### What Needs Work

- End-to-end testing coverage
- Production deployment hardening
- Documentation completeness
- Performance optimization at scale
- Some provider integrations

---

## AI Generation Limitations

### Text Generation

| Limitation    | Details                                           | Workaround                                              |
| ------------- | ------------------------------------------------- | ------------------------------------------------------- |
| Token limits  | Max ~100K tokens per request (provider-dependent) | Chunk large documents                                   |
| Rate limits   | Provider-imposed limits on requests/minute        | Use caching, queue requests                             |
| Cost          | Can be expensive at scale                         | Enable cost optimization, use cheaper models for drafts |
| Hallucination | LLMs may generate incorrect information           | Implement verification workflows                        |
| Consistency   | Results vary between requests                     | Use temperature=0, provide examples                     |

### Image Generation

| Limitation        | Details                                      | Workaround                               |
| ----------------- | -------------------------------------------- | ---------------------------------------- |
| Resolution        | Max 1024x1024 (DALL-E 3), varies by provider | Upscale post-generation                  |
| Style consistency | Hard to maintain across multiple images      | Use consistent prompts, style references |
| Text in images    | Often renders incorrectly                    | Generate text separately, composite      |
| Specific details  | May miss exact requirements                  | Iterative refinement                     |

### Audio Generation

| Limitation    | Details                                   | Workaround                      |
| ------------- | ----------------------------------------- | ------------------------------- |
| Length        | Music generation limited to ~30s segments | Concatenate segments            |
| Voice quality | Cloned voices may sound artificial        | Use premium voices, fine-tuning |
| Real-time     | Not suitable for real-time streaming      | Pre-generate, cache results     |

---

## 3D Generation Limitations

### Model Quality

| Limitation      | Details                                         | Workaround                               |
| --------------- | ----------------------------------------------- | ---------------------------------------- |
| Polygon count   | Generated models often have suboptimal topology | Use mesh optimization post-processing    |
| UV mapping      | May require manual cleanup                      | Auto-UV unwrapping, manual touch-up      |
| Texture quality | Can be low resolution or inconsistent           | Texture upscaling, manual texturing      |
| Animation-ready | Not automatically rigged for animation          | Use auto-rigging feature, manual rigging |

### Generation Time

| Provider | Typical Time  | Notes                    |
| -------- | ------------- | ------------------------ |
| Hunyuan  | 2-5 minutes   | Good quality, slower     |
| Meshy    | 30s-2 minutes | Faster, variable quality |
| Tripo    | 1-3 minutes   | Good balance             |
| Local    | Varies        | Depends on hardware      |

### Format Support

- **Fully supported**: GLB, GLTF, OBJ, FBX
- **Partially supported**: USD, USDZ (export only)
- **Not supported**: Proprietary formats (Maya MB, 3DS Max)

### Known Issues

1. **Complex scenes**: Multi-object generation is inconsistent
2. **Specific objects**: Some object types (vehicles, architecture) have lower
   quality
3. **Scale**: Generated models may have incorrect real-world scale
4. **Materials**: PBR material generation is basic

---

## Engine Integration Limitations

### Blender Integration

| Limitation           | Details                          | Status                   |
| -------------------- | -------------------------------- | ------------------------ |
| Version support      | Only Blender 4.0+ supported      | By design                |
| WebSocket connection | Requires Blender addon installed | Manual setup required    |
| Real-time sync       | Some operations have latency     | Optimization ongoing     |
| Crash recovery       | Limited state recovery           | Implementing checkpoints |

### Godot Integration

| Limitation      | Details                     | Status                     |
| --------------- | --------------------------- | -------------------------- |
| Version support | Only Godot 4.2+ supported   | By design                  |
| GDExtension     | Requires native compilation | CMake build system         |
| Hot reload      | Limited hot reload support  | Workaround: restart editor |

### Unreal Integration

| Limitation           | Details                      | Status                    |
| -------------------- | ---------------------------- | ------------------------- |
| Version support      | Only UE 5.3+ supported       | By design                 |
| Blueprint generation | Basic blueprint support      | Advanced features pending |
| Live link            | Requires plugin installation | Documentation available   |
| Linux                | Limited support              | Windows/Mac prioritized   |

### Unity Integration

| Limitation         | Details                     | Status                 |
| ------------------ | --------------------------- | ---------------------- |
| Version support    | Unity 2022.3+ recommended   | LTS versions supported |
| Package manager    | Manual package installation | UPM support planned    |
| Gaussian splatting | Experimental feature        | Active development     |

---

## Performance Limitations

### API Performance

| Metric                | Current     | Target      | Notes                   |
| --------------------- | ----------- | ----------- | ----------------------- |
| Request latency (p50) | ~50ms       | <30ms       | Excluding AI operations |
| Request latency (p99) | ~200ms      | <100ms      | Optimization ongoing    |
| Throughput            | ~1000 req/s | ~5000 req/s | Single instance         |
| WebSocket connections | ~10,000     | ~50,000     | Per instance            |

### Database Performance

| Operation        | Current   | Notes                  |
| ---------------- | --------- | ---------------------- |
| Simple queries   | <10ms     | Well-optimized         |
| Complex joins    | 50-200ms  | May need optimization  |
| Bulk operations  | Variable  | Batch size dependent   |
| Full-text search | 100-500ms | Consider Elasticsearch |

### Storage Performance

| Operation                  | Current | Notes                      |
| -------------------------- | ------- | -------------------------- |
| Small file upload (<1MB)   | <1s     | Good                       |
| Large file upload (>100MB) | 10-60s  | Multipart upload           |
| Thumbnail generation       | 1-5s    | Async processing           |
| Video transcoding          | Minutes | GPU acceleration available |

---

## Scalability Considerations

### Current Scale Tested

- **Users**: Up to 1,000 concurrent users
- **Requests**: Up to 10,000 requests/minute
- **Data**: Up to 1TB storage tested
- **GPU Jobs**: Up to 100 concurrent jobs

### Scaling Bottlenecks

1. **Database connections**: Connection pooling required at scale
2. **Redis memory**: May need Redis Cluster for large caches
3. **Storage I/O**: CDN recommended for asset delivery
4. **GPU providers**: Rate limits vary by provider

### Not Yet Tested

- Multi-region deployment
- 10,000+ concurrent users
- 100+ concurrent GPU jobs
- Petabyte-scale storage

---

## Security Considerations

### Implemented

- JWT-based authentication with refresh tokens
- Role-based access control (RBAC)
- Rate limiting and DDoS protection
- Input validation (Zod schemas)
- SQL injection prevention (Prisma ORM)
- CORS configuration
- Helmet security headers

### Pending/Partial

| Feature               | Status                | Notes                          |
| --------------------- | --------------------- | ------------------------------ |
| SOC 2 compliance      | Assessment complete   | Certification pending          |
| GDPR compliance       | Partially implemented | Data export/deletion available |
| HIPAA compliance      | Not implemented       | Not currently in scope         |
| Audit logging         | Basic implementation  | Advanced features pending      |
| Encryption at rest    | Provider-dependent    | S3/MinIO native encryption     |
| End-to-end encryption | Not implemented       | Planned for sensitive data     |

### Known Security Limitations

1. **API keys**: No automatic rotation (manual process)
2. **Session management**: Limited concurrent session controls
3. **File uploads**: Basic malware scanning only
4. **Third-party dependencies**: Regular updates required

---

## API Limitations

### General API Limits

| Limit             | Value     | Notes                    |
| ----------------- | --------- | ------------------------ |
| Request body size | 10MB      | Increase via config      |
| File upload size  | 100MB     | Multipart for larger     |
| Response timeout  | 30s       | Longer for AI operations |
| Pagination max    | 100 items | Per page                 |
| Batch operations  | 100 items | Per request              |

### Endpoint-Specific Limits

| Endpoint       | Limit             | Notes                 |
| -------------- | ----------------- | --------------------- |
| `/ai/generate` | 10 req/min (free) | Tier-based            |
| `/3d/generate` | 5 req/min         | Cost-based throttling |
| `/auth/login`  | 5 attempts        | Then 15min lockout    |
| `/webhooks`    | 100 registered    | Per account           |

### Missing Features

- GraphQL API (REST only)
- Batch API for bulk operations (partial)
- API versioning (v1 only currently)
- Idempotency keys (partial support)

---

## Known Bugs

### Critical (Actively Working On)

None currently tracked.

### High Priority

1. **WebSocket reconnection**: Occasional connection drops under high load
2. **Large file uploads**: Progress reporting inaccurate for files >500MB
3. **3D preview**: Memory leak in preview renderer after extended use

### Medium Priority

1. **Search**: Full-text search performance degrades with large datasets
2. **Collaboration**: Cursor position sync can lag in complex documents
3. **Asset versioning**: Diff view not working for binary files

### Low Priority

1. **UI**: Minor styling inconsistencies in dark mode
2. **Logs**: Timestamp formatting inconsistent across services
3. **Export**: Some edge cases in CSV export

---

## Roadmap Items

### Near-term (Next 3 months)

- [ ] Performance optimization for large-scale deployment
- [ ] Improved 3D model quality and consistency
- [ ] Better error messages and debugging tools
- [ ] Comprehensive end-to-end test suite
- [ ] SOC 2 Type II certification

### Medium-term (3-6 months)

- [ ] GraphQL API support
- [ ] Multi-region deployment support
- [ ] Advanced video generation features
- [ ] Improved game engine integration
- [ ] Mobile SDK (React Native)

### Long-term (6-12 months)

- [ ] Self-hosted deployment option
- [ ] Enterprise SSO (SAML, OIDC)
- [ ] Custom model training
- [ ] AR/VR integration
- [ ] Offline mode support

---

## Reporting Issues

If you encounter issues not listed here:

1. **Check existing issues**:
   [GitHub Issues](https://github.com/yemaya/yemaya/issues)
2. **Search documentation**: Many common issues are documented
3. **Create new issue**: Include reproduction steps, environment details
4. **Join Discord**: Real-time help from community

### Issue Template

```markdown
## Description

Brief description of the issue

## Steps to Reproduce

1. Step one
2. Step two
3. ...

## Expected Behavior

What should happen

## Actual Behavior

What actually happens

## Environment

- OS:
- Node.js version:
- Browser (if applicable):
- Yemaya version:

## Additional Context

Any other relevant information
```

---

## Getting Help

- **Documentation**: https://docs.yemaya.io
- **GitHub Issues**: https://github.com/yemaya/yemaya/issues
- **Discord**: https://discord.gg/yemaya
- **Email**: support@yemaya.io

We appreciate your patience as we continue to improve the platform. Your
feedback helps us prioritize what matters most.
