PosterBoy — Autonomous Design Director

A local-first autonomous design system powered by Gemini 2.5 Flash. Upload any image, describe your intent, and watch a 7-agent pipeline plan, compose, critique, and self-correct a production-ready poster layout — without touching a single CSS property.

---

Architecture

Image → Vision Agent → Creative Director → Copywriter → Typography → Layout → [Critique Loop] → Canvas

Agent	Role
Agent 1 – Vision	Segments image into face / product / empty / logo-safe regions
Agent 2 – Creative Director	Generates 3 concepts (Luxury / Editorial / Commercial), scores and selects winner
Agent 3 – Copywriter	Writes headline (≤10 words), subheadline, CTA, and supporting copy
Agent 4 – Typography	Pairs display + body fonts, sets size/tracking/weight tokens
Agent 5 – Layout	Plans absolute coordinate positions (0–100%) using Design Memory patterns
Agent 6 – Critic	Screenshots the render, scores it (0–100), lists violations
Agent 7 – Repair	Adjusts coordinates based on critic feedback (max 3 loops)

A Python geometry helper (src/lib/python/geometry_helper.py) handles exact bounding-box overlap math — face collisions, product occlusions, margin breaches — independently of TypeScript.

Design rules live in the Design Constitution (design_rules.md) and are version-controlled in SQLite. Edit them in the UI; every subsequent generation respects the new rules immediately.

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, TypeScript)
AI	@google/genai — Gemini 2.5 Flash
Database	SQLite via better-sqlite3
State	Zustand
Styling	Tailwind CSS v4
Canvas Export	html-to-image
Geometry	Python 3 (geometry_helper.py)

---

Getting Started

# 1. Install dependencies
npm install
# 2. Add your Gemini API key
cp .env.example .env
# Edit .env and set GEMINI_API_KEY=your_key_here# 3. Start the dev server
npm run dev

Open http://localhost:3000.

---

Key Design Decisions

• Coordinates, not CSS — Gemini generates JSON {x, y, width, height} percentages. The React canvas maps these to absolute positions. No hallucinated inline styles.
• Self-correcting, not self-evolving — Agents critique outputs and fix coordinates. Core code is never rewritten.
• Design Memory — Successful layouts (score ≥ 90) are stored in SQLite and fed back as few-shot examples to the Layout Agent.
• Python delegation — Geometry math (overlap, margins, IoU) runs in Python for precision. See decision_log.md for full rationale.

---

Project Structure

src/
├── app/
│ ├── api/
│ │ ├── generate/ # POST: run all 5 generation agents
│ │ ├── critique/ # POST: run critique + repair loop
│ │ ├── constitution/ # GET/POST: manage design rules
│ │ ├── fonts/ # GET/POST: font registry
│ │ └── layouts/ # GET/POST: layout memory + job history
│ ├── globals.css
│ ├── layout.tsx
│ └── page.tsx # Main dashboard
├── components/
│ ├── Canvas.tsx # Drag/resize/edit canvas editor
│ ├── ControlPanel.tsx # Upload, prompt, font, export sidebar
│ ├── CritiquePanel.tsx # Score gauge + issue list
│ ├── Telemetry.tsx # Live agent execution log
│ └── ConstitutionEditor.tsx
├── lib/
│ ├── agents/
│ │ ├── gemini.ts # Shared Gemini client + callAgent()
│ │ ├── visionAgent.ts
│ │ ├── creativeDirectorAgent.ts
│ │ ├── copywriterAgent.ts
│ │ ├── typographyAgent.ts
│ │ ├── layoutAgent.ts
│ │ ├── criticAgent.ts
│ │ ├── repairAgent.ts
│ │ └── orchestrator.ts # Pipeline controller
│ ├── python/
│ │ └── geometry_helper.py
│ ├── db.ts # SQLite schema + seeding
│ ├── pythonRunner.ts # Node → Python bridge
│ └── store.ts # Zustand global state
└── types/
└── agents.ts # Shared TypeScript contracts