Report Generator

Report Generator is a full-stack research workflow for building long-form scientific or analytical reports from structured evidence instead of one-shot prompting.

It combines a React frontend with a FastAPI backend, SQLite persistence, source-quality checks, report-quality checks, versioned report runs, and export pipelines for Markdown, PDF, and DOCX.

What it does

• Create research projects from a topic or guiding question
• Generate a report outline and deep research questions with an LLM
• Ingest evidence from shared URLs, pasted text, and uploaded .md, .txt, or .docx files
• Normalize sources, preserve provenance, and archive research artifacts
• Run source QA before synthesis and report QC after generation
• Generate, revise, score, refine, and export report versions

Stack

• Frontend: React, TypeScript, Vite
• Backend: FastAPI, SQLAlchemy, SQLite
• LLM provider: OpenRouter
• Export formats: Markdown, PDF, DOCX

Repository layout

backend/   FastAPI app, database models, routers, services, tests, scripts
frontend/  React SPA used to manage the report workflow
start.sh   Starts backend and frontend dev servers together

Prerequisites

• Python 3.11+
• Node.js 20+
• npm 10+

Quick start

1. Create the backend virtual environment and install Python dependencies.

python3 -m venv venv
./venv/bin/pip install -r backend/requirements.txt

2. Install frontend dependencies.

cd frontend
npm install
cd ..

3. Create a local environment file.

cp .env.example .env

Set at least:

• OPENROUTER_API_KEY
• DEFAULT_MODEL (optional, defaults to google/gemini-2.5-flash-lite)
• DATABASE_URL (optional; defaults to local SQLite in backend/data/app.db)

4. Start both apps.

./start.sh

After startup:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Running services separately

Backend:

cd backend
../venv/bin/uvicorn main:app --reload --host localhost --port 8000

Frontend:

cd frontend
npm run dev -- --host localhost

If you need the frontend to talk to a non-default API URL, set VITE_API_BASE_URL before starting Vite.

Tests and verification

Backend tests:

./venv/bin/pytest

Frontend production build:

cd frontend
npm run build

Notes

• Local databases, uploads, archives, exports, and LLM logs are stored under backend/data/ and are not meant to be committed.
• The backend creates missing data directories automatically on startup.
• backend/scripts/backfill_legacy_project.py can be used to backfill legacy projects into the current storage model.

Workflow overview

1. Create a project
2. Generate an outline
3. Generate research questions
4. Add evidence for each question
5. Review source QA results
6. Synthesize a report draft
7. Run QC, scoring, and refinement
8. Export the final report and supplement