S5 Client Cleanup Implementation Plan¶

Date: 2025-11-22 Status: Implementation Plan Author: Claude Code Complexity: Medium-high complexity migration with architectural benefits Risk Level: Medium

Executive Summary¶

This document provides a detailed implementation plan for converting the S5 Slidefactory repository from a monolithic codebase to a thin client that depends on the slidefactory-core package. This completes the repository separation strategy outlined in the November 2025 migration guides.

Current State: - S5 repository contains duplicate core code (app/, cli/, alembic/, tests/) - Core package exists at ../slidefactory-core with version 1.0.8 - S5 uses monolith-style imports (app.*) - No clear separation between core functionality and S5-specific branding/deployment

Target State: - S5 repository contains only branding, configuration, and deployment files - S5 depends on slidefactory-core==1.0.8 via pyproject.toml - Core functionality provided by installed package - Clear separation of concerns: core logic vs. client deployment

Benefits: - Single source of truth for core functionality - Easier maintenance and updates - Clear deployment boundaries - Consistent with repository separation architecture - Reduced code duplication

Assessment Summary¶

Current Repository State¶

✅ Verified: - Core package (slidefactory-core) exists at ../slidefactory-core with version 1.0.8 - Core has all application code under src/slidefactory/ with proper package structure - Core uses proper imports (slidefactory.app.*) - S5 branding files identified in static/img/branding/ and scattered locations

