homelab-frontend/WORKFLOWS_INDEX.md

Temporal Workflows - Documentation Index

📍 Start Here

New to workflows? Start with WORKFLOWS_QUICK_START.md (5 minutes)

---

📚 Documentation Map

Quick Reference

• WORKFLOWS_QUICK_START.md - 2-minute start guide
  • Basic request format
  • All 4 workflows with minimal examples
  • Common patterns and troubleshooting

Complete API Reference

• WORKFLOWS.md - Full documentation
  • Request/response schemas
  • All parameters for each workflow
  • Error handling guide
  • Examples in bash, Python, JavaScript
  • FAQ

Architecture & Implementation

• IMPLEMENTATION_SUMMARY.md - Technical details
  • Architecture overview
  • Files created/modified
  • Testing information
  • Extensibility guide
  • Performance characteristics

Overview

• WORKFLOWS_README.md - Project overview
  • High-level features
  • Integration details
  • Deployment guide
  • All 4 workflows explained

---

💻 Code & Examples

Source Code

• internal/proxy/workflows.go - Core implementation (450 lines)
• internal/proxy/workflows_test.go - Unit tests (280 lines)

Examples

• examples/workflows.sh - 8 cURL examples
• examples/workflows.py - Python client library with examples

Quick Copy-Paste

Bash:

curl -X POST http://localhost:8080/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "batch-embeddings",
    "input": {"texts": ["hello", "world"]}
  }'

Python:

import requests
response = requests.post(
    "http://localhost:8080/workflows",
    json={
        "workflow": "batch-embeddings",
        "input": {"texts": ["hello", "world"]}
    }
)
print(response.json())

---

🎯 By Use Case

I want to...

...get started quickly (5 minutes)

→ WORKFLOWS_QUICK_START.md

...understand all features (15 minutes)

→ WORKFLOWS.md

...integrate workflows into my app (20 minutes)

1. WORKFLOWS_QUICK_START.md - Learn the API
2. examples/workflows.py or examples/workflows.sh - See examples
3. WORKFLOWS.md - Check specific parameters

...add a new workflow (45 minutes)

1. IMPLEMENTATION_SUMMARY.md - Section "Extensibility"
2. internal/proxy/workflows.go - Study existing implementations
3. internal/proxy/workflows_test.go - Add tests
4. WORKFLOWS.md - Document

...troubleshoot an error (10 minutes)

→ WORKFLOWS_QUICK_START.md - Section "Troubleshooting" → WORKFLOWS.md - Section "Error Handling"

...understand the architecture (30 minutes)

→ IMPLEMENTATION_SUMMARY.md

---

📋 The 4 Workflows

1. batch-embeddings

Generate embeddings for multiple texts.

Doc: WORKFLOWS.md - batch-embeddings Quick: WORKFLOWS_QUICK_START.md - batch-embeddings Example: examples/workflows.sh - Example 4

2. chat-and-embed

Chat with a model, then embed the response.

Doc: WORKFLOWS.md - chat-and-embed Quick: WORKFLOWS_QUICK_START.md - chat-and-embed Example: examples/workflows.sh - Example 1

3. multi-model-chat

Chat with multiple models and compare responses.

Doc: WORKFLOWS.md - multi-model-chat Quick: WORKFLOWS_QUICK_START.md - multi-model-chat Example: examples/workflows.sh - Example 2

4. rag-pipeline

RAG workflow: rerank documents and answer based on top results.

Doc: WORKFLOWS.md - rag-pipeline Quick: WORKFLOWS_QUICK_START.md - rag-pipeline Example: examples/workflows.sh - Example 3

---

🚀 Getting Started

1. Build & Run (2 minutes)

cd /Users/rockliang/workplace/homelab-frontend
go build -o gateway ./cmd/gateway/
./gateway
# Listening on 127.0.0.1:8080

2. Test with cURL (1 minute)

curl -X POST http://localhost:8080/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "batch-embeddings",
    "input": {"texts": ["hello"]}
  }' | jq '.'

3. Read the Docs (5 minutes)

→ WORKFLOWS_QUICK_START.md

---

🔍 Quick Lookup

Request Format

See: WORKFLOWS_QUICK_START.md - Format Or: WORKFLOWS.md - Endpoint

Response Format

See: WORKFLOWS_QUICK_START.md - Response Format Or: WORKFLOWS.md - Response Schema

