Web app

FastAPI and React application package for biblioflow workflows.

Purpose

biblioflow-web is the browser-based application package. It provides an interactive browser workflow while keeping the analysis logic in the core biblioflow library. The current frontend is an intermediate dashboard with Search, Appraisal, Analysis, and Synthesis workflow groups.

The package is organized as:

packages/biblioflow-web/
├── backend/    # Python package published as biblioflow-web
└── frontend/   # Private React/Vite application, not published to npm

Installation and running

After installation, run the backend CLI:

pip install biblioflow-web
biblioflow-web

For development from the monorepo:

makim web.backend.dev          # defaults to --port 0 for a random free port
makim web.backend.dev --port 8000
makim web.frontend.install
makim web.frontend.dev

When --port 0 is used, Uvicorn prints the selected random port in the logs. Use an explicit port, such as --port 8000, when the Vite development proxy needs a stable backend URL. The frontend development server proxies /api requests to the backend.

Backend package

The backend lives in packages/biblioflow-web/backend and is an individual Python package with its own pyproject.toml, src/, tests, and build metadata. It provides:

FastAPI application factory.
Project, upload, dataset, validation, filter, analysis, matrix, network, and PRISMA/export routes.
Source-agnostic screening routes that stage uploaded files, raw records, and supported remote API searches as candidates before promotion into normal datasets.
Runtime file stores for uploaded files, normalized datasets, exports, and project metadata.
Static-file serving for the bundled React build in production wheels.

Runtime data is controlled by BIBLIOFLOW_WEB_DATA_DIR and should never be written inside the installed package directory.

Demo data

For local interface testing, seed rich synthetic projects with:

makim web.seed.demo
makim web.seed.demo --data-dir /tmp/biblioflow-web-demo

The seed task uses the Python backend and the core biblioflow package to load synthetic records, create projects, set active datasets, and pre-generate JSON/CSV exports. It includes complete projects and a data-quality sandbox with intentional validation warnings.

Frontend package

The frontend lives in packages/biblioflow-web/frontend. It is intentionally private and is not published to npm. The release build compiles the React app and copies the production assets into the backend static package data.

makim web.frontend.install
makim web.frontend.lint
makim web.frontend.tests
makim web.frontend.build

Source-agnostic screening imports

The browser workflow now separates import from review:

The Import or Load page uploads local bibliographic exports, searches supported remote sources, stages records for screening, or loads selected uploads directly as a compatibility shortcut.
The Screening page reviews staged candidates, applies keep/maybe/exclude decisions, marks duplicates, and creates a dataset from selected records.

Screening runs are generic. They can be created from uploaded exports, raw records supplied by a client, or supported remote sources such as PubMed, PubMed Central, OpenAlex, Crossref, and Scopus. Results are first saved as a project-level screening queue with candidate statuses such as candidate, selected, maybe, excluded, duplicate, and imported. This preserves the original import/search run for reproducibility and makes it possible to inspect, filter, and bulk-select records before they enter the active analysis dataset.

The staged workflow is:

Any source input
→ persisted screening run
→ candidate screening table
→ selected candidates
→ active biblioflow dataset

Promoted records are saved with the same dataset payload shape as uploaded files, so all dashboard pages immediately work with the new active dataset.

Remote forms accept a query, source, limit, contact email, optional API key, tool name, and optional screening/dataset name. API keys are sent only to the backend request handler and are not stored in project metadata, screening payloads, datasets, or API responses.

For deployments, configure a default contact email when users should not type it for every import:

export BIBLIOFLOW_NCBI_EMAIL="researcher@example.org"
export BIBLIOFLOW_NCBI_API_KEY="optional-key"

Bundling behavior

The backend build script compiles and copies frontend assets:

cd packages/biblioflow-web/backend
python scripts/build_frontend.py
poetry build

The root Makim task wraps this:

makim web.package.build

Users installing the final biblioflow-web wheel or sdist do not need Node.js or npm because the compiled frontend is already included in the Python package.

API overview

All application API routes live under /api by default.

Area	Route pattern	Purpose
Health	`GET /api/health`	Service and version metadata.
Projects	`/api/projects`	Create, list, inspect, and delete projects.
Uploads	`/api/projects/{project_id}/uploads`	Upload and manage bibliographic files.
Screening	`POST /api/projects/{project_id}/screening/runs`	Stage uploaded files, raw records, or supported remote searches as screening candidates.
Screening	`GET /api/projects/{project_id}/screening/runs`	List project screening runs.
Screening	`GET /api/projects/{project_id}/screening/runs/{screening_run_id}`	Fetch one screening run and its candidates.
Screening	`PATCH /api/projects/{project_id}/screening/runs/{screening_run_id}/candidates`	Apply keep/maybe/exclude/duplicate decisions.
Screening	`POST /api/projects/{project_id}/screening/runs/{screening_run_id}/promote`	Create an active dataset from selected candidates.
Remote sources	`/api/projects/{project_id}/sources/search*`	Compatibility wrappers for earlier PubMed/PMC staged imports.
Remote sources	`POST /api/projects/{project_id}/sources/import`	Compatibility direct import that creates an active dataset.
Datasets	`/api/projects/{project_id}/datasets`	Load uploads and retrieve normalized datasets.
Validation	`/api/projects/{project_id}/datasets/{dataset_id}/validation`	Inspect warnings and validation metadata.
Filters	`/api/projects/{project_id}/datasets/{dataset_id}/filters/*`	Discover filter options and preview filtered results.
Analysis	`/api/projects/{project_id}/datasets/{dataset_id}/analysis/overview`	Run descriptive analysis.
Matrices	`/api/projects/{project_id}/datasets/{dataset_id}/matrices`	Build bibliometric matrices.
Networks	`/api/projects/{project_id}/datasets/{dataset_id}/networks`	Build bibliometric networks.
PRISMA	`/api/projects/{project_id}/prisma`	Build PRISMA flow diagrams from dataset/project state.
Exports	`/api/projects/{project_id}/exports`	Create and download export artifacts.

The PRISMA page renders SVG diagrams with prisma-flow and exposes SVG/PNG downloads in the browser interface.

Design rule

If a web feature requires new bibliometric behavior, add it to biblioflow first. The FastAPI layer should orchestrate projects, uploads, persistence, request validation, and response shaping; it should not become a second analysis library.