Repository Separation - Quick Reference¶

Date: 2025-11-18 Full Guide: 2025-11-18_repository_separation_implementation_guide.md

Architecture Overview¶

┌─────────────────────────────────────────────┐
│         slidefactory-core (Package)         │
│                                             │
│  • Core FastAPI application                 │
│  • AI providers (OpenAI, Azure, etc.)       │
│  • Workflow engines (N8N, Prefect, etc.)    │
│  • Document processing & vector search      │
│  • Storage abstraction (MinIO, Azure)       │
│  • Database models & migrations             │
│  • CLI tool                                 │
│                                             │
│  Published to: GitHub Packages              │
│  Version: Semantic (v1.0.0, v1.1.0, etc.)   │
└─────────────────────────────────────────────┘
                    ▲         ▲
                    │         │
                    │         │
        pip install │         │ pip install
                    │         │
    ┌───────────────┴─┐   ┌───┴─────────────────┐
    │                 │   │                     │
    │  s5-slidefactory│   │  eddy-slidefactory  │
    │                 │   │                     │
    │  • S5 branding  │   │  • Eddy branding    │
    │  • Azure deploy │   │  • Docker deploy    │
    │  • S5 config    │   │  • Coolify config   │
    │  • S5 issues    │   │  • Eddy issues      │
    └─────────────────┘   └─────────────────────┘

File Distribution¶

Core Package (`slidefactory-core`)¶

src/slidefactory/
├── app/                   # All FastAPI routes, models, logic
├── cli/                   # CLI commands
├── alembic/               # Database migrations
├── templates/             # Generic Jinja2 templates
└── __init__.py

static/                    # Generic assets ONLY
├── css/
├── js/
├── vendor/
└── img/
    ├── logo.png           # Generic Slidefactory logo
    └── favicon.ico

packages/
└── n8n-nodes-slidefactory/

tests/                     # Core tests
requirements.txt           # Core dependencies
pyproject.toml             # Package configuration
Dockerfile.base            # Base image for clients

What's NOT in core: - ❌ Client-specific branding (SportFive, Eddy logos) - ❌ Deployment configs (Azure, Coolify) - ❌ Environment templates with client URLs - ❌ Client-specific documentation

S5 Client (`s5-slidefactory`)¶

s5_branding/
├── static/
│   ├── img/
│   │   ├── sportfive_logo.png
│   │   ├── sportfive_large.png
│   │   └── login_hero.png
│   └── css/
│       └── s5-custom.css
└── templates/             # S5-specific overrides (if needed)

.env.s5                    # S5 configuration
.github/workflows/
├── preview.yml            # Azure preview deployment
└── production.yml         # Azure production deployment

scripts/
├── start-web-azure.sh
└── deploy-azure.sh

pyproject.toml             # dependencies = ["slidefactory-core==1.0.0"]
Dockerfile                 # FROM ghcr.io/org/slidefactory-core:1.0.0
docker-compose.s5.yml      # Local development
README.md                  # S5-specific docs

Eddy Client (`eddy-slidefactory`)¶

eddy_branding/
├── static/
│   ├── img/
│   │   ├── eddy_logo.png
│   │   └── eddy_large.png
│   └── css/
│       └── eddy-custom.css
└── templates/             # Eddy-specific overrides (if needed)

.env.eddy                  # Eddy configuration
docker-compose.yml         # Coolify deployment

scripts/
├── start-web-docker.sh
└── start-worker-docker.sh

pyproject.toml             # dependencies = ["slidefactory-core==1.0.0"]
Dockerfile                 # FROM ghcr.io/org/slidefactory-core:1.0.0
README.md                  # Eddy-specific docs

Configuration Pattern¶

Core Provides Defaults¶

# src/slidefactory/app/config.py
class Config:
    CLIENT_NAME: str = os.getenv("CLIENT_NAME", "Slidefactory")
    CLIENT_LOGO: str = os.getenv("CLIENT_LOGO", "/static/img/logo.png")
    CLIENT_PRIMARY_COLOR: str = os.getenv("CLIENT_PRIMARY_COLOR", "#007bff")

Clients Override via Environment¶

S5 (.env.s5):

CLIENT_NAME="SportFive Slidefactory"
CLIENT_LOGO="/s5_branding/static/img/sportfive_logo.png"
CLIENT_PRIMARY_COLOR="#ee0000"
STORAGE_PROVIDER="azure"
DEPLOYMENT_PLATFORM="azure"

Eddy (.env.eddy):

CLIENT_NAME="Eddy Slidefactory"
CLIENT_LOGO="/eddy_branding/static/img/eddy_logo.png"
CLIENT_PRIMARY_COLOR="#0066cc"
STORAGE_PROVIDER="minio"
DEPLOYMENT_PLATFORM="docker"

Version Management¶

Release Core¶

# In slidefactory-core
git tag v1.1.0
git push --tags
# GitHub Actions publishes to GitHub Packages automatically

