Documentation Hub

Welcome to the Holistix Forge documentation! This hub will guide you to the right resources.

🎯 I Want To...

Get Started

• 🚀 Set up local development - Multi-environment dev setup
• 🏭 Production deployment - Deploy on Ubuntu VPS
• 🤝 Contribute - Development workflow and standards

Understand the System

• 🏗️ Architecture Overview - System design and components
• 📐 System Architecture - Complete architecture diagram
• 📊 Gateway Architecture - Multi-gateway pool architecture
• 🔒 Protected Services - Module-driven protected endpoints
• 📡 Logging & Observability - Logs, traces, error categories, and OTel stack
• 🎨 Layer System Architecture - Modular whiteboard layers (Excalidraw integration)

Production Deployment

• 📋 Production Deployment Guide - Complete planning & reference (future work)

Learn How To

• 🧪 Testing Guide - Comprehensive testing strategies for frontend, backend, and components
• 🧪 Test Modules - Module stories and fake collab
• 📦 Use Nx Workspace - Monorepo commands and workflows
• 🎨 Build UI Components - Module development with Storybook
• 🔧 Package Architecture - React dependency management and package patterns
• 🚀 Gateway Build Distribution - HTTP build distribution system
• 🔌 Module Reference - Individual module documentation
• 🩹 Troubleshooting - Common issues and solutions

Quick Reference

• ⚡ Cheatsheet - Common commands and aliases
• 🔌 API Reference - REST API endpoints
• 🖥️ GPU Host Setup - Configure GPU access for Docker
• 📄 Licensing - License information and commercial licensing

Work In Progress

see github issues

Historical

• 📚 Archive - Superseded documentation (preserved for reference)

📂 Documentation Structure

doc/
├── README.md                 ← You are here
│
├── architecture/             # System Design
│   ├── OVERVIEW.md                   - High-level architecture
│   ├── SYSTEM_ARCHITECTURE.md        - Complete system diagram
│   ├── GATEWAY_ARCHITECTURE.md       - Multi-gateway architecture
│   └── ARCHITECTURAL_DECISIONS.md    - Key design decisions
│
├── guides/                   # How-To Guides
│   ├── LOCAL_DEVELOPMENT.md  - Multi-env local setup
│   ├── TESTING_GUIDE.md      - Testing strategies & examples
│   ├── MODULES_TESTING.md    - Module development & testing
│   └── NX_WORKSPACE.md       - Nx monorepo workflows
│
├── reference/                # Quick Reference
│   ├── CHEATSHEET.md         - Commands, aliases, tools
│   ├── API.md                - REST API documentation
│   └── GPU_HOST_SETUP.md     - GPU configuration
│
└── archive/                  # Historical Docs
    ├── README.md             - Archive context
    ├── 2024-container-refactor/  - Container feature redesign
    └── project-server-state-and-transition.md  - Legacy states

🎓 Learning Paths

New Developer

1. Read Architecture Overview
2. Set up Local Development
3. Review Contributing Guidelines
4. Browse Cheatsheet
5. Review Testing Guide
6. Try Module Testing

Frontend Developer

1. Local Development Setup
2. Testing Guide (React components, LocalStorage)
3. Module Testing with Storybook
4. Nx Workspace Guide
5. API Reference (for backend integration)

Backend Developer

1. Architecture Overview
2. Local Development Setup
3. Testing Guide (Express API testing)
4. API Reference
5. System Architecture
6. Gateway Architecture
7. Nx Workspace Guide

DevOps/SRE

1. Architecture Overview
2. Local Development
3. Production Deployment
4. GPU Host Setup
5. Gateway Architecture

🔍 Finding Information

By Topic

• Authentication: Overview, API Reference
• Collaboration: Overview, Gateway Architecture, Modules Testing
• Containers: System Architecture, User Containers Module, Docker Images
• Protected Services: Protected Services Architecture
• Terminal Access: User Containers Module (Web-based terminals)
• Testing: Testing Guide, Modules Testing
• Database: Overview, Gateway Architecture
• Gateway: Gateway Architecture, System Architecture
• Modules: Module Reference, Modules Testing, Overview

Search Tips

• Use Ctrl+F / Cmd+F to search within a document
• Use GitHub search to search across all docs
• Check Archive for historical context

📝 Contributing to Documentation

When updating documentation:

1. Keep it current - Remove outdated information
2. Be concise - Short and clear is better than long and confusing
3. Use examples - Code examples clarify intent
4. Link related docs - Help readers navigate
5. Update this hub - Add links for new documents

See CONTRIBUTING.md for more details.

🙋 Need Help?

• Something unclear? Open an issue asking for clarification
• Found outdated info? Submit a PR or issue
• Need examples? Check Archive for historical context
• Still stuck? Ask in GitHub Discussions

Last updated: 2025-01-06
Maintained by: Core team

History and Rationale

• 📖 Fluid Lifecycle Whitepaper – learn why Holistix Forge began, the pain points it targets, and the original engineering rationale.