xpltdco/fractafrag
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Create Home wiki page for fractafrag

xpltd_admin 2026-04-03 22:48:27 -06:00
commit 73d2dbe30d
1 changed files with 103 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
Home.md Normal file

@ -0,0 +1,103 @@
# 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](Architecture) | System design, service topology, data flow, design decisions |
| [Getting Started](Getting-Started) | Local dev setup, prerequisites, Docker Compose |
| [Data Model](Data-Model) | PostgreSQL schema, ORM models, pgvector indexes |
| [API Reference](API-Reference) | Complete REST endpoint inventory |
| [Deployment](Deployment) | Docker setup, volumes, nginx, health checks |
| [Configuration](Configuration) | All environment variables and settings |
| [Development Guide](Development-Guide) | Code patterns, testing, CI/CD |
| [Agent Context](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.