xpltdco/fractafrag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fractafrag/DECISIONS.md
John Lightner 05d39fdda8 M0: Foundation scaffold — Docker Compose, DB schema, FastAPI app, all service stubs 
Track A (Infrastructure & Data Layer):
- docker-compose.yml with all 7 services (nginx, frontend, api, mcp, renderer, worker, postgres, redis)
- docker-compose.override.yml for local dev (hot reload, port exposure)
- PostgreSQL init.sql with full schema (15 tables, pgvector indexes, creator economy stubs)
- .env.example with all required environment variables

Track A+B (API Layer):
- FastAPI app with 10 routers (auth, shaders, feed, votes, generate, desires, users, payments, mcp_keys, health)
- SQLAlchemy ORM models for all 15 tables
- Pydantic schemas for all request/response types
- JWT auth middleware (access + refresh tokens, Redis blocklist)
- Redis rate limiting middleware
- Celery worker config with job stubs (render, embed, generate, feed cache, expire bounties)
- Alembic migration framework

Service stubs:
- MCP server (health endpoint, 501 for all tools)
- Renderer service (Express + Puppeteer scaffold, 501 for /render)
- Frontend (package.json with React/Vite/Three.js/TanStack/Tailwind deps)
- Nginx reverse proxy config (/, /api, /mcp, /renders)

Project:
- DECISIONS.md with 11 recorded architectural decisions
- README.md with architecture overview
- Sample shader seed data (plasma, fractal noise, raymarched sphere)
2026-03-24 20:45:08 -05:00

3 KiB
Raw Blame History

Fractafrag — Project Decisions

D001 — Backend Language & Framework

  • Choice: Python + FastAPI
  • Rationale: AI/ML integrations (pgvector, LLM clients, embeddings) are Python-native. FastAPI gives async performance with Pydantic auto-generated OpenAPI docs. Celery + Redis is mature for job queues.
  • Made by: Collaborative
  • Revisable: No

D002 — Frontend Stack

  • Choice: React 18 + Vite + Three.js + TanStack Query + Zustand + Tailwind CSS
  • Rationale: Three.js for 3D shader rendering, raw WebGL for feed thumbnails. React UI, TanStack Query for server state, Zustand for client state.
  • Made by: Collaborative
  • Revisable: No

D003 — Database & Cache

  • Choice: PostgreSQL 16 + pgvector + Redis 7
  • Rationale: pgvector for taste/style/desire embeddings (ANN). Redis for sessions, feed cache, rate limiting, Celery broker.
  • Made by: Collaborative
  • Revisable: No

D004 — Container Orchestration

  • Choice: Single Docker Compose stack, self-hosted, no cloud dependencies
  • Rationale: Self-contained with nginx reverse proxy. .env-driven config.
  • Made by: Collaborative
  • Revisable: No

D005 — Media Storage (Q1)

  • Choice: Docker volume initially, S3-compatible config flag for later migration
  • Rationale: Volume is simplest for single-server. Add Minio/S3 when storage grows large.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D006 — Style Embedding Model (Q2)

  • Choice: Heuristic classifier + LLM structured output for M1, fine-tune later
  • Rationale: No training data yet for fine-tuning. Heuristic is fast/cheap, LLM fills accuracy gaps.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D007 — Renderer Approach (Q3)

  • Choice: Puppeteer + Headless Chromium
  • Rationale: Accurate browser-equivalent rendering. Profile at M2 and optimize if needed.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D008 — Generation Status UX (Q4)

  • Choice: Polling for M5, SSE upgrade later
  • Rationale: Simpler to implement. Generation takes 5-30s, 2s polling is acceptable UX.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D009 — Comments Scope (Q6)

  • Choice: Defer to post-M5 polish sprint
  • Rationale: Schema is in place. Feature is not on critical path for core product loop.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D010 — Moderation Approach (Q7)

  • Choice: Admin API endpoints only (/api/v1/admin/queue). No admin UI for M4.
  • Rationale: Simple approve/reject actions via API. Admin panel deferred until scale demands it.
  • Made by: Agent (per spec recommendation)
  • Revisable: Yes

D011 — Creator Economy

  • Choice: Deferred until organic traction (500 DAU, 1000 shaders, 20 active creators)
  • Rationale: Build the hooks (schema stubs, engagement tracking), not the features. Monetization on a platform nobody uses is worthless.
  • Made by: Collaborative (per spec Section 11)
  • Revisable: Yes