05d39fdda8
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)
67 lines
3 KiB
Markdown
67 lines
3 KiB
Markdown
# 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
|