Deck Architect Architecture

Status: v2 production, v3 experimental

Version History

v1 (Retired)

python-pptx based, programmatic slide generation
Quality: poor — retired and removed from git

v2 (Production) — pptxgenjs Engine

Engine: Node.js pptxgenjs (JavaScript)
Architecture: LLM generates full JavaScript code per slide batch
Quality: Production-grade
Speed: ~200s for 11 slides
Cost: ~$0.60 per deck

Key Components

File	Purpose
orchestrator.py	Pipeline: plan, generate, QA, export
code_generator.py	Feeds design system + prompt to LLM, gets JS back
visual_qa.py	Screenshot slides, LLM scores each (threshold: 8.0)
design-system.mjs	9 golden layout patterns + helper functions
generator-system.md	Layout rules, design constraints

Layout Patterns

Anchor Left — key stat left, supporting content right
Split Contrast — two-panel comparison
Card Grid — 2x2 or 3-column cards
Stat Spotlight — large number with context
Three Columns — parallel content streams
Table — structured data display
Hero Statement — opening slide with title
Timeline Rail — chronological progression
Closing — call-to-action with contact info

v3 (Experimental) — Template Engine

Engine: Python python-pptx with pre-built .pptx templates
Architecture: LLM outputs structured JSON content only (never layout code)
Speed: 66-76s (2.6x faster than v2)
Cost: ~$0.15 (4x cheaper than v2)
Quality: 5-6/10 (needs template refinement)

Template Slide Types (11)

hero, section_break, anchor_left, split_contrast, stat_spotlight, three_columns, card_grid_2x2, table_slide, timeline, closing, blank_content

Usage

# v2 (recommended for quality)
python3.12 -m agents.deck_architect_v2 "Brief or topic description" --palette midnight_navy

# v3 (recommended for speed/cost)
python3.12 -m agents.deck_architect_v3 "Brief or topic description"

Design System

A curated design skill provides:

Design intent first, layout variety, 4-tier visual hierarchy
10 curated color palettes for different content types
McKinsey-style takeaway titles
Reference deck for quality benchmarking