# jukalemanmath/roast-my-code architecture

> Architecture diagram of the GitHub repository jukalemanmath/roast-my-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jukalemanmath/roast-my-code
- Repository: https://github.com/jukalemanmath/roast-my-code

## Overview

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: [`backend/apps/reviews/models.py`](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/models.py) (Review), [`backend/apps/input_handler`](https://github.com/jukalemanmath/roast-my-code/tree/main/backend/apps/input_handler) (Input Handler), [`frontend/app`](https://github.com/jukalemanmath/roast-my-code/tree/main/frontend/app) (App Routes), [`backend/apps/reviews/views.py`](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/views.py) (Review API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_review_domain[("Review<br/>domain model<br/>[models.py]")]
  node_review_api["Review API<br/>REST surface<br/>[views.py]"]
  node_review_serializers["Review Serializers<br/>serialization<br/>[serializers.py]"]
  node_input_handler["Input Handler<br/>ingest boundary"]
  node_input_paste["Paste Input<br/>submit path<br/>[paste.py]"]
  node_input_upload["File Upload<br/>submit path<br/>[file_upload.py]"]
  node_input_github["GitHub Fetch<br/>submit path<br/>[github_fetch.py]"]
  node_worker_task["Worker Task<br/>celery job<br/>[tasks.py]"]
  node_pipeline_graph["Pipeline Graph<br/>state machine<br/>[graph.py]"]
  node_review_state["Review State<br/>pipeline state<br/>[state.py]"]
  node_agent_core["Agent Base<br/>[base.py]"]
  node_agent_personas["Agent Personas<br/>llm agents"]
  node_ws_layer["WebSockets<br/>realtime layer"]
  node_export_pdf["PDF Export<br/>reporting<br/>[pdf.py]"]
  node_user_auth[("Users & Auth<br/>identity")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App Routes<br/>next routes"]
  node_frontend_ui["UI Components<br/>presentation"]
  node_frontend_api["API Client<br/>client integration<br/>[api.ts]"]
  node_frontend_ws["WS Client<br/>client integration<br/>[ws.ts]"]
end

subgraph group_infra["Infra"]
  node_docker_runtime["Docker Compose<br/>runtime<br/>[docker-compose.yml]"]
  node_redis_dep[("Redis<br/>shared dependency")]
  node_postgres_dep[("PostgreSQL<br/>shared dependency")]
  node_groq_dep(("Groq<br/>llm provider"))
end

node_input_handler -->|"normalizes"| node_input_paste
node_input_handler -->|"normalizes"| node_input_upload
node_input_handler -->|"normalizes"| node_input_github
node_input_handler -->|"creates"| node_review_domain
node_review_api -->|"uses"| node_review_serializers
node_review_api -->|"reads/writes"| node_review_domain
node_worker_task -->|"runs"| node_pipeline_graph
node_worker_task -->|"updates"| node_review_domain
node_pipeline_graph -->|"passes"| node_review_state
node_pipeline_graph -->|"delegates"| node_agent_core
node_agent_core -->|"implements"| node_agent_personas
node_agent_personas -->|"calls"| node_groq_dep
node_agent_personas -->|"emits results to"| node_review_domain
node_ws_layer -->|"streams"| node_review_domain
node_frontend_api -->|"calls"| node_review_api
node_frontend_ws -->|"subscribes"| node_ws_layer
node_frontend_app -->|"renders"| node_frontend_ui
node_frontend_app -->|"fetches"| node_frontend_api
node_frontend_app -->|"listens"| node_frontend_ws
node_export_pdf -->|"renders"| node_review_domain
node_user_auth -->|"protects"| node_review_api
node_user_auth -->|"signs in"| node_frontend_app
node_docker_runtime -->|"includes"| node_redis_dep
node_docker_runtime -->|"includes"| node_postgres_dep
node_worker_task -->|"uses"| node_redis_dep
node_ws_layer -->|"uses"| node_redis_dep
node_review_domain -->|"persists to"| node_postgres_dep

click node_review_domain "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/models.py"
click node_review_api "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/views.py"
click node_review_serializers "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/serializers.py"
click node_input_handler "https://github.com/jukalemanmath/roast-my-code/tree/main/backend/apps/input_handler"
click node_input_paste "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/paste.py"
click node_input_upload "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/file_upload.py"
click node_input_github "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/github_fetch.py"
click node_worker_task "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/worker/tasks.py"
click node_pipeline_graph "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/graph.py"
click node_review_state "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/state.py"
click node_agent_core "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/agents/base.py"
click node_agent_personas "https://github.com/jukalemanmath/roast-my-code/tree/main/backend/pipeline/agents"
click node_ws_layer "https://github.com/jukalemanmath/roast-my-code/tree/main/backend/ws"
click node_export_pdf "https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/export/pdf.py"
click node_user_auth "https://github.com/jukalemanmath/roast-my-code/tree/main/backend/apps/users"
click node_frontend_app "https://github.com/jukalemanmath/roast-my-code/tree/main/frontend/app"
click node_frontend_ui "https://github.com/jukalemanmath/roast-my-code/tree/main/frontend/components"
click node_frontend_api "https://github.com/jukalemanmath/roast-my-code/blob/main/frontend/lib/api.ts"
click node_frontend_ws "https://github.com/jukalemanmath/roast-my-code/blob/main/frontend/lib/ws.ts"
click node_docker_runtime "https://github.com/jukalemanmath/roast-my-code/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_review_domain,node_review_api,node_review_serializers,node_input_handler,node_input_paste,node_input_upload,node_input_github,node_worker_task,node_pipeline_graph,node_review_state,node_agent_core,node_agent_personas,node_ws_layer,node_export_pdf,node_user_auth toneBlue
class node_frontend_app,node_frontend_ui,node_frontend_api,node_frontend_ws toneAmber
class node_docker_runtime,node_redis_dep,node_postgres_dep,node_groq_dep toneMint
```

## Components

### Backend

Django API, pipeline, workers, websockets, and persistence.

- [Review](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/models.py): domain model · Core persisted review record with status, agent outputs, synthesis, events, and share slug. · `backend/apps/reviews/models.py`
- [Review API](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/views.py): REST surface · Create, detail, share, history, and PDF endpoints for reviews. · `backend/apps/reviews/views.py`
- [Review Serializers](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/reviews/serializers.py): serialization · API serialization layer for review payloads and responses. · `backend/apps/reviews/serializers.py`
- [Input Handler](https://github.com/jukalemanmath/roast-my-code/tree/main/backend/apps/input_handler): ingest boundary · Normalizes pasted code, file uploads, and GitHub fetches; enforces limits and language detection. · `backend/apps/input_handler`
- [Paste Input](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/paste.py): submit path · Handles pasted code submissions. · `backend/apps/input_handler/paste.py`
- [File Upload](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/file_upload.py): submit path · Handles uploaded file submissions. · `backend/apps/input_handler/file_upload.py`
- [GitHub Fetch](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/input_handler/github_fetch.py): submit path · Fetches code from GitHub URLs. · `backend/apps/input_handler/github_fetch.py`
- [Worker Task](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/worker/tasks.py): celery job · Owns review lifecycle, retries, failure handling, and pipeline execution. · `backend/worker/tasks.py`
- [Pipeline Graph](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/graph.py): state machine · LangGraph orchestration for the sequential review run. · `backend/pipeline/graph.py`
- [Review State](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/state.py): pipeline state · Shared pipeline state passed between agents and synthesis. · `backend/pipeline/state.py`
- [Agent Base](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/pipeline/agents/base.py): llm agent base · Common agent behavior for calling the model and parsing structured output. · `backend/pipeline/agents/base.py`
- [Agent Personas](https://github.com/jukalemanmath/roast-my-code/tree/main/backend/pipeline/agents): llm agents · Sequential persona modules: pragmatist, paranoid, minimalist, optimizer, mentor, and synthesis. · `backend/pipeline/agents`
- [WebSockets](https://github.com/jukalemanmath/roast-my-code/tree/main/backend/ws): realtime layer · Channels consumers, routing, and auth middleware for live review updates. · `backend/ws`
- [PDF Export](https://github.com/jukalemanmath/roast-my-code/blob/main/backend/apps/export/pdf.py): reporting · Renders persisted review data into a downloadable PDF report. · `backend/apps/export/pdf.py`
- [Users & Auth](https://github.com/jukalemanmath/roast-my-code/tree/main/backend/apps/users): identity · 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](https://github.com/jukalemanmath/roast-my-code/tree/main/frontend/app): next routes · Landing, live review, public share, dashboard, auth callback, and example pages. · `frontend/app`
- [UI Components](https://github.com/jukalemanmath/roast-my-code/tree/main/frontend/components): presentation · Reusable panels, cards, controls, navbar, and theme/input widgets. · `frontend/components`
- [API Client](https://github.com/jukalemanmath/roast-my-code/blob/main/frontend/lib/api.ts): client integration · REST client boundary used by the frontend to talk to the backend. · `frontend/lib/api.ts`
- [WS Client](https://github.com/jukalemanmath/roast-my-code/blob/main/frontend/lib/ws.ts): client integration · WebSocket client boundary used to subscribe to live review events. · `frontend/lib/ws.ts`

### Infra

Container and runtime dependencies shared across services.

- [Docker Compose](https://github.com/jukalemanmath/roast-my-code/blob/main/docker-compose.yml): runtime · Containerized deployment for web, worker, frontend, Redis, and database services. · `docker-compose.yml`
- **Redis**: shared dependency · Broker, cache, and realtime pub/sub backend for Celery and Channels.
- **PostgreSQL**: shared dependency · Durable storage for users, reviews, artifacts, and history.
- **Groq**: llm provider · External model provider used by the agent personas.

## Connections

- 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.