Update Client¶

# In s5-slidefactory or eddy-slidefactory
# Edit pyproject.toml
dependencies = [
    "slidefactory-core==1.1.0",  # Update version here
]

pip install -e . --force-reinstall
# Test locally

git commit -am "chore: upgrade slidefactory-core to v1.1.0"
git push

Installation Commands¶

Core Package (for local development)¶

# From GitHub Packages
pip install slidefactory-core==1.0.0 \
  --index-url https://${GITHUB_TOKEN}@github.com/pypi/YOUR_ORG/simple/

# From source
git clone https://github.com/YOUR_ORG/slidefactory-core.git
cd slidefactory-core
pip install -e ".[dev]"

S5 Client¶

git clone https://github.com/YOUR_ORG/s5-slidefactory.git
cd s5-slidefactory
pip install -e ".[azure]"  # Installs core + Azure dependencies

Eddy Client¶

git clone https://github.com/YOUR_ORG/eddy-slidefactory.git
cd eddy-slidefactory
pip install -e ".[minio]"  # Installs core + MinIO dependencies

Deployment Comparison¶

Aspect	S5	Eddy
Platform	Azure Container Apps	Docker Compose (Coolify)
Storage	Azure Blob Storage	MinIO
Database	Azure PostgreSQL	Dockerized PostgreSQL
Redis	Azure Redis Cache	Dockerized Redis
Auth	Azure AD / Entra ID	Local (database)
CI/CD	GitHub Actions → Azure	Coolify auto-deploy
Scaling	Auto-scaling (Azure)	Manual (Docker resources)
SSL	Azure-managed	Coolify-managed

CLI Commands¶

Core package includes CLI tool:

# Initialize system
slidefactory init all

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

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

# Templates
slidefactory template list --workflow-folder esg
slidefactory template upload template.pptx --workflow-folder esg

# Presentations
slidefactory presentation generate --template-id 123 --data-file data.json
slidefactory presentation status <process-id>
slidefactory presentation download <process-id>

Testing Strategy¶

Core Tests¶

cd slidefactory-core
pytest tests/ -v

# By category
pytest -m unit          # Fast, no external dependencies
pytest -m integration   # Requires services
pytest -m api           # API endpoint tests

Client Tests¶

cd s5-slidefactory
pytest tests/ -v        # S5-specific integration tests

cd eddy-slidefactory
pytest tests/ -v        # Eddy-specific integration tests

Migration Timeline¶

Week	Phase	Tasks
1	Core Package	Create repo, restructure code, publish v1.0.0
2	S5 Client	Create repo, migrate branding, test Azure deploy
3	Eddy Client	Create repo, setup branding, test Docker deploy
4	Validation	Full integration tests, documentation

Total Effort: 1-2 weeks

Key Decision Points¶

✅ Decided¶

Distribution: GitHub Packages (private)
Versioning: Semantic versioning
License: Private for now, core may become MIT
Breaking Changes: Direct communication with clients
Version Pinning: Clients pin to specific versions

❓ To Decide¶

GitHub organization name?
Exact repository names?
Who needs access to each repo?
Start at v1.0.0 or v0.1.0?
Migration start date?

Common Commands Quick Reference¶

Publishing Core Update¶

cd slidefactory-core
# Update version in pyproject.toml and src/slidefactory/__init__.py
git commit -am "chore: bump version to 1.1.0"
git tag v1.1.0
git push && git push --tags

Upgrading Client¶

cd s5-slidefactory  # or eddy-slidefactory
# Edit pyproject.toml: slidefactory-core==1.1.0
pip install -e . --force-reinstall
# Test locally
docker-compose up  # or deploy to preview
git commit -am "chore: upgrade core to 1.1.0"
git push

Rolling Back¶

cd s5-slidefactory
# Edit pyproject.toml: slidefactory-core==1.0.0  (previous version)
pip install -e . --force-reinstall
git commit -am "fix: rollback core to 1.0.0"
git push

Support & Issues¶

Issue Type	Where to Report
Core bugs, feature requests	`slidefactory-core` issues
S5-specific issues	`s5-slidefactory` issues
Eddy-specific issues	`eddy-slidefactory` issues
Azure deployment problems	`s5-slidefactory` issues
Docker/Coolify problems	`eddy-slidefactory` issues

Benefits Summary¶

For Core Maintainer (You)¶

✅ Single source of truth ✅ Version control over releases ✅ Clear separation of concerns ✅ Easier testing and debugging

For Clients (S5, Eddy)¶

✅ Own issue tracker ✅ Custom branding ✅ Independent deployment schedule ✅ Version stability

Technical¶

✅ Reusable core ✅ Easy to add new clients ✅ Clear upgrade path ✅ Isolated testing

Full Implementation Guide: See 2025-11-18_repository_separation_implementation_guide.md for detailed step-by-step instructions.