Fractafrag

Meta	Value
Repo	`xpltdco/fractafrag`
Page	`Home`
Audience	developers, agents, newcomers
Last Updated	2026-04-04
Status	current

What is Fractafrag?

Fractafrag is a self-hosted GLSL shader platform that combines a TikTok-style adaptive feed, a Shadertoy-compatible code editor, AI generation capabilities, and a community-driven desire/bounty board. Users can create, share, discover, and remix WebGL2 fragment shaders — all running on your own infrastructure with zero cloud dependencies for core functionality.

Current Status

Actively developed. Milestone 0 (M0) — infrastructure, auth, and core CRUD — is in progress. The Docker Compose stack, database schema, authentication system, and basic shader endpoints are functional. Several features (payments, AI generation, full rendering pipeline) are stubbed for future milestones.

Key URLs

Resource	URL
Application	`https://fractafrag.xpltd.co`
Repository (public)	`https://git.xpltd.co/xpltdco/fractafrag`
Repository (private mirror)	`https://git.xpltd.co/meshonl/fractafrag`
API Docs (Swagger)	`https://fractafrag.xpltd.co/api/docs`
API Docs (ReDoc)	`https://fractafrag.xpltd.co/api/redoc`

Core Features

Shader Editor — In-browser GLSL editor with live WebGL2 preview (Shadertoy-compatible uniforms)
Adaptive Feed — Personalized discovery using tag affinity, engagement signals, and Wilson-score trending
Versioning — Immutable shader version snapshots with restore capability
Desire Board — Community bounty system where users post shader requests, others fulfill them
MCP Server — AI agents (Claude, GPT) can browse, create, and update shaders programmatically
Headless Rendering — Server-side shader rendering via Puppeteer/Chromium for thumbnails and previews
Creator Economy — Verified creators, source unlocks, commercial licenses, Stripe Connect (schema-ready)
BYOK AI — Bring Your Own Key for Anthropic, OpenAI, or Ollama-based shader generation

Tech Stack

Component	Technology
API	Python 3.12, FastAPI, SQLAlchemy 2 (async)
Frontend	React 18, Vite, Three.js, TanStack Query, Zustand, Tailwind CSS
Database	PostgreSQL 16 + pgvector (similarity search)
Cache/Queue	Redis 7 (Celery broker, token blocklist, rate limiting)
Worker	Celery (async job processing)
Renderer	Node.js + Puppeteer Core + Chromium (headless shader rendering)
MCP Server	Python FastMCP (AI agent interface via HTTP+SSE)
Proxy	nginx (reverse proxy, static file serving)
Deployment	Docker Compose (8 services)

Wiki Pages

Page	Description
Architecture	System design, service topology, data flow, design decisions
Getting Started	Local dev setup, prerequisites, Docker Compose
Data Model	PostgreSQL schema, ORM models, pgvector indexes
API Reference	Complete REST endpoint inventory
Deployment	Docker setup, volumes, nginx, health checks
Configuration	All environment variables and settings
Development Guide	Code patterns, testing, CI/CD
Agent Context	Structured metadata for LLM agents

Milestones

Milestone	Focus	Status
M0	Infrastructure + Auth	In Progress
M1	Core Shader Loop (editor, submit, feed)	Planned
M2	Intelligence Layer (MCP, recommendations)	Planned
M3	Desire Economy (bounties, fulfillment)	Planned
M4	Monetization (Stripe, subscriptions)	Planned
M5	AI Generation (prompt → shader)	Planned

Glossary

Term	Definition
Shader	A GLSL fragment shader program that runs on the GPU to generate visual output
GLSL	OpenGL Shading Language — the programming language for GPU shaders
Fragment shader	A shader that computes the color of each pixel
Desire	A community bounty request — a user describes a shader they want and others can fulfill it
Heat score	Demand indicator for desires — increases when similar desires are posted (cluster size)
Format profile	Not applicable here (tubearr term)
pgvector	PostgreSQL extension for vector similarity search using HNSW indexes
BYOK	Bring Your Own Key — users provide their own API keys for AI providers
MCP	Model Context Protocol — standardized interface for AI agents to interact with tools
Wilson score	Statistical method for ranking shaders, accounting for both vote count and ratio

Infrastructure Context

For newcomers to the xpltd infrastructure:

ub01 (10.0.0.10) — Primary server running all Docker Compose services
nginx01 (10.0.0.9) — Reverse proxy handling TLS termination for *.xpltd.co
AdGuard Home — Internal DNS rewriting *.xpltd.co to nginx01
Cloudflare — External DNS with CNAME to dyndns.xpltd.co

Mirror Note

The primary development repository is meshonl/fractafrag (private, mirrors the GitHub origin). The xpltdco/fractafrag fork is the public-facing copy on this Forgejo instance. Both contain the same code.