S5 Documentation Reorganization Plan¶

Date: 2025-11-23 Status: Planning Complexity: Medium Author: Claude Code

Executive Summary¶

This document outlines the plan to reorganize S5 Slidefactory documentation to align with the thin Azure client architecture. After the S5 client cleanup, the repository should only contain user-facing documentation and Azure infrastructure setup guides, not core development documentation.

Current State Analysis¶

Current Documentation Structure¶

docs/
├── admin/                      # User management, branding, deployment
├── api-reference/              # ❌ REMOVE - belongs in core
├── archive/                    # ✅ KEEP - migration history
├── code-reference/             # ❌ REMOVE - belongs in core
├── configuration/              # ⚠️ PARTIAL - keep Azure-specific only
├── database/                   # ❌ REMOVE - belongs in core
├── developer-guide/            # ❌ REMOVE - belongs in core
├── getting-started/            # ⚠️ PARTIAL - rework for S5 users
├── guides/                     # ⚠️ PARTIAL - keep user guides only
├── operations/                 # ⚠️ PARTIAL - keep Azure operations only
├── project/                    # ❌ REMOVE - belongs in core
├── reports/technical/          # ✅ ARCHIVE - move to archive/
└── user-guide/                 # ✅ KEEP - user-facing documentation

Issues with Current Structure¶

Duplicate/Core Documentation: Extensive developer docs (architecture, database, API) belong in slidefactory-core
Technical Reports: 90+ technical reports clutter docs/reports/technical/
Mixed Purpose: Docs mix core development, S5 deployment, and user guides
Complexity: Too many documentation sections for a thin client
Outdated: Many docs reference internal workflows, Docker setup (now removed)

Target State¶

New S5 Documentation Structure¶

docs/
├── README.md                           # Documentation overview
├── user-guide/                         # User-facing documentation
│   ├── index.md                        # Getting started with S5
│   ├── presentations.md                # Creating presentations
│   ├── templates.md                    # Managing templates
│   ├── api-keys.md                     # API key usage
│   └── n8n-workflows.md                # Using N8N workflows
├── azure/                              # Azure infrastructure documentation
│   ├── index.md                        # Azure architecture overview
│   ├── deployment.md                   # Deployment process (preview/main)
│   ├── local-development.md            # Local dev connecting to Azure preview
│   ├── infrastructure.md               # Azure resources (Container Apps, PostgreSQL, etc.)
│   ├── monitoring.md                   # Azure monitoring and logging
│   ├── troubleshooting.md              # Common Azure issues
│   └── resources/                      # S5-specific Azure resources
│       ├── gotenberg.md                # Gotenberg setup
│       └── librechat.md                # LibreChat setup (optional)
├── configuration/                      # S5 configuration
│   ├── index.md                        # Configuration overview
│   ├── environment-variables.md        # Azure-specific env vars
│   └── branding.md                     # S5 branding customization
├── operations/                         # S5 operations
│   ├── index.md                        # Operations overview
│   ├── github-actions.md               # CI/CD workflows
│   ├── monitoring.md                   # Production monitoring
│   └── backup-restore.md               # Backup and restore procedures
└── archive/                            # Historical reference
    ├── index.md                        # Archive overview
    └── technical-reports/              # All technical reports
        └── 2025-11-23_s5_client_cleanup_implementation_plan_revised.md
        └── [90+ existing reports]

Implementation Plan¶

Phase 1: Archive Technical Reports¶

Objective: Move all technical development reports to archive

# Create archive structure
mkdir -p docs/archive/technical-reports

