Self-hosted GLSL shader platform
c4b8c0fe38
Track B — Auth & User System (complete): - User registration with bcrypt + Turnstile verification - JWT access/refresh token flow with httpOnly cookie rotation - Redis refresh token blocklist for logout - User profile + settings update endpoints (username, email) - API key generation with bcrypt hashing (ff_key_ prefix) - BYOK key management with AES-256-GCM encryption at rest - Free tier rate limiting (5 shaders/month) - Tier-gated endpoints (Pro/Studio for BYOK, API keys, bounty posting) Track C — Shader Submission & Renderer (complete): - GLSL validator: entry point check, banned extensions, infinite loop detection, brace balancing, loop bound warnings, code length limits - Puppeteer/headless Chromium renderer with Shadertoy-compatible uniform injection (iTime, iResolution, iMouse), WebGL2 with SwiftShader fallback - Shader compilation error detection via page title signaling - Thumbnail capture at t=1s, preview frame at t=duration - Renderer client service for API→renderer HTTP communication - Shader submission pipeline: validate GLSL → create record → enqueue render job - Desire fulfillment linking on shader submit - Re-validation and re-render on shader code update - Fork endpoint copies code, tags, metadata, enqueues new render Track D — Frontend Shell (complete): - React 18 + Vite + TypeScript + Tailwind CSS + TanStack Query + Zustand - Dark theme with custom fracta color palette and surface tones - Responsive layout with sticky navbar, gradient branding - Auth: Login + Register pages with JWT token management - API client with automatic 401 refresh interceptor - ShaderCanvas: Full WebGL2 renderer component with Shadertoy uniforms, mouse tracking, ResizeObserver, debounced recompilation, error callbacks - GLSL Editor: Split pane (code textarea + live preview), 400ms debounced preview, metadata panel (description, tags, type), GLSL validation errors, shader publish flow, fork-from-existing support - Feed: Infinite scroll with IntersectionObserver sentinel, dwell time tracking, skeleton loading states, empty state with CTA - Explore: Search + tag filter + sort tabs (trending/new/top), grid layout - ShaderDetail: Full-screen preview, vote controls, view source toggle, fork button - Bounties: Desire queue list sorted by heat score, status badges, tip display - BountyDetail: Single desire view with style hints, fulfill CTA - Profile: User header with avatar initial, shader grid - Settings: Account info, API key management (create/revoke/copy), subscription tiers - Generate: AI generation UI stub with prompt input, style controls, example prompts 76 files, ~5,700 lines of application code. |
||
|---|---|---|
| .bg-shell | ||
| db | ||
| scripts | ||
| services | ||
| .env.example | ||
| .gitignore | ||
| DECISIONS.md | ||
| docker-compose.override.yml | ||
| docker-compose.yml | ||
| FRACTAFRAG FULL SPEC & SUMMARY.md | ||
| README.md | ||
🔥 Fractafrag
A self-hosted GLSL shader platform — browse, create, generate, and share real-time GPU visuals.
Fractafrag fuses three experiences:
- TikTok-style adaptive feed of living, animated shaders that learns your taste
- Shadertoy-style code editor for writing, forking, and publishing GLSL shaders
- AI generation layer where you describe what you want and the platform writes the shader
Plus a desire queue / bounty board where users express what they want to see, and human creators or AI agents fulfill those requests.
Quick Start
# 1. Clone and configure
cp .env.example .env
# Edit .env with your secrets
# 2. Launch everything
docker compose up -d
# 3. Open
open http://localhost
Architecture
nginx (reverse proxy)
├── / → React frontend (Vite)
├── /api/* → FastAPI backend
└── /mcp/* → MCP server (AI agent interface)
postgres (pgvector/pgvector:pg16) — primary datastore + vector similarity
redis (redis:7-alpine) — cache, rate limiting, job queue
renderer — headless Chromium shader renderer
worker — Celery job processor (render, embed, AI generate)
Tech Stack
| Layer | Tech |
|---|---|
| Frontend | React 18, Vite, Three.js, TanStack Query, Zustand, Tailwind CSS |
| Backend | Python, FastAPI, SQLAlchemy, Pydantic |
| Database | PostgreSQL 16 + pgvector, Redis 7 |
| Jobs | Celery + Redis |
| Renderer | Node.js + Puppeteer (Headless Chromium) |
| MCP | Python MCP SDK, HTTP+SSE transport |
| Payments | Stripe (subscriptions + Connect) |
| Container | Docker Compose, single-stack |
Milestone Roadmap
| Milestone | Focus | Status |
|---|---|---|
| M0 | Infrastructure + Auth | 🚧 In Progress |
| M1 | Core Shader Loop (editor, submit, feed) | ⏳ |
| M2 | Intelligence Layer (MCP, recommendations) | ⏳ |
| M3 | Desire Economy (bounties, fulfillment) | ⏳ |
| M4 | Monetization (Stripe, subscriptions) | ⏳ |
| M5 | AI Generation (prompt → shader) | ⏳ |
Development
# API direct access (dev mode)
http://localhost:8000/api/docs # Swagger UI
http://localhost:8000/health # Health check
# Services
http://localhost:5173 # Vite dev server
http://localhost:3200 # MCP server
http://localhost:3100 # Renderer
License
Private — see DECISIONS.md for project governance.