Skip to content

Development Guide

Setup

git clone https://github.com/cgast/slidefactory-core.git
cd slidefactory-core

# Backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Database
createdb slidefactory
psql slidefactory -c "CREATE EXTENSION IF NOT EXISTS vector;"
slidefactory init database

# Frontend
cd frontend && npm install

Create .env — see Configuration for all variables.

Running Locally

# Option 1: Full stack via script
./dev-start.sh

# Option 2: Manual (3 terminals)
uvicorn slidefactory.app.main:app --reload --port 8080        # backend
celery -A slidefactory.app.celery_app worker -Q process_queue  # worker
cd frontend && npm run dev                                      # frontend (:5173)

The Vite dev server proxies /api to FastAPI on :8080. Set CORS_ENABLED=true in .env.

Code Style

Tool Purpose Command
Black Formatting black src/ tests/
isort Import sorting isort src/ tests/
flake8 Linting flake8 src/ tests/
mypy Type checking mypy src/slidefactory

Testing

pytest                           # all tests
pytest -m unit                   # unit tests only
pytest -m integration            # integration tests (require services)
pytest -m api                    # API endpoint tests
pytest -m cli                    # CLI tests
pytest --cov=src/slidefactory    # with coverage report
pytest -n auto                   # parallel execution

Test structure:

tests/
├── unit/           # fast, isolated, mocked dependencies
├── integration/    # require PostgreSQL, Redis, MinIO
├── api/            # FastAPI TestClient endpoint tests
├── cli/            # CLI command tests
└── e2e/            # end-to-end workflow tests

Markers: @pytest.mark.unit, @pytest.mark.integration, @pytest.mark.api, @pytest.mark.cli, @pytest.mark.e2e

Frontend Development

cd frontend
npm run dev              # dev server with HMR
npm run build            # production build → dist/
npm run type-check       # TypeScript check
npm run generate-api     # regenerate API types from OpenAPI schema

Stack: Vue 3 (Composition API), TypeScript, Vite 5, Pinia, Vue Router 4

Key directories:

  • src/pages/ — page components (Dashboard, Presentations, Templates, Workflows, Collections, Settings)
  • src/stores/ — Pinia stores (auth, ui)
  • src/api/ — typed API client
  • src/components/ — reusable components (admin, collections, common, layout, templates, viewers, workflows)
  • src/i18n/ — internationalization (en, de, fr, it, nl)

Database Migrations

# Auto-generate migration from model changes
cd src/slidefactory && alembic revision --autogenerate -m "description"

# Apply migrations
slidefactory init database    # or: alembic upgrade head

Migrations live in src/slidefactory/alembic/versions/.

Branch Strategy

  • main — production-ready
  • feature/* — new features
  • bugfix/* — bug fixes
  • hotfix/* — urgent fixes from tag

Commit Conventions

Conventional Commits: type(scope): subject

Types: feat, fix, docs, style, refactor, test, chore

git commit -m "feat(ai): add Anthropic Claude support"
git commit -m "fix(storage): handle missing bucket error"

Adding New Components

AI Provider: Create src/slidefactory/app/ai/providers/my_provider.py, implement BaseAIProvider, add tests.

Storage Backend: Create src/slidefactory/app/filemanager/storage/my_storage.py, implement StorageClient, update StorageClientFactory.

Workflow Engine: Create src/slidefactory/app/workflowengine/engines/my_engine.py, implement BaseWorkflowEngine, register in registry.py.

Releases

Semantic versioning (MAJOR.MINOR.PATCH). Version lives in src/slidefactory/__init__.py.

# Update version, commit, tag, push, create GitHub release
# Use the /release or /bump-version CLI skill for automation

CI/CD

  • Tests: GitHub Actions on push/PR — runs pytest with PostgreSQL + Redis services
  • Docs: Auto-deploy to GitHub Pages on push to main
  • Release: Build wheel + source dist, attach to GitHub release