From 73d2dbe30d4884c8a51999e01930de6abfe7d5a0 Mon Sep 17 00:00:00 2001 From: xpltd_admin Date: Fri, 3 Apr 2026 22:48:27 -0600 Subject: [PATCH] Create Home wiki page for fractafrag --- Home.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..05cb05c --- /dev/null +++ b/Home.md @@ -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. \ No newline at end of file