❌ Issues: - S5 repo still has duplicate code in app/, cli/, alembic/, static/, templates/ - S5 repo has old setup.py for CLI (should use core's package) - S5 repo has migration docs that belong in core or archive - S5 uses old monolith imports (app.*)

Key Differences¶

Aspect	Core Package	S5 Current	S5 Target
Import Style	`slidefactory.app.*`	`app.*`	Use core package
Package Structure	`src/slidefactory/`	`app/` at root	No app code
Version	1.0.8	N/A	Depends on core
CLI	`slidefactory` command	Local `setup.py`	Use core's CLI
Distribution	Python package	Monolith	Thin client

Repository Structure Changes¶

Files to KEEP in S5 Repo¶

Configuration: - .env, .env.azure.*, .env.local - S5-specific configuration - .env.s5 - New S5 environment template - .gitignore, .gitattributes - Git configuration - .github/workflows/ - Azure deployment workflows (updated)

S5-Specific Assets: - S5 branding files (moved to s5_branding/) - S5-specific documentation in docs/ (deployment guides, Azure setup)

Deployment: - Dockerfile - Updated to use core package - docker-compose.s5.yml - S5 local development (updated) - scripts/ - S5 deployment scripts (updated) - start.sh - Local development startup (updated)

Project Files: - README.md - S5-specific documentation (rewritten) - pyproject.toml - New S5 client package definition - Git history and configuration

Files to REMOVE from S5 Repo¶

Core Application Code: - app/ - Entire FastAPI application (now in core) - cli/ - CLI tool (now in core package) - alembic/ - Database migrations (now in core) - alembic.ini - Migration configuration (now in core)

Core Assets: - static/ - Except S5 branding (moved to s5_branding/static/) - templates/ - Except S5 overrides (moved to s5_branding/templates/)

Core Testing: - tests/ - Core tests (now in core repo) - pytest.ini - Testing configuration (now in core) - .coverage, htmlcov/ - Coverage artifacts

Core Infrastructure: - init.sql, init_test.sql - Database initialization (now in core) - packages/ - N8N nodes package (now in core) - bootstrap-database.sh - Database setup script (now in core)

Old Package Files: - setup.py - Old CLI setup (replaced by pyproject.toml) - s5_slidefactory_cli.egg-info/ - Old package metadata - requirements.txt, requirements-dev.txt - Replaced by pyproject.toml

Build Artifacts: - site/ - MkDocs build output (docs now in core) - mkdocs.yml - Documentation config (now in core) - test_workflow_engines.py - Core test file

Migration Documentation: - docs/reports/technical/2025-11-18_repository_separation_*.md - Archive these - docs/reports/technical/2025-11-20_core_*.md - Archive these - docs/reports/technical/2025-11-20_eddy_*.md - Archive these

New S5 Repository Structure¶

s5-slidefactory/
├── pyproject.toml                    # S5 package with core dependency
├── README.md                         # S5-specific documentation
├── .env.s5                          # S5 environment template
├── .env, .env.azure.*, .env.local   # S5 configurations
├── s5_branding/                     # S5-specific branding
│   ├── __init__.py
│   ├── static/
│   │   ├── css/
│   │   │   └── s5-custom.css
│   │   └── img/
│   │       ├── sportfive_logo.png
│   │       ├── sportfive_large.png
│   │       ├── sportfive_small.png
│   │       ├── bannerlogo.png
│   │       ├── sf_logo_*.png
│   │       └── favicon.ico
│   └── templates/                   # S5-specific overrides (if needed)
├── .github/
│   └── workflows/
│       ├── preview.yml              # Azure preview deployment
│       └── production.yml           # Azure production deployment
├── docker-compose.s5.yml            # S5 local development
├── scripts/
│   ├── start-web-azure.sh           # Updated to use core
│   ├── start-worker-azure.sh        # Updated to use core
│   └── deploy-azure.sh              # Azure deployment helper
├── Dockerfile                       # S5-specific (installs core)
├── start.sh                         # Local development (updated)
├── docs/
│   ├── deployment.md                # Azure deployment guide
│   ├── archive/
│   │   └── migration/               # Archived migration docs
│   └── reports/technical/           # S5-specific technical reports
└── README.md                        # S5 user documentation

Implementation Plan - CLI Commands¶

PHASE 1: BACKUP & PREPARATION¶

# 1. Create backup of current state
git checkout -b backup-before-s5-cleanup-$(date +%Y%m%d)
git push origin backup-before-s5-cleanup-$(date +%Y%m%d)

# 2. Verify core package is available
ls -la ../slidefactory-core/src/slidefactory/
cat ../slidefactory-core/pyproject.toml | grep version

# 3. Create working branch for cleanup
git checkout preview
git pull origin preview
git checkout -b feature/s5-client-cleanup

PHASE 2: CREATE S5 BRANDING STRUCTURE¶

# 4. Create S5 branding directory structure
mkdir -p s5_branding/static/img
mkdir -p s5_branding/static/css
mkdir -p s5_branding/templates

# 5. Move S5-specific images to branding folder
mv static/img/branding/* s5_branding/static/img/
mv static/img/sf_logo_*.png s5_branding/static/img/
mv static/img/sportfive* s5_branding/static/img/

# 6. Create S5 custom CSS (if needed)
touch s5_branding/static/css/s5-custom.css

# 7. Create __init__.py for S5 branding package
cat > s5_branding/__init__.py << 'EOF'
"""S5 SportFive branding package for Slidefactory."""
__version__ = "1.0.0"
EOF

PHASE 3: CREATE S5 CLIENT CONFIGURATION¶

# 8. Create S5-specific pyproject.toml
cat > pyproject.toml << 'EOF'
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "s5-slidefactory"
version = "1.0.0"
description = "S5 SportFive Slidefactory - Azure Deployment Client"
requires-python = ">=3.11"
dependencies = [
    "slidefactory-core==1.0.8",  # Pin to specific core version
]

[project.optional-dependencies]
azure = [
    "azure-storage-blob>=12.19.0",
    "azure-identity>=1.15.0",
    "msal>=1.26.0",
]

[tool.setuptools]
packages = ["s5_branding"]
EOF

# 9. Create S5-specific .env.s5 template
cat > .env.s5 << 'EOF'
# S5 SportFive Branding
CLIENT_NAME="SportFive Slidefactory"
CLIENT_LOGO="/s5_branding/static/img/sportfive_logo.png"
CLIENT_LOGO_LARGE="/s5_branding/static/img/sportfive_large.png"
CLIENT_PRIMARY_COLOR="#ee0000"

# S5 Deployment
DEPLOYMENT_PLATFORM="azure"
SERVER_URL="https://slidefactory.sportfive.com"

# Storage (Azure)
STORAGE_PROVIDER="azure"
AZURE_STORAGE_ACCOUNT_NAME="${AZURE_STORAGE_ACCOUNT_NAME}"
AZURE_STORAGE_ACCOUNT_KEY="${AZURE_STORAGE_ACCOUNT_KEY}"

# Auth (Azure AD)
AZURE_TENANT_ID="${AZURE_TENANT_ID}"
AZURE_CLIENT_ID="${AZURE_CLIENT_ID}"
AZURE_CLIENT_SECRET="${AZURE_CLIENT_SECRET}"
AZURE_REDIRECT_URI="${AZURE_REDIRECT_URI}"

# Database (from secrets)
DATABASE_URL="${DATABASE_URL}"

# Redis (from secrets)
REDIS_HOST="${REDIS_HOST}"
REDIS_PORT="${REDIS_PORT}"
REDIS_PASSWORD="${REDIS_PASSWORD}"
REDIS_SSL=true

# AI (from secrets)
OPENAI_API_KEY="${OPENAI_API_KEY}"
AZURE_OPENAI_API_KEY="${AZURE_OPENAI_API_KEY}"
EOF

# 10. Update Dockerfile to use core package
cat > Dockerfile << 'EOF'
FROM python:3.11-slim

WORKDIR /code

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Copy S5 package files
COPY pyproject.toml /code/
COPY s5_branding/ /code/s5_branding/

# Install S5 package with Azure dependencies (installs core automatically)
RUN pip install --no-cache-dir -e ".[azure]"

# Copy S5 scripts
COPY scripts/ /code/scripts/
RUN chmod +x /code/scripts/*.sh

# Expose S5 branding as static files
RUN ln -s /code/s5_branding/static /code/static/s5_branding

# Expose port
EXPOSE 8000

# Use S5 startup script
CMD ["/code/scripts/start-web-azure.sh"]
EOF

# 11. Update docker-compose.yml for local development
cat > docker-compose.s5.yml << 'EOF'
version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - TZ=Europe/Berlin
    env_file:
      - .env.s5
    volumes:
      - ./s5_branding:/code/s5_branding
      - ./downloads:/code/downloads
    depends_on:
      - postgres
      - redis
      - minio
    command: /code/scripts/start-web-azure.sh

  worker:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - TZ=Europe/Berlin
    env_file:
      - .env.s5
    depends_on:
      - postgres
      - redis
      - minio
    command: slidefactory worker start

  postgres:
    image: ankane/pgvector:latest
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: slidefactory
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: adminadminadmin
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

volumes:
  postgres_data:
  minio_data:
EOF

PHASE 4: UPDATE SCRIPTS FOR CORE PACKAGE¶

# 12. Update start-web-azure.sh
cat > scripts/start-web-azure.sh << 'EOF'
#!/bin/bash
set -e

echo "Starting S5 Slidefactory Web (Azure deployment)..."

# Run migrations (from core package)
echo "Running database migrations..."
alembic upgrade head

# Initialize system if needed (from core package CLI)
echo "Initializing system..."
slidefactory init check || slidefactory init all

# Start uvicorn (core package's FastAPI app)
echo "Starting web server..."
exec uvicorn slidefactory.app.main:app --host 0.0.0.0 --port 8000
EOF
chmod +x scripts/start-web-azure.sh

# 13. Update start-worker-azure.sh
cat > scripts/start-worker-azure.sh << 'EOF'
#!/bin/bash
set -e

echo "Starting S5 Slidefactory Worker (Azure deployment)..."

# Start Celery worker (from core package)
exec celery -A slidefactory.app.celery_app worker --loglevel=info --concurrency=2
EOF
chmod +x scripts/start-worker-azure.sh

# 14. Create simple start.sh for local development
cat > start.sh << 'EOF'
#!/bin/bash
# S5 Slidefactory local development startup
# Uses core package installed in development mode

set -e

echo "Starting S5 Slidefactory (local development)..."

# Load environment
if [ -f .env.s5 ]; then
    export $(cat .env.s5 | grep -v '^#' | xargs)
fi

# Start uvicorn with reload (core package)
exec uvicorn slidefactory.app.main:app --host 0.0.0.0 --port 8080 --reload
EOF
chmod +x start.sh

PHASE 5: UPDATE DOCUMENTATION¶

# 15. Create S5-specific README
cat > README.md << 'EOF'
# S5 SportFive Slidefactory

SportFive-branded deployment of Slidefactory on Azure Container Apps.

## Overview

This repository contains the SportFive-specific configuration, branding, and deployment setup for Slidefactory.

**Core Engine:** [slidefactory-core](https://github.com/cgast/slidefactory-core) v1.0.8

## Quick Start

### Local Development

```bash
# Install dependencies (installs core package automatically)
pip install -e ".[azure]"

# Configure environment
cp .env.s5 .env
# Edit .env with your secrets

# Start with Docker Compose
docker-compose -f docker-compose.s5.yml up

Access: http://localhost:8000

Azure Deployment¶

Automatic deployment via GitHub Actions: - Preview: Push to preview branch → Azure Container Apps (preview environment) - Production: Push to main branch → Azure Container Apps (production)

S5 Branding¶

S5 branding assets are in s5_branding/static/: - Logo: SportFive red logo - Colors: Red (#ee0000) primary - Custom CSS: s5_branding/static/css/s5-custom.css

Configuration¶

See .env.s5 for S5-specific settings.

Azure Resources: - Container Apps: Web and Worker services - Storage: Azure Blob Storage - Database: Azure Database for PostgreSQL with pgvector - Redis: Azure Cache for Redis

CLI Commands¶

All CLI commands are provided by the core package:

# System initialization
slidefactory init all

# User management
slidefactory user list
slidefactory user create-local user@example.com --name "John Doe"

# API keys
slidefactory api-key create "My Key" --user-id 1

# Presentations
slidefactory presentation generate --template-id 123

Support¶

S5-specific issues: Create issue in this repository
Core platform issues: slidefactory-core issues

License¶

Proprietary - SportFive internal use only EOF

16. Archive migration docs¶

mkdir -p docs/archive/migration mv docs/reports/technical/2025-11-18_repository_separation_.md docs/archive/migration/ mv docs/reports/technical/2025-11-20_core_.md docs/archive/migration/ mv docs/reports/technical/2025-11-20_eddy_*.md docs/archive/migration/

### PHASE 6: REMOVE CORE CODE

```bash
# 17. Remove core application code
rm -rf app/
rm -rf cli/
rm -rf alembic/
rm -f alembic.ini

# 18. Remove core static/templates (keep structure for mounting)
rm -rf static/css/
rm -rf static/js/
rm -rf static/vendor/
rm -rf static/img/  # S5 images already moved
rm -rf templates/

# 19. Remove core test infrastructure
rm -rf tests/
rm -f pytest.ini

# 20. Remove core database files
rm -f init.sql
rm -f init_test.sql

# 21. Remove old package setup
rm -f setup.py
rm -rf s5_slidefactory_cli.egg-info/

# 22. Remove core requirements files
rm -f requirements.txt
rm -f requirements-dev.txt

# 23. Remove core package directory (N8N nodes)
rm -rf packages/

# 24. Remove core-specific files
rm -f test_workflow_engines.py
rm -f bootstrap-database.sh

# 25. Clean up old build artifacts
rm -rf htmlcov/
rm -f .coverage
rm -rf site/  # MkDocs build output (docs now in core)
rm -f mkdocs.yml

PHASE 7: UPDATE GITHUB ACTIONS¶

# 26. Update preview.yml workflow
cat > .github/workflows/preview.yml << 'EOF'
name: Deploy S5 to Azure Preview

on:
  push:
    branches: [preview]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install -e ".[azure]"

      - name: Login to Azure
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Build and push Docker image
        run: |
          docker build -t s5slidefactory.azurecr.io/slidefactory:preview-${{ github.sha }} .
          docker push s5slidefactory.azurecr.io/slidefactory:preview-${{ github.sha }}

      - name: Deploy to Azure Container Apps
        run: |
          az containerapp update \
            --name slidefactory-web-preview \
            --resource-group rg-slidefactory-preview \
            --image s5slidefactory.azurecr.io/slidefactory:preview-${{ github.sha }}
EOF

# Similar update for production.yml (not shown for brevity)

PHASE 8: COMMIT CHANGES¶

# 27. Review changes
git status
git diff --stat

# 28. Stage S5-specific files
git add s5_branding/
git add pyproject.toml
git add .env.s5
git add Dockerfile
git add docker-compose.s5.yml
git add scripts/
git add start.sh
git add README.md
git add .github/workflows/

# 29. Stage removals
git add -u  # Stage all deletions

# 30. Review staged changes
git status

# 31. Commit changes
git commit -m "refactor: Convert S5 to thin client using slidefactory-core package

- Remove core application code (app/, cli/, alembic/, tests/)
- Create s5_branding/ with SportFive assets
- Create pyproject.toml with slidefactory-core==1.0.8 dependency
- Update Dockerfile to install core package
- Update scripts to use core package's CLI and app
- Archive migration documentation
- Update README for S5 client deployment

Core functionality now provided by slidefactory-core package.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

PHASE 9: VERIFICATION¶

# 32. Install S5 package in development mode
pip install -e ".[azure]"

# 33. Verify core package is installed
pip list | grep slidefactory

# 34. Verify CLI is available
which slidefactory
slidefactory --help

# 35. Test imports work
python -c "from slidefactory.app.main import app; print('✅ Core package imports successfully')"

# 36. Run a simple test
slidefactory init check

# 37. Build Docker image locally
docker build -t s5-slidefactory:test .

# 38. Test Docker container
docker run --rm s5-slidefactory:test slidefactory --version

PHASE 10: PUSH TO REMOTE¶

# 39. Push feature branch
git push origin feature/s5-client-cleanup

# 40. Create PR to preview branch (NOT main)
# Do this via GitHub UI or gh CLI:
gh pr create --base preview --title "Convert S5 to thin client using slidefactory-core" \
  --body "Completes repository separation by removing core code and using slidefactory-core package."

# After PR review and merge to preview:
# 41. Test preview deployment
# Monitor Azure Container Apps preview environment

# 42. If preview works, merge preview → main (repo owner only)
# This triggers production deployment

OPTIONAL: CLEANUP¶

# 43. After successful deployment, archive old branches
git branch -D backup-before-s5-cleanup-YYYYMMDD  # Delete local backup
# Keep remote backup for safety

Risk Assessment & Mitigation¶

Complexity Assessment¶

Complexity: Medium-high Risk Level: Medium

Reasons for Medium-High Complexity: 1. Major architectural change (monolith → package dependency) 2. Affects deployment pipeline and CI/CD 3. Changes import paths and startup scripts throughout 4. Requires coordination with Azure deployment configuration 5. Multiple file movements and deletions 6. Testing requires both local and Azure environments

Reasons for Medium Risk: 1. Core package is already tested and stable (v1.0.8) 2. Clear rollback strategy available (backup branch) 3. Preview environment allows testing before production 4. Non-destructive changes (backups created) 5. Similar pattern already working in core repo

Risk Mitigation Strategies¶

1. Backup Strategy - Create backup branch before any changes - Push backup to remote immediately - Keep backup for at least 30 days after successful deployment

2. Staged Rollout - Test in local development first - Deploy to preview environment - Monitor for 24-48 hours before production - Only merge to main after preview validation

3. Testing Strategy - Verify package installation locally - Test CLI commands work - Test Docker build completes - Test Docker container starts - Verify Azure deployment succeeds

4. Rollback Plan

# If something breaks:
git checkout preview
git reset --hard origin/preview  # Restore to last working state

# Or restore from backup branch:
git checkout backup-before-s5-cleanup-YYYYMMDD
git checkout -b preview-restored
git push origin preview-restored --force

Pre-deployment Checklist¶

Before executing this plan, verify:

Core package v1.0.8 is stable and tested in core repo
Core package is accessible (installed locally or via package registry)
S5 branding assets are identified and backed up
Azure secrets and credentials are documented
Preview environment is available for testing
Backup branch has been created and pushed to remote
Team has been notified of upcoming changes
Rollback procedure has been reviewed
Local development environment is ready for testing

Post-deployment Validation¶

After deployment, verify:

Preview deployment starts successfully
Web application is accessible at preview URL
CLI commands work in Azure environment
Database migrations run correctly
Static files (S5 branding) are served correctly
User authentication works
Presentation generation works
Worker processes start and process tasks
Logs show no import errors or package issues

Benefits Realized¶

For Core Maintainer¶

Single Source of Truth: One codebase for all core functionality
Version Control: Clients upgrade on their schedule
Clear Ownership: Core changes go to core repo only
Easier Testing: Test core once, all clients benefit
Documentation: Core docs separate from client docs
Reduced Duplication: No need to maintain multiple copies of core code

For S5 Deployment¶

Isolated Issues: S5-specific issues tracked separately
Custom Branding: Complete control over S5 look and feel
Independent Deployments: Deploy on S5's schedule
Stable Versions: Pin to tested core versions, upgrade when ready
Clear Support: Know where to report issues (core vs. S5)
Simplified Repository: Only deployment and branding code

Technical Benefits¶

Separation of Concerns: Core logic vs. deployment configuration
Testability: Core tests don't need Azure setup
Reusability: Easy to create new clients (Eddy, etc.)
Scalability: Core improvements benefit all clients automatically
Security: Client-specific secrets stay in client repos
Maintainability: Changes are localized and easier to reason about

Version Management Strategy¶

Core Package Updates¶

When core package releases a new version:

Core team creates new release in core repo:

cd ../slidefactory-core
# Update version in pyproject.toml and __init__.py
git tag v1.1.0
git push --tags

S5 team decides when to upgrade:

cd s5-slidefactory
# Edit pyproject.toml
# Change: slidefactory-core==1.0.8 → slidefactory-core==1.1.0
pip install -e ".[azure]" --force-reinstall
# Test locally, then deploy to preview
git commit -am "chore: upgrade slidefactory-core to v1.1.0"
git push

Version Pinning Policy¶

S5 pins exact versions of core package (e.g., ==1.0.8)
Prevents unexpected breakage from core updates
S5 controls upgrade timing
Allows testing before production deployment

Breaking Changes¶

Core package follows semantic versioning: - MAJOR (x.0.0): Breaking changes - S5 must review and test - MINOR (1.x.0): New features - S5 can upgrade with low risk - PATCH (1.0.x): Bug fixes - S5 should upgrade ASAP

Future Considerations¶

Adding More Clients¶

This pattern makes it easy to add new clients (e.g., Eddy):

# Create new client repo
mkdir eddy-slidefactory
cd eddy-slidefactory

# Create pyproject.toml with core dependency
cat > pyproject.toml << 'EOF'
[project]
name = "eddy-slidefactory"
dependencies = ["slidefactory-core==1.0.8"]
EOF

# Create branding directory
mkdir -p eddy_branding/static/img

# Done! Client is ready

Core Package Distribution¶

Current: Local installation from ../slidefactory-core

Future options: 1. GitHub Packages: Private package registry 2. PyPI: Public package (if open-sourced) 3. Self-hosted PyPI: Internal package server

Documentation Strategy¶

Core docs: In core repo, published via MkDocs
S5 docs: In S5 repo, deployment-specific
Eddy docs: In Eddy repo, deployment-specific

Troubleshooting Guide¶

Issue: Package not found during installation¶

# Solution: Install from local path
pip install -e ../slidefactory-core

# Or if using package registry:
pip install slidefactory-core==1.0.8 --index-url <registry-url>

Issue: Import errors after cleanup¶

# Check if core package is installed
pip list | grep slidefactory

# Reinstall if needed
pip install -e ".[azure]" --force-reinstall

Issue: Static files (branding) not found¶

# Verify symlink in Dockerfile
ls -la /code/static/s5_branding

# Check mount point in docker-compose
docker-compose -f docker-compose.s5.yml config | grep volumes

Issue: CLI commands not working¶

# Check which slidefactory is being used
which slidefactory

# Should point to core package's CLI, not local script
# /path/to/.venv/bin/slidefactory (correct)
# ./slidefactory (incorrect - old script)

Issue: Database migrations fail¶

# Migrations are in core package now
# Check alembic can find migrations
alembic current

# If issues, verify DATABASE_URL is set
echo $DATABASE_URL

Success Criteria¶

This migration is considered successful when:

✅ S5 repo contains only branding, config, and deployment files
✅ Core package (v1.0.8) is installed and importable
✅ slidefactory CLI command works and uses core package
✅ Local development works with ./start.sh
✅ Docker build completes successfully
✅ Docker container starts and serves application
✅ Preview deployment to Azure succeeds
✅ S5 branding appears correctly in deployed application
✅ All core functionality (presentations, users, API keys) works
✅ No import errors or package-related errors in logs

Timeline Estimate¶

Estimated Effort: - Backup and preparation: 30 minutes - Create S5 branding structure: 1 hour - Update configuration files: 1-2 hours - Update scripts and Dockerfile: 1 hour - Remove core code: 30 minutes - Testing and verification: 2-3 hours - Deployment to preview: 1 hour - Monitoring and validation: 24-48 hours

Total active work: 1 day Total including monitoring: 2-3 days

Note: These are effort estimates, not timelines. Actual calendar time will depend on team availability and deployment windows.

Conclusion¶

This cleanup plan completes the repository separation strategy by converting S5 from a monolithic repository to a thin client that depends on the slidefactory-core package. The benefits include:

Clear separation of concerns
Easier maintenance
Version control and stability
Reusable core across multiple clients
Reduced code duplication

The plan is structured as a series of incremental, reversible steps with clear verification points. The medium risk level is appropriate given the architectural significance, but is mitigated by comprehensive backup, testing, and rollback strategies.

Recommendation: Proceed with implementation following the phased approach outlined above, with careful validation at each step.

Appendix A: File Inventory¶

Files Removed (Core Code)¶

app/ (18 subdirectories, ~200 files)
cli/ (5 files)
alembic/ (4 directories, ~30 files)
static/ (4 subdirectories, ~50 files)
templates/ (14 subdirectories, ~40 files)
tests/ (11 subdirectories, ~80 files)
Supporting files: ~20 files

Total removal: ~420 files

Files Created (S5 Client)¶

s5_branding/ (3 subdirectories)
pyproject.toml
.env.s5
Updated: Dockerfile, docker-compose.s5.yml, README.md
Updated scripts: 3 files
New documentation: This report

Total additions: ~15 files + branding assets

Net Change¶

Before: ~500 files (monolith)
After: ~80 files (thin client)
Reduction: ~85% fewer files in S5 repo

These documents have been archived to docs/archive/migration/ as they pertain to the migration process rather than ongoing S5 operations.

Document Status: Ready for Review Next Steps: Review plan with team, obtain approval, execute Phase 1 (backup) Questions/Issues: Contact maintainer or create issue in S5 repository