ForkFolio — System Architecture
Production
Updated:
Branch:
Click any component for details
Frontend
Backend
Database
Cache
External Service
Auth
Client
Next.js Frontend
Next.js App
apps/web/
App Router · Server Components · SSR
Next.js 16
React 19
TypeScript
Tailwind CSS 4
shadcn/ui
Vitest
Pages & Routing
/, /browse, /recipes/[id], /recipes/new, /books, /bag, /experiment
Auth (Supabase SSR)
Google OAuth · httpOnly cookies
PostHog Analytics
posthog-js · Event tracking
REST API + SSE streaming · X-API-Token · X-Viewer-User-Id
Backend
FastAPI Backend — app/
Middleware
Timeout (120s)
→
Auth Token
→
Rate Limit (120/min)
→
Request Size (1MB)
→
Trace Context
API Routers — app/api/v1/
Recipes Router
app/api/v1/endpoints/recipes.py
process-and-store
preview-from-url
preview-jobs
list/search
delete
grocery-list
Recipe Books Router
app/api/v1/endpoints/recipe_books.py
CRUD
add/remove recipes
by-recipe lookup
Experiments Router
app/api/v1/endpoints/experiments.py
LangGraph
SSE stream
chat threads
Services — app/services/
Services Layer
RecipeProcessingService
extract · cleanup · dedupe · embed
LLMGenerationService
text gen · structured output · embeddings
HybridSearchImpl
FTS + trigram + pgvector
ExperimentAgentGraph
LangGraph state machine
RecipePreviewJobService
queue · process isolate · complete/fail
Data Access — app/services/data/
Data Access Layer
RecipeManager
CRUD + hybrid search SQL
RecipeBookManager
book + recipe link management
ExperimentManager
thread + message persistence
Caching — app/core/cache.py
Process-local TTL Caches
LLM responses · embeddings · hybrid search · preview-job fallback
psycopg2 pool (min=2, max=10) · redis-py (lazy)
Data Stores
PostgreSQL / Supabase
Primary Database
AWS us-west-2
psycopg2 · pgvector (HNSW, 768-dim) · pg_trgm
recipes
recipe_ingredients
recipe_instructions
recipe_embeddings
recipe_books
recipe_book_recipes
experiment_threads
experiment_messages
profiles
Redis Job Store
Managed KV
optional
Render free plan · internal URL
preview jobs
survives restart
TTL expiry
API calls (HTTPS)
External Services
OpenRouter
LLM provider · gpt-oss-20b · OpenAI-compat API
Supabase Auth
Google OAuth · JWT · profile sync trigger
PostHog
Frontend analytics · event capture
Braintrust
optional
LLM call tracing · observability
Render
Hosting (FE + BE + Redis) · render.yaml
Click any component above to see details →
✕