Error Handling

See: WORKFLOWS_QUICK_START.md - Error Messages Or: WORKFLOWS.md - Error Handling

Timeout Configuration

See: WORKFLOWS_QUICK_START.md - Optional Parameters Or: WORKFLOWS.md - Timeout Configuration

Parameters for each workflow

See: WORKFLOWS_QUICK_START.md - Available Workflows Or: WORKFLOWS.md - Each workflow section

---

📊 Feature Overview

Feature	Location
API Endpoint	/workflows (POST)
Request Format	JSON with workflow, input, timeout, wait
Workflows	4 pre-built: batch-embeddings, chat-and-embed, multi-model-chat, rag-pipeline
Error Handling	RFC 9457 Problem Details
Timeout Support	Configurable per request (default 30s)
Async/Sync	wait parameter (default true)
Documentation	1,488 lines across 4 markdown files
Examples	Bash (8), Python (7)
Tests	9 unit tests, 100% pass rate
Status	Production ready

---

🔗 Related Files

Configuration

• Check model configuration: internal/config/config.go
• Configure upstreams: Environment variables + config loading

Integration

• Proxy routing: internal/proxy/proxy.go
• Model dispatch: internal/proxy/router.go
• Health checks: internal/server/health.go

Deployment

• Main executable: cmd/gateway/main.go
• Dockerfile: Dockerfile
• K8s manifests: k8s/

---

✅ Verification Checklist

Before deploying:

• Code compiles: go build ./cmd/gateway/
• Tests pass: go test ./internal/proxy/... -v
• Read quick start: WORKFLOWS_QUICK_START.md
• Reviewed examples: examples/workflows.sh
• Understand error handling: WORKFLOWS.md - Error Handling
• Reviewed architecture: IMPLEMENTATION_SUMMARY.md

---

🆘 Help & Support

Issue: Gateway won't start

Check: go build ./cmd/gateway/ Docs: WORKFLOWS_README.md - Debugging

Issue: Workflow returns error

Check: WORKFLOWS_QUICK_START.md - Troubleshooting Docs: WORKFLOWS.md - Error Handling

Issue: Need more examples

Find: examples/workflows.sh and examples/workflows.py Or: WORKFLOWS.md - Examples

Issue: Want to add custom workflow

Read: IMPLEMENTATION_SUMMARY.md - Extensibility Study: internal/proxy/workflows.go (existing implementations)

---

📝 Document Sizes

Document	Lines	Size
WORKFLOWS.md	650	15KB
WORKFLOWS_QUICK_START.md	480	9.1KB
WORKFLOWS_README.md	400	12KB
IMPLEMENTATION_SUMMARY.md	310	9KB
Total Documentation	1,488	45KB
examples/workflows.sh	180	4.6KB
examples/workflows.py	350	11KB
Total Examples	530	16KB
internal/proxy/workflows.go	450	13KB
internal/proxy/workflows_test.go	280	6.2KB
Total Code	730	19KB

---

🎓 Learning Path

Time: ~1 hour for complete understanding

1. 5 min - WORKFLOWS_QUICK_START.md - Overview
2. 5 min - Try examples: curl -X POST http://localhost:8080/workflows ...
3. 15 min - WORKFLOWS.md - Complete reference
4. 10 min - Review examples/workflows.py or examples/workflows.sh
5. 15 min - IMPLEMENTATION_SUMMARY.md - Architecture
6. 5 min - Review internal/proxy/workflows.go - Implementation details

---

🎯 Common Tasks

Test all workflows

bash examples/workflows.sh

Run Python examples

python3 examples/workflows.py

Run tests

go test ./internal/proxy/... -v -run Workflow

Build for production

go build -o gateway ./cmd/gateway/
docker build -t homelab-gateway:latest .

Check logs

kubectl -n api logs deployment/homelab-frontend

---

📞 Quick Reference

Need	File
2-min overview	WORKFLOWS_QUICK_START.md
Complete API	WORKFLOWS.md
Examples (bash)	examples/workflows.sh
Examples (Python)	examples/workflows.py
Architecture	IMPLEMENTATION_SUMMARY.md
Implementation	internal/proxy/workflows.go
Tests	internal/proxy/workflows_test.go

---

Ready to start? → WORKFLOWS_QUICK_START.md

Need help? → Check the "Help & Support" section above