How jukalemanmath/roast-my-code works
1. Top-level shape
- This repo is a two-tier product: a Django backend in backend/ and a Next.js frontend in frontend/.
- The backend owns all durable data, review orchestration, LLM calls, WebSockets, auth, and PDF export.
- The frontend is a thin interactive client that submits code, subscribes to live review updates, and renders results/history/share pages.
2. Core business object: Review
- The central domain entity is the review: submitted code plus metadata, lifecycle status, agent outputs, synthesis output, event log, and share slug.
- The backend persists review state in PostgreSQL and uses JSON fields for agent results, synthesis verdicts, and replayable event history.
- This is the main boundary for the whole system: every input mode becomes a Review, and every output mode reads from it.
3. Input acquisition boundary
- backend/apps/input_handler/ normalizes three submission paths:
- pasted code,
- uploaded file,
- GitHub URL fetch.
- It also enforces size/line limits and language detection before the review pipeline starts.
- This module is the first trust boundary: raw user input is sanitized and constrained before any LLM or storage work.
4. Review API and user-facing backend
- backend/apps/reviews/ contains the REST layer for create/detail/share/history/PDF endpoints.
- It is the primary backend API surface consumed by the frontend.
- The same app also defines review models, serializers, and admin integration, so it sits at the center of persistence and external presentation.
5. Asynchronous execution pipeline
- backend/worker/tasks.py is the Celery entry point that owns review execution lifecycle: mark pending/running/done, invoke the pipeline, handle retries, and record failures.
- The actual review logic lives in backend/pipeline/, which is a LangGraph state machine.
- The pipeline runs the five agent personas in sequence, then hands their outputs to a synthesis step.
6. Agent subsystem
- backend/pipeline/agents/ contains one module per persona: pragmatist, paranoid, minimalist, optimizer, mentor, plus synthesis.
- Each agent transforms the shared ReviewState, calls the Groq LLM, parses structured JSON, and emits its result.
- The important architectural choice is that agent execution is sequential, not parallel, to fit rate limits and to stream one result at a time to the UI.
7. Realtime delivery path
- backend/ws/ is the live-update layer built on Django Channels.
- WebSocket consumers subscribe clients to a review-specific group and replay stored event logs for late joiners.
- Middleware handles JWT-based auth via query param for protected connections, while anonymous connections can still observe public review streams where allowed.
8. Persistence and auth
- backend/apps/users/ holds the custom user model and auth endpoints, including JWT and Google OAuth exchange.
- This is a separate boundary from reviews: authenticated users gain history and higher limits, but the review pipeline itself remains usable anonymously.
- PostgreSQL stores users, reviews, and durable review artifacts; Redis is used for Channels pub/sub, Celery broker/backend, and cache.
9. Export and reporting
- backend/apps/export/ turns a finished review into a PDF using an HTML template and WeasyPrint.
- This module is downstream of the review record, not the live pipeline: it renders the persisted synthesis and agent findings into a downloadable document.
- That keeps reporting decoupled from execution and lets the same review data power both web and PDF views.
10. Frontend application structure
- frontend/app/ is organized by route: landing/input, live review view, public share view, dashboard/history, auth callback, and an example page.
- frontend/components/ contains reusable presentation pieces such as agent cards, synthesis panel, share/download controls, navbar, and input panel.
- frontend/lib/api.ts and frontend/lib/ws.ts are the client-side integration boundaries for REST and WebSocket communication.
11. End-to-end request flow
- A user submits code on the frontend, which calls POST /api/reviews/.
- The backend creates a review row and queues a Celery task.
- The worker runs the LangGraph pipeline; each agent result is pushed over WebSocket as it completes.
- Synthesis finishes the run, the review is marked done, and the frontend updates in place or later reloads from persisted state.
12. Public sharing and history
- Reviews get a permanent public URL under /r/[slug], backed by a short share slug rather than a sequential ID.
- Authenticated users also have a dashboard route for review history.
- This creates two read paths over the same review record: public share access and private account history.
13. Infrastructure and deployment constraints that matter
- The runtime is split into at least three processes: ASGI web server, Celery worker, and frontend app, all containerized with Docker Compose.
- Redis is a shared infrastructure dependency because it supports both background jobs and realtime WebSockets.
- Groq is the external LLM provider, GitHub is the optional code source, and Google OAuth is the optional identity provider.
14. Testing boundaries
- The repository has focused tests around each subsystem: input handling, pipeline, worker tasks, WebSocket behavior, reviews, and frontend UI/API/WebSocket interactions.
- That test layout mirrors the architecture: each major boundary is exercised independently rather than through one monolithic test suite.
Main entry points: models.py Review · input_handler Input Handler · app App Routes · views.py Review API
Components 23
Backend
Django API, pipeline, workers, websockets, and persistence.
- Review · Core persisted review record with status, agent outputs, synthesis, events, and share slug.
backend/apps/reviews/models.py - Review API · Create, detail, share, history, and PDF endpoints for reviews.
backend/apps/reviews/views.py - Review Serializers · API serialization layer for review payloads and responses.
backend/apps/reviews/serializers.py - Input Handler · Normalizes pasted code, file uploads, and GitHub fetches; enforces limits and language detection.
backend/apps/input_handler - Paste Input · Handles pasted code submissions.
backend/apps/input_handler/paste.py - File Upload · Handles uploaded file submissions.
backend/apps/input_handler/file_upload.py - GitHub Fetch · Fetches code from GitHub URLs.
backend/apps/input_handler/github_fetch.py - Worker Task · Owns review lifecycle, retries, failure handling, and pipeline execution.
backend/worker/tasks.py - Pipeline Graph · LangGraph orchestration for the sequential review run.
backend/pipeline/graph.py - Review State · Shared pipeline state passed between agents and synthesis.
backend/pipeline/state.py - Agent Base · Common agent behavior for calling the model and parsing structured output.
backend/pipeline/agents/base.py - Agent Personas · Sequential persona modules: pragmatist, paranoid, minimalist, optimizer, mentor, and synthesis.
backend/pipeline/agents - WebSockets · Channels consumers, routing, and auth middleware for live review updates.
backend/ws - PDF Export · Renders persisted review data into a downloadable PDF report.
backend/apps/export/pdf.py - Users & Auth · Custom users, JWT, and Google OAuth integration for authenticated features.
backend/apps/users
Frontend
Next.js client for submission, live review, sharing, and history.
- App Routes · Landing, live review, public share, dashboard, auth callback, and example pages.
frontend/app - UI Components · Reusable panels, cards, controls, navbar, and theme/input widgets.
frontend/components - API Client · REST client boundary used by the frontend to talk to the backend.
frontend/lib/api.ts - WS Client · WebSocket client boundary used to subscribe to live review events.
frontend/lib/ws.ts
Infra
Container and runtime dependencies shared across services.
- Docker Compose · Containerized deployment for web, worker, frontend, Redis, and database services.
docker-compose.yml - Redis · Broker, cache, and realtime pub/sub backend for Celery and Channels.
- PostgreSQL · Durable storage for users, reviews, artifacts, and history.
- Groq · External model provider used by the agent personas.
Connections 27
- Input Handler → Paste Input: normalizes · Routes pasted code through the paste input path.
- Input Handler → File Upload: normalizes · Routes uploaded files through the upload path.
- Input Handler → GitHub Fetch: normalizes · Routes GitHub URLs through the fetch path.
- Input Handler → Review: creates · Produces the persisted review record after validation.
- Review API → Review Serializers: uses · Serializes and deserializes review API payloads.
- Review API → Review: reads/writes · Exposes review creation, lookup, sharing, history, and PDF access.
- Worker Task → Pipeline Graph: runs · Invokes the LangGraph review pipeline for each queued review.
- Worker Task → Review: updates · Marks review status, retries, and terminal outcomes.
- Pipeline Graph → Review State: passes · Executes the pipeline over shared review state.
- Pipeline Graph → Agent Base: delegates · Uses common agent execution and parsing behavior.
- Agent Base → Agent Personas: implements · Supports the persona-specific review agents and synthesis step.
- Agent Personas → Groq: calls · Sends prompts to the external LLM provider.
- Agent Personas → Review: emits results to · Stores agent outputs and synthesis findings on the review.
- WebSockets → Review: streams · Publishes live review events and replays stored history.
- API Client → Review API: calls · Frontend REST requests target the review API.
- WS Client → WebSockets: subscribes · Frontend connects to review-specific live update channels.
- App Routes → UI Components: renders · Routes compose reusable UI components.
- App Routes → API Client: fetches · Pages submit code and load persisted review data.
- App Routes → WS Client: listens · Live review pages subscribe to streaming updates.
- PDF Export → Review: renders · Builds PDF output from persisted review data.
- Users & Auth → Review API: protects · Supports authenticated access to dashboard/history and gated endpoints.
- Users & Auth → App Routes: signs in · Enables auth callback and user-facing session flow.
- Docker Compose → Redis: includes · Shared infrastructure for broker and realtime pub/sub.
- Docker Compose → PostgreSQL: includes · Durable database service for the backend.
- Worker Task → Redis: uses · Consumes Celery broker/backend support.
- WebSockets → Redis: uses · Uses Channels pub/sub and cache support.
- Review → PostgreSQL: persists to · Stores reviews and related durable artifacts.