Prumo

Meet Prumo, an open-source platform for running systematic reviews and meta-analyses without losing the audit trail: import the literature, extract data against versioned templates, and appraise risk of bias with independent reviewers and a recorded consensus step. 🔬

Prumo is under active development. Your suggestions, ideas, and bug reports help us a lot — open a GitHub issue or see Support. We read everything.

🚀 Getting started

Choose the setup that works best for you:

• Live instance The hosted deployment runs at prumoai.vercel.app — Vercel for the frontend, Railway for the API and workers, Supabase for Postgres, Auth, and Storage.

• Run it locally Full control over your data: one make setup, one make start, and the whole stack (Supabase, FastAPI, Celery worker, Vite) comes up together.

Requirement	Notes
Node.js 24 LTS + npm	Recommended via nvm
Python 3.11+	Managed with uv
Supabase CLI	Local Auth + Storage + Postgres
Docker Desktop	Runtime for the local Supabase stack
make	Preinstalled on macOS and Linux

# 1. Clone
git clone https://github.com/raphaelfh/prumo.git
cd prumo

# 2. First-time install
make setup

# 3. (Optional) configure env
cp .env.example .env  # only if make setup did not already
$EDITOR .env backend/.env

# 4. Start the full local stack (Supabase + backend + worker + frontend)
make start

# 5. Sanity checks
make status
make urls

URL	Service
http://localhost:8080	Frontend (Vite dev server)
http://localhost:8000	Backend API
http://localhost:8000/api/v1/docs	OpenAPI / Swagger UI
http://127.0.0.1:54323	Supabase Studio

For manual setup without make, see CONTRIBUTING.

🌟 Features

• Article management Import, organise, deduplicate, and track research articles across the whole review, with PDFs stored and parsed on ingest.

• Zotero integration Pull articles and attachments straight from Zotero collections instead of re-entering metadata by hand.

• Data extraction Build extraction forms from versioned templates (CHARMS, PROBAST+AI, or your own), and pin every run to the template snapshot it was answered against.

• Quality assessment (HITL) Risk-of-bias appraisal with PROBAST and QUADAS-2, independent reviewers, blind reviews, and an explicit consensus step before a result is published.

• AI-assisted proposals Field-level suggestions from OpenAI and Anthropic models using your own API keys — always a proposal a human accepts or rejects, never a silent write.

• Grounded citations Every AI suggestion carries the passage it came from, highlighted in the source document, so a reviewer can check the claim in one click.

• PDF viewer Integrated reader with search, annotations, and side-by-side extraction against the article text.

• Batch processing Process many articles and assessment items in parallel through Celery workers.

🛠️ Local development

Command	Purpose
make start / make stop / make restart	Lifecycle of the local stack
make status / make health / make urls	Status, health, URL list
make test-backend / make lint-backend	Backend pytest + ruff
make db-fresh	Reset + migrate + seed (idempotent)
make quality-scan	Full gate: lint, typecheck, tests, architectural fitness
npm test / npm run test:run / npm run test:coverage	Frontend Vitest
npm run lint / npm run build / npm run dev	Frontend ESLint / production build / dev server
npx playwright test	E2E suite (see frontend/e2e/README.md)

Frontend tooling runs from the repo root — there is no frontend/package.json. The app schema is owned by Alembic (backend/alembic/versions/); the supabase/ migrations cover Auth and Storage only.

⚙️ Built with

Typed end to end: TypeScript strict on the frontend, Pydantic v2 and SQLAlchemy 2.0 async on the backend, with row-level security enforcing project-scoped access in Postgres. Tests are pytest, Vitest, and Playwright (E2E + accessibility + visual).

🗂️ Repo layout

prumo/
├── frontend/                # React + Vite app
│   ├── components/          # UI components (shadcn + custom)
│   ├── hooks/               # Custom React hooks
│   ├── services/            # API clients
│   ├── pages/               # Routes
│   ├── lib/                 # Utilities, i18n (copy/), validators
│   └── e2e/                 # Playwright suite
├── backend/                 # FastAPI app
│   ├── app/
│   │   ├── api/v1/          # REST endpoints
│   │   ├── core/            # Config, security, DI
│   │   ├── db/              # Engine, session
│   │   ├── llm/             # Provider adapters, extraction prompts
│   │   ├── models/          # SQLAlchemy models
│   │   ├── repositories/    # CRUD layer
│   │   ├── schemas/         # Pydantic v2 schemas
│   │   ├── services/        # Business logic
│   │   ├── worker/          # Celery tasks
│   │   └── seed.py          # Idempotent seed (CHARMS, PROBAST, QUADAS-2)
│   ├── alembic/versions/    # Migrations (app schema)
│   └── tests/               # pytest suite
├── supabase/migrations/     # Auth + Storage migrations only
├── docs/                    # Documentation (Diátaxis)
├── scripts/                 # Automation scripts
├── railway.toml             # Backend IaC (Railway)
├── vercel.json              # Frontend project config
└── docker-compose.yml       # Local-only Postgres helper

🚢 Deployment

Service	Platform
Frontend	Vercel — auto-deploys main
Backend web (FastAPI + gunicorn)	Railway, Hobby plan, US East
Backend worker (Celery)	Railway, Hobby plan, US East
Redis	Railway managed plugin
Postgres + Auth + Storage	Supabase

See docs/reference/deployment.md for the topology diagram, the full environment-variable reference, deploy gates, rollback procedure, and the CI coverage constraint.

📝 Documentation

Explore the documentation index — a Diátaxis-organised site map covering deployment, migrations, architecture, and test strategy. Recorded architecture decisions live in ADRs, planned work in the roadmap, and the agent entry point is llms.txt.

❤️ Community

Ask questions, report bugs, share ideas, or request features through GitHub issues. We follow a Code of Conduct in all community channels, and Support lists the fastest route for each kind of request.

🛡️ Security

If you discover a security vulnerability in Prumo, please report it responsibly instead of opening a public issue. All legitimate reports are investigated promptly — see the security policy for how to reach us.

🤝 Contributing

• Report bugs or submit feature requests.
• Improve the docs — typo fixes and new content are equally welcome.
• Pick up an item from the roadmap and open a pull request against dev.

Read CONTRIBUTING for the branch model, commit convention, and the checks a pull request has to pass.

We couldn't have done this without you

License

Prumo is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only).