Self-hosted GLSL shader platform

Find a file

John Lightner a5f0c0e093 Bootstrap GSD structure for M001-M003 GSD artifacts: - .gsd/PROJECT.md — full project state, architecture, milestone sequence - .gsd/REQUIREMENTS.md — 16 requirements (10 active, 3 validated, 3 deferred, 2 out-of-scope) - .gsd/DECISIONS.md — 18 decisions migrated from project root + new M1/M2 decisions - .gsd/STATE.md — active milestone M001, phase: planning - .gsd/DISCUSSION-MANIFEST.json — all 3 gates completed Milestone contexts: - M001-CONTEXT.md — Desire Economy: embedding, clustering, heat, fulfillment - M001-ROADMAP.md — 3 slices: embedding/clustering, fulfillment/frontend, integration - M002-CONTEXT.md — Monetization: Stripe subscriptions, credits, Connect (depends M001) - M003-CONTEXT.md — AI Generation: LLM pipeline, BYOK, retry (depends M001, M002) Removed old DECISIONS.md from project root (migrated to .gsd/).		2026-03-25 00:45:33 -05:00
.bg-shell	Initial commit: project spec	2026-03-24 20:36:53 -05:00
db	Versioning, drafts, resizable editor, My Shaders, 200 seed shaders	2026-03-24 22:00:10 -05:00
scripts	Fix shader rendering: visibility-aware WebGL contexts, fix 2 GLSL shaders	2026-03-24 22:12:58 -05:00
services	M2 complete: Recommendation engine + similar shaders + tag affinities	2026-03-24 23:25:45 -05:00
.env.example	M0: Foundation scaffold — Docker Compose, DB schema, FastAPI app, all service stubs	2026-03-24 20:45:08 -05:00
.gitignore	Bootstrap GSD structure for M001-M003	2026-03-25 00:45:33 -05:00
docker-compose.dev.yml	Fix Docker Compose startup issues	2026-03-24 21:06:01 -05:00
docker-compose.override.yml	Fix Docker Compose startup issues	2026-03-24 21:06:01 -05:00
docker-compose.yml	Fix Docker Compose startup issues	2026-03-24 21:06:01 -05:00
FRACTAFRAG FULL SPEC & SUMMARY.md	Initial commit: project spec	2026-03-24 20:36:53 -05:00
README.md	M0: Foundation scaffold — Docker Compose, DB schema, FastAPI app, all service stubs	2026-03-24 20:45:08 -05:00

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.