deckforge: Instructions file for Claude Code

DeckForge

API-first presentation generation platform. 32 slide types, 24 chart types, 15 themes, native PPTX + Google Slides output, AI content generation, finance vertical with 9 specialized slide types.

Tech Stack

• API: Python 3.12, FastAPI, Pydantic v2, uvicorn
• Database: PostgreSQL (prod) / SQLite (dev), SQLAlchemy 2.0 (async), Alembic migrations
• Queue: Redis + ARQ (async workers for content generation and rendering)
• Storage: MinIO (dev) / Cloudflare R2 (prod), S3-compatible via boto3
• Rendering: python-pptx (PPTX), google-api-python-client (Google Slides), Plotly + Kaleido (static chart PNGs)
• SDK: TypeScript, tsup build, vitest tests (in sdk/ directory)
• Billing: Stripe (subscriptions, 3 tiers), x402 (USDC per-call for AI agents on Base L2)
• Auth: Unkey (prod) / DB-based SHA-256 key hashing (dev), API key prefixes dk_test_ / dk_live_
• Layout: kiwisolver constraint solver, 12-column grid, Pillow text measurement
• Themes: 15 YAML definitions in src/deckforge/themes/data/
• Content: Model-agnostic LLM orchestration (Claude, OpenAI, Gemini, Ollama) with 4-stage pipeline
• MCP: FastMCP server with 6 tools for AI agent integration

Project Structure

src/deckforge/
  config.py       # Pydantic Settings, DECKFORGE_ env prefix, all config fields
  main.py         # App entrypoint, lifespan, uvicorn runner
  ir/             # Pydantic IR models
    slides/       # 32 slide types (23 universal + 9 finance), discriminated on slide_type
    elements/     # Element types (title, text, metric, chart, image, table, etc.)
    charts/       # 24 chart types, discriminated on chart_type
  api/            # FastAPI routes + middleware
    routes/       # 15 route modules: render, generate, health, billing, onboarding, etc.
    middleware/    # Auth (Unkey/DB), rate limiting (Redis token bucket), credit check, x402
  db/             # Database layer
    base.py       # SQLAlchemy Base with naming conventions
    engine.py     # Async engine, session factory, get_db() dependency
    models/       # 8 models: User, ApiKey, Job, Deck, BatchJob, UsageRecord, PaymentEvent, WebhookRegistration
    repositories/ # Repository pattern, singleton instances, session-as-argument
  rendering/      # Output renderers
    pptx/         # PPTX renderer with ELEMENT_RENDERERS registry, transitions, Open XML
    gslides/      # Google Slides renderer with ELEMENT_BUILDERS dispatch, batchUpdate
    charts/       # Static chart renderers (Plotly -> PNG at 300 DPI), 24 chart types
    thumbnails/   # 3-tier fallback: LibreOffice -> pdf2image -> Pillow placeholder
  layout/         # Constraint-based layout
    solver.py     # kiwisolver constraint system
    grid.py       # 12-column grid
    patterns/     # PATTERN_REGISTRY: 9 layout patterns + GenericPattern fallback
    overflow.py   # Adaptive: font reduce (2pt steps) -> reflow -> slide split
  themes/         # Theme system
    data/         # 15 YAML themes (arctic-clean, corporate-blue, finance-pro, etc.)
    resolver.py   # 3-tier resolution: colors -> palette -> slide_masters
    brand_kit.py  # BrandKitMerger (protected keys: spacing, typography.scale)
  content/        # NL-to-IR pipeline
    pipeline.py   # 4-stage: intent -> outline -> expand -> refine
    intent.py     # Prompt classification
    outline.py    # Slide structure planning
    expand.py     # Content generation per slide
    refine.py     # QA and polish
  llm/            # LLM provider adapters
    router.py     # Provider selection + fallback chain
    adapters/     # Claude (tool_use), OpenAI (json_schema), Gemini (response_schema), Ollama (retry)
  charts/         # Chart recommender (data analysis -> chart type suggestion)
  finance/        # Financial formatting, conditional formatting, data ingestion
  qa/             # 5-pass QA pipeline, auto-fix engine (contrast, overflow, alignment), scorer
  billing/        # Stripe client, credit reservation/deduction, tier definitions, x402 config
  services/       # Business logic: DeckOperations, SlideTypeRegistry, CostEstimator
  workers/        # ARQ workers: ContentWorkerSettings, RenderWorkerSettings, task definitions
  mcp/            # MCP server: 6 tools (render, generate, themes, slide_types, estimate, preview)

sdk/              # TypeScript SDK (@deckforge/sdk)
  src/            # Immutable builder pattern, SSE streaming, full type coverage (32 slide + 24 chart types)
demos/            # 5 demo deck IRs (mckinsey-strategy, pe-deal-memo, startup-pitch, board-update, product-launch)
alembic/          # Database migrations (5 migrations)
scripts/          # bootstrap-db.sh (migrations + seed data)