# Move all technical reports
mv docs/reports/technical/*.md docs/archive/technical-reports/

# Remove empty reports directory
rm -rf docs/reports

# Create archive index
cat > docs/archive/index.md << 'EOF'
# Documentation Archive

This directory contains historical technical reports and migration documentation.

## Technical Reports

Technical reports documenting S5 development, migrations, and architectural decisions.

See [technical-reports/](technical-reports/) for the full list.

## Migration Documentation

Documentation about the repository separation and S5 client cleanup.

Key reports:
- [S5 Client Cleanup Implementation Plan](technical-reports/2025-11-23_s5_client_cleanup_implementation_plan_revised.md)
- [Repository Separation Guide](migration/2025-11-18_repository_separation_implementation_guide.md)

EOF

Files to Archive: 90+ technical reports in docs/reports/technical/

Phase 2: Remove Core Development Documentation¶

Objective: Remove documentation that belongs in slidefactory-core

# Remove core development docs
rm -rf docs/developer-guide/      # Core development guide
rm -rf docs/database/              # Database schema docs
rm -rf docs/code-reference/        # Code reference docs
rm -rf docs/api-reference/         # API reference docs
rm -rf docs/project/               # Project roadmap/changelog

# Remove duplicate/mixed guides
rm -rf docs/guides/                # Mixed core/S5 guides
rm -rf docs/getting-started/       # Will be replaced with S5-specific guide

Rationale: - These docs describe core platform functionality - Core development happens in slidefactory-core repo - S5 users need Azure deployment docs, not core development docs

Phase 3: Create S5-Specific User Guide¶

Objective: Create clear, concise user documentation for S5

docs/user-guide/index.md¶

# S5 Slidefactory User Guide

Welcome to S5 Slidefactory, the SportFive-branded presentation automation platform.

## What is S5 Slidefactory?

S5 is a presentation automation platform that generates PowerPoint presentations using AI and N8N workflows. It's deployed on Azure and branded for SportFive.

## Quick Start

1. **Access S5**: Navigate to https://slidefactory.sportfive.com
2. **Log in**: Use your Azure AD credentials
3. **Create Presentation**: Select a template and trigger a workflow
4. **Download**: Download your generated presentation

## Key Features

- **AI-Powered Generation**: Uses OpenAI/Azure OpenAI for content
- **N8N Workflows**: External workflow orchestration
- **Template Management**: Upload and manage PowerPoint templates
- **Azure AD Authentication**: Single sign-on with company credentials

## User Guides

- [Creating Presentations](presentations.md)
- [Managing Templates](templates.md)
- [Using API Keys](api-keys.md)
- [N8N Workflows](n8n-workflows.md)

## Support

For issues or questions:
- **S5-specific issues**: Contact S5 admin team
- **Core platform issues**: [slidefactory-core repository](https://github.com/cgast/slidefactory-core/issues)

docs/user-guide/presentations.md¶

# Creating Presentations

Learn how to create presentations using S5 Slidefactory.

## Via Web Interface

1. Navigate to **Presentations** page
2. Click **New Presentation**
3. Select a **Template** from the dropdown
4. Click **Generate**
5. Monitor progress on the Presentations list
6. Download when status shows **Completed**

## Via API

Generate presentations programmatically using the REST API.

### Authentication

Get an API key from the **Account** page:

```bash
# Via web interface
Account → API Keys → Create New Key

# Via CLI
slidefactory api-key create "My API Key" --user-id <your-user-id>

Generate Presentation¶

curl -X POST https://slidefactory.sportfive.com/api/presentations/generate \
  -H "Authorization: Bearer sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 123,
    "workflow_data": {
      "title": "Q3 Results",
      "data": {...}
    }
  }'

Response:

{
  "process_id": "proc_abc123",
  "status": "running"
}

Check Status¶

curl https://slidefactory.sportfive.com/api/presentations/status/proc_abc123 \
  -H "Authorization: Bearer sf_your_api_key_here"

Download Presentation¶

curl -L https://slidefactory.sportfive.com/api/presentations/download/proc_abc123 \
  -H "Authorization: Bearer sf_your_api_key_here" \
  -o presentation.pptx

Troubleshooting¶

Presentation Failed¶

Check N8N execution logs
Verify template is valid
Check workflow data format

Long Processing Time¶

Normal processing: 2-5 minutes
Complex presentations: 5-15 minutes
If >30 minutes: Contact support

Managing Templates
N8N Workflows

API Keys

### Phase 4: Create Azure Infrastructure Documentation

**Objective**: Document S5's Azure deployment architecture

#### docs/azure/index.md

```markdown
# S5 Azure Infrastructure

S5 Slidefactory is deployed on **Azure Container Apps** with supporting Azure services.

## Architecture Overview

┌─────────────────────────────────────────────────────────────┐ │ Azure Container Apps │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Web Service │ │ Worker Service │ │ │ │ (FastAPI) │────────▶│ (Celery) │ │ │ │ Port 8000 │ │ │ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Azure PostgreSQL│ │ Azure Redis │ │ with pgvector │ │ (Celery broker) │ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Azure Blob │ │ Storage │ └─────────────────┘

## Azure Resources

### Preview Environment

- **Resource Group**: `rg-slidefactory-preview`
- **Container App**: `slidefactory-web-preview`, `slidefactory-worker-preview`
- **Database**: `postgres-slidefactory-preview.postgres.database.azure.com`
- **Redis**: `redis-slidefactory-preview.redis.cache.windows.net`
- **Storage**: `slidefactorypreview` (Blob Storage account)

### Production Environment

- **Resource Group**: `rg-slidefactory-prod`
- **Container App**: `slidefactory-web-prod`, `slidefactory-worker-prod`
- **Database**: `postgres-slidefactory-prod.postgres.database.azure.com`
- **Redis**: `redis-slidefactory-prod.redis.cache.windows.net`
- **Storage**: `slidefactoryprod` (Blob Storage account)

## Deployment Model

S5 uses a **preview → production** deployment workflow:

1. **Development**: Commit to `preview` branch
2. **Preview Deployment**: GitHub Actions → Azure Container Apps (preview)
3. **Testing**: Test on preview environment
4. **Production**: Repository owner merges `preview` → `main`
5. **Production Deployment**: GitHub Actions → Azure Container Apps (production)

## Core Dependency

S5 uses the `slidefactory-core` package (v1.0.8) for all application logic.

The core package is:
- Installed from GitHub releases during Docker build
- Provides CLI (`slidefactory` command)
- Provides FastAPI app and Celery worker

## Documentation Sections

- [Deployment Process](deployment.md)
- [Local Development](local-development.md)
- [Infrastructure Details](infrastructure.md)
- [Monitoring & Logging](monitoring.md)
- [Troubleshooting](troubleshooting.md)

## S5-Specific Resources

Beyond core infrastructure, S5 includes:

- [Gotenberg PDF Service](resources/gotenberg.md)
- [LibreChat AI Interface](resources/librechat.md) (optional)

docs/azure/deployment.md¶

# Azure Deployment Process

S5 uses GitHub Actions for automated deployments to Azure Container Apps.

## Deployment Workflow

### Preview Deployment

**Trigger**: Push to `preview` branch

**Process**:
1. GitHub Actions workflow starts (`.github/workflows/preview.yml`)
2. Checkout code
3. Login to Azure (using `AZURE_CREDENTIALS` secret)
4. Build Docker image
   - Download slidefactory-core v1.0.8 from GitHub releases
   - Copy S5 branding assets
   - Install dependencies
5. Push image to Azure Container Registry
6. Update Container App with new image
7. Container App restarts with new image

**Preview URL**: https://slidefactory-preview.sportfive.com

**Duration**: ~5-10 minutes

### Production Deployment

**Trigger**: Push to `main` branch (repository owner only)

**Process**: Same as preview, but:
- Uses `AZURE_CREDENTIALS_PROD` secret
- Deploys to production resource group
- Tags image with `prod-{sha}`

**Production URL**: https://slidefactory.sportfive.com

**Duration**: ~5-10 minutes

## Manual Deployment

### Via Azure CLI

```bash
# Login to Azure
az login

# Update preview environment
az containerapp update \
  --name slidefactory-web-preview \
  --resource-group rg-slidefactory-preview \
  --image s5slidefactory.azurecr.io/slidefactory:preview-abc123

# Update production environment (owner only)
az containerapp update \
  --name slidefactory-web-prod \
  --resource-group rg-slidefactory-prod \
  --image s5slidefactory.azurecr.io/slidefactory:prod-abc123

Via Azure Portal¶

Navigate to Azure Portal
Go to Container App resource
Select Revision Management
Create new revision with updated image
Activate new revision

Rollback¶

Rollback to Previous Revision¶

# List revisions
az containerapp revision list \
  --name slidefactory-web-preview \
  --resource-group rg-slidefactory-preview

# Activate previous revision
az containerapp revision activate \
  --name slidefactory-web-preview \
  --resource-group rg-slidefactory-preview \
  --revision slidefactory-web-preview--abc123

Rollback via GitHub¶

# Revert commit on preview branch
git revert HEAD
git push origin preview

# Or reset to previous commit
git reset --hard HEAD~1
git push origin preview --force

Deployment Checklist¶

Before merging to production:

Preview deployment successful
Smoke tests pass on preview
Database migrations applied (if any)
Environment variables updated (if needed)
S5 branding displays correctly
Presentations generate successfully
N8N workflows execute
No errors in logs

Monitoring Deployment¶

GitHub Actions¶

View deployment progress: 1. Go to repository on GitHub 2. Click Actions tab 3. Select workflow run 4. View logs for each step

Azure Portal¶

Monitor Container App health: 1. Go to Container App resource 2. View Metrics for CPU/memory 3. Check Log stream for application logs 4. Review Revision management for active revision

Troubleshooting¶

Deployment Failed¶

Symptom: GitHub Actions workflow fails

Solutions: 1. Check GitHub Actions logs for error message 2. Verify Azure credentials are valid 3. Check if Container Registry is accessible 4. Verify Docker build succeeds locally

Container App Not Starting¶

Symptom: Deployment succeeds but app doesn't start

Solutions: 1. Check Container App logs in Azure Portal 2. Verify environment variables are set correctly 3. Check if database is accessible 4. Verify slidefactory-core version is available

Database Migration Issues¶

Symptom: App starts but database errors occur

Solutions: 1. Check if migrations ran successfully 2. Manually run migrations: az containerapp exec 3. Verify database connection string 4. Check pgvector extension is installed

Infrastructure Details
Local Development

Monitoring

### Phase 5: Clean Up Configuration Documentation

**Objective**: Keep only Azure-specific configuration docs

```bash
# Keep Azure-specific docs
# - docs/configuration/azure.md ✅
# - docs/configuration/environment-variables.md ✅
# Remove Docker docs
rm docs/configuration/docker.md

Update docs/configuration/index.md to focus on S5 Azure configuration only.

Phase 6: Update Operations Documentation¶

Objective: Focus on S5 Azure operations

Keep and update: - docs/operations/monitoring.md - Azure monitoring - docs/operations/troubleshooting.md - S5-specific troubleshooting - docs/operations/production-checklist.md - Azure production checklist

Remove: - Generic operations docs that belong in core

Phase 7: Update Main README¶

Objective: Clarify S5 as thin Azure client with link to docs

Update README.md to: 1. Emphasize S5 as Azure-only thin client 2. Link to user guide for getting started 3. Link to Azure infrastructure docs for deployment 4. Reference slidefactory-core for platform docs

Success Criteria¶

Documentation reorganization is complete when:

✅ All technical reports archived to docs/archive/technical-reports/
✅ Core development docs removed (developer-guide, database, code-reference, api-reference)
✅ User guide focuses on S5 usage (web UI, API, workflows)
✅ Azure infrastructure docs complete (deployment, monitoring, troubleshooting)
✅ Configuration docs focus on S5 Azure-specific settings
✅ Operations docs focus on S5 Azure operations
✅ README.md clearly positions S5 as thin Azure client
✅ Documentation structure is simple and intuitive
✅ No references to Docker Compose or local development (unless Azure preview)
✅ All links to core functionality point to slidefactory-core repo

Maintenance Guidelines¶

Going forward, S5 documentation should:

User-Facing Only: Focus on how to use S5, not how core platform works
Azure-Specific: Document Azure deployment, not generic deployment
Link to Core: Reference slidefactory-core docs for platform functionality
Archive Reports: New technical reports go to docs/archive/technical-reports/
Keep It Simple: S5 is a thin client, docs should be too

S5 Documentation Reorganization Plan¶

Executive Summary¶

Current State Analysis¶

Current Documentation Structure¶

Issues with Current Structure¶

Target State¶

New S5 Documentation Structure¶

Implementation Plan¶

Phase 1: Archive Technical Reports¶

Phase 2: Remove Core Development Documentation¶

Phase 3: Create S5-Specific User Guide¶

docs/user-guide/index.md¶

docs/user-guide/presentations.md¶

Generate Presentation¶

Check Status¶

Download Presentation¶

Troubleshooting¶

Presentation Failed¶

Long Processing Time¶

Related Documentation¶

docs/azure/deployment.md¶

Via Azure Portal¶

Rollback¶

Rollback to Previous Revision¶

Rollback via GitHub¶

Deployment Checklist¶

Monitoring Deployment¶

GitHub Actions¶

Azure Portal¶

Troubleshooting¶

Deployment Failed¶

Container App Not Starting¶

Database Migration Issues¶

Related Documentation¶

Phase 6: Update Operations Documentation¶

Phase 7: Update Main README¶

Success Criteria¶

Maintenance Guidelines¶

Related Documentation¶