BibMedEd

---

Systematic bibliometric reviews currently require stitching together PubMed search, Covidence, VOSviewer, CiteSpace, and Excel — four tools, manual deduplication, and a methodology section that's painful to reconstruct. BibMedEd is one application that does all of it, self-hosts with one command, and exports a citable PRISMA-ready methodology log of every step it took.

New here? Read Why BibMedEd vs Covidence / VOSviewer / Bibliometrix for an honest capability comparison, or jump into the end-to-end case study.

Features

• Multi-database search — PubMed, OpenAlex, CrossRef, Semantic Scholar, and Lens.org built-in, extensible to any source via plug-and-play adapters
• Automated deduplication — Cross-database dedup by DOI and PMID
• Six analysis modules — Publications, authors, countries, keywords, citations, journals
• Interactive visualizations — D3.js co-authorship and keyword co-occurrence network graphs
• Reproducible methodology — Every pipeline step logged, exportable as a citable .txt for your Methods section
• First-run onboarding — One-click synthetic sample project for instant, network-free access to analyses and visualizations
• Standard exports — .RIS (Zotero/EndNote), .CSV (Excel/Sheets), Web of Science plain text (VOSviewer/Bibliometrix), versioned .JSON, methodology log, PRISMA 2020 flow diagram (.svg), and a single-click .zip bundle of all six
• Programmatic access — Auto-generated OpenAPI spec at /openapi.json, interactive Swagger UI at /docs, ReDoc at /redoc. Analysis responses carry a schema_version field for downstream pinning.
• Self-hostable — Single docker compose up on any lab server, no cloud account needed
• Result cap — Default 2,000 records (configurable up to 10,000). For PubMed below 10,000 the results page warns when upstream returned more than was fetched; for other sources and for PubMed at 10,000 truncation is not yet flagged (#151), so treat a count equal to the cap as truncated and check it with bibmeded search --dry-run

Architecture

┌─────────────────────┐     ┌─────────────────────┐     ┌──────────────┐
│  Frontend (Next.js)  │◄───►│  Backend (FastAPI)   │◄───►│  PostgreSQL  │
│                     │     │                     │     └──────────────┘
│  - Search UI        │     │  - REST API         │
│  - Dashboard        │     │  - Adapter Registry  │     ┌──────────────┐
│  - D3.js Networks   │     │  - Analysis Engine  │◄───►│    Redis     │
│  - Export Manager   │     │  - Export Service   │     └──────────────┘
└─────────────────────┘     └─────────────────────┘           │
                                                      ┌──────────────┐
                                                      │Celery Workers│
                                                      │- Search      │
                                                      │- Analysis    │
                                                      └──────────────┘

Quick Start

git clone https://github.com/ata381/BibMedEd
cd BibMedEd/bibmeded
docker compose up

Open http://localhost:3000. That's it.

Just want to look around? Run the disposable, read-only local demo (SQLite, no Postgres or Redis) from bibmeded/: docker compose -f docker-compose.demo.yml up --build, then open http://localhost:3100.

Choose Explore sample project on the empty workspace to open a fully populated, clearly labeled synthetic corpus without making any external API calls. The sample behaves like a normal editable project: your changes persist, and deleting it before choosing Explore sample project again restores the bundled dataset. A sample project created by an earlier version receives the bundled search strategy when the database is migrated (alembic upgrade head, which the Docker entrypoint runs) or the next time you choose Explore sample project; searches you ran yourself are untouched.

Optional: Create a free NCBI API key and add it to .env as BIBMEDED_PUBMED_API_KEY=your_key. BibMedEd then queries PubMed at 10 req/s instead of 3 req/s; BIBMEDED_PUBMED_RATE_LIMIT overrides the rate. Lens.org searches require a Lens Scholarly API token in BIBMEDED_LENS_API_KEY.

CLI only, no Docker: pip install bibmeded (Python 3.12+, PyPI), then bibmeded search "medical education" --dry-run to estimate result counts from a terminal or notebook. See Scripting.

See the full Self-Hosting Guide for configuration, reset, and dev setup. Stuck on a port clash, a PubMed rate limit, a missing Lens key or a search that never starts? See Troubleshooting & FAQ.

Deploy to Cloud

The Blueprint provisions PostgreSQL, Redis, FastAPI, Celery, and the Next.js frontend on Render.com's free tier. The frontend-to-API wiring of this one-click path has not yet been verified end to end; see #93 before relying on it.

Security model: BibMedEd has no built-in authentication. It is a single-tenant tool meant for one research team, and every API endpoint trusts the numeric ID in the URL with no notion of an "owner" — there is no login, no per-project access control, nothing. The one-click deploy above provisions a publicly reachable *.onrender.com URL with zero credentials required, so anyone who has (or guesses) that link can list every project, export or bulk-edit their data, or delete them. Read the Security model section of the Self-Hosting Guide before deploying publicly, and put an IP allowlist or auth proxy in front — or just keep it on localhost / a private network, which is how BibMedEd is designed to be run.

Write Your Own Adapter

Adding a bibliographic database starts with one focused Python module; richer APIs need more mapping and pagination code:

from bibmeded.adapters.base import BaseSourceAdapter, RawRecord, SearchResponse

class ScopusAdapter(BaseSourceAdapter):
    name = "scopus"
    display_name = "Scopus"
    requires_api_key = True

    async def search(self, query, **kwargs) -> SearchResponse:
        # Hit Scopus API, return IDs + count
        ...

    async def fetch(self, ids) -> list[RawRecord]:
        # Map Scopus JSON to RawRecord
        ...

Drop it in bibmeded/adapters/, restart the worker, and it appears in the search UI automatically. The adapter registry handles discovery, and cross-database deduplication works via the external_ids field.

See the full Writing Adapters guide with RawRecord field reference and an annotated OpenAlex walkthrough.

Community & Roadmap

Want to help shape BibMedEd?

• Start contributing: See CONTRIBUTING.md
• Request or claim work: GitHub Issues
• Ask questions or discuss major ideas: GitHub Discussions
• Use in research and cite the project: See Citation

Looking for a first task? Pick an open item from GOOD_FIRST_ISSUES.md, comment on its issue, and ask to be assigned.

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, D3.js, Tailwind CSS
Backend	FastAPI, SQLAlchemy 2.0, Pydantic
Workers	Celery with Redis broker
Database	PostgreSQL 16
Analysis	NetworkX, scikit-learn, scipy
Deployment	Docker Compose, Render.com Blueprint

Citation

If you use BibMedEd in your research, please cite:

@software{bibmeded,
  title   = {BibMedEd: Bibliometric Analysis Platform for Medical Education},
  author  = {Akillioglu, Ata},
  year    = {2026},
  doi     = {10.5281/zenodo.20404321},
  url     = {https://doi.org/10.5281/zenodo.20404321},
  note    = {Concept DOI — resolves to latest version. For a specific release, see Zenodo.}
}

Contributing

Contributions are warmly welcome. A focused adapter is often the fastest path to a high-impact first PR; complete submissions include fixture-based tests and source-specific documentation.

• Read the Contributing Guide for setup, code style, and PR flow.
• Pick and claim a starter task from GOOD_FIRST_ISSUES.md.
• Report bugs or request features with the issue templates.
• Improve docs — PRs to docs/ auto-deploy to GitHub Pages on merge.

By contributing you agree to abide by our Code of Conduct. Security issues should be reported via the process in SECURITY.md.

Contributors

Thank you to everyone who has shipped code to BibMedEd:

Contributor	Contribution
@BaygeldiAza	Dry-run and full CLI search pipeline (#46, #52)
@landon-personal	CLI source and network error handling (#50)
@DYNOSuprovo	bibmeded sources command (#71)
@Sandro850	bibmeded --version (#72)

License

MIT — use it freely in academic and commercial projects.

Star history