arXivisual - Moses Yebei

The Problem

Academic research papers are delivered as dense, monolithic text blocks. Researchers and students must manually extract key concepts, conceptualize visual representations, and build animations to understand complex ideas. This process is time-consuming and requires skills in both domain knowledge and animation tools. arXivisual automates this pipeline, transforming paper text into structured animations via AI agents.

What This Does

arXivisual provides a full-stack pipeline for paper-to-visualization. Users ingest an arXiv URL via the Next.js frontend (frontend/app/page.tsx), which triggers the backend job worker (backend/jobs/worker.py). AI agents ingest the paper (backend/ingestion/pdf_parser.py, backend/ingestion/html_parser.py), analyze sections for visual opportunities (backend/agents/section_analyzer.py, backend/agents/manim_generator.py), and generate Manim code (backend/manim_generator.py). A validation pipeline runs four quality gates before rendering (backend/rendering/local_runner.py) and serving the result through the API (backend/api/routes.py) to the interactive scrollytelling interface (frontend/components/ScrollyReader.tsx, frontend/components/VideoPlayer.tsx).

How It Is Wired

Execution begins at the API route start_processing in backend/api/routes.py, which enqueues a process_paper_job in backend/jobs/worker.py (reaching 110 downstream functions). The worker coordinates the pipeline: ingestion feeds into the agent graph centered on backend/agents/pipeline (instability 0.92, Ca 1, Ce 12), where Section is called from 8 places and GeneratedCode from 7. The run function in backend/agents/base.py (called from nowhere else in the repo) orchestrates LLM calls (_call_llm, _call_llm_sync) and JSON parsing (_parse_json_response). Visualizations are rendered via backend/rendering/local_runner.py, which executes Manim subprocesses. Paths to external effects are short: process_paper_job -> update_job_status writes to the database; run -> _call_llm hits the Anthropic model; run -> get_manim_docs reads the filesystem. The module backend/agents/base.py is a hub defined by 19 functions and 1 class, routing provider detection and client setup for the majority of agent logic.

How To Use It

Setup:

# Frontend
cd frontend
npm install
npm run dev

# Backend
cd backend
cp .env.example .env  # Add Anthropic, ElevenLabs, Dedalus keys
uv sync
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

Navigate to http://localhost:3000, paste an arXiv URL, and submit. The system will ingest, analyze, generate, validate, and display the visualization.

Real-World Use

A researcher pastes a machine-learning paper URL. The system fetches the PDF, extracts sections on attention mechanisms, and the manim_generator agent produces a Manim script visualizing the multi-head attention matrix. The voiceover_generator agent scripts narration. The pipeline runs validation gates; if the scene passes, local_runner.py renders the MP4. The frontend displays the animation synchronized with the text, allowing the researcher to grasp the concept without manually coding the animation.

Code Health & Issues

HIGH – No LICENSE file at root; redistribution rights are undefined, blocking legal reuse.
HIGH – No CI/CD pipeline; every merge runs without automated build or test validation.
HIGH – Wildcard CORS allow_origins=["*"] with credentials enabled in backend/main.py; any site can make authenticated API calls from a user's browser.
HIGH – No build gate for backend/Dockerfile; deployment artifacts have never been validated via automated workflow.
MEDIUM – Mutable base image python:3.13-slim in backend/Dockerfile; no digest pinning, so CVE sets shift between builds.
MEDIUM – Large demo videos over 5MB (backend/demo-videos/ArXivisual.mp4, frontend/public/videos/...) increase clone size and CI checkout cost.
MEDIUM – No Dependabot or Renovate configuration; dependency advisories remain unpatched without manual audit.
MEDIUM – No non-root USER in the Docker image; processes run as root, elevating container escape risk.
LOW – Missing convention files (.editorconfig, .gitattributes, formatter config), risking inconsistent tooling across contributors.

Static analysis also flagged deep nesting (max depth 8) in backend/ingestion/pdf_parser.py, backend/jobs/worker.py, and backend/agents/context7_docs.py; broad except blocks in backend/agents/context7_docs.py, backend/agents/render_tester.py, and backend/ingestion/pdf_parser.py; and 86 duplicated 6-line blocks across 28 files in the agent directory, particularly backend/agents/base.py and backend/agents/dedalus_base.py.

The Bottom Line

arXivisual is a functional hackathon prototype that successfully chains ingestion, AI analysis, and Manim rendering into a user-friendly interface. The code graph is resolvable and the pipeline logic is traceable. However, it carries significant SDLC gaps: no license, no CI, a security-hardened CORS misconfiguration, and a mutable Docker base. It is viable for experimentation and internal demos, but requires the listed fixes before it should be shared beyond the originating team or used in a client-facing capacity.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

199 files

Python65
TSX28
Markdown27
TypeScript8
JSON4
TOML2

ReactNext.jsDocker

Module dependencies

The 10 most depended-upon modules of 103, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_backend_models_generation["generation"] n1_backend_agents_base["base"] n2_backend_models_paper["paper"] n3_backend_db_models["models"] n4_backend_models_voiceover["voiceover"] n5_ckend_agents_manim_generator["manim_generator"] n6_kend_agents_section_analyzer["section_analyzer"] n7_s_voiceover_script_validator["voiceover_script_validat"] n8_agents_visualization_planner["visualization_planner"] n9_ackend_agents_code_validator["code_validator"] n9_ackend_agents_code_validator --> n0_backend_models_generation n5_ckend_agents_manim_generator --> n1_backend_agents_base n5_ckend_agents_manim_generator --> n0_backend_models_generation n6_kend_agents_section_analyzer --> n1_backend_agents_base n6_kend_agents_section_analyzer --> n2_backend_models_paper n6_kend_agents_section_analyzer --> n0_backend_models_generation n8_agents_visualization_planner --> n1_backend_agents_base n8_agents_visualization_planner --> n0_backend_models_generation n7_s_voiceover_script_validator --> n1_backend_agents_base n7_s_voiceover_script_validator --> n0_backend_models_generation n7_s_voiceover_script_validator --> n4_backend_models_voiceover

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
MediumNo LICENSE file - unclear usage/redistribution rights root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium4

low1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Add a workflow that builds and tests this repositoryhigh

103 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh2 occurrences

backend/Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Replace the wildcard CORS origin with an explicit allow listhigh

backend/main.py

allow_origins=["*"] together with credentials enabled

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

backend/Dockerfile

python:3.13-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

backend/demo-videos/ArXivisual.mp4

2 blobs over 5MB: ArXivisual.mp4 18.5MB, demo.mp4 14.0MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Add a non-root USER to the imagemedium

backend/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.