title	ChemPath
emoji	🧪
colorFrom	blue
colorTo	green
sdk	docker
pinned	false
license	mit

ChemPath

Turn a list of organic conversions into a graph you can explore.

Search compounds, choose a start and target, and compare stepwise routes through a small teaching dataset. A runnable local learning archive with React and FastAPI.

Try a conversion · Inside the graph · Dataset and development

The running app: Ethene → Ethanoic acid returns four routes in this dataset. Select a Path button to compare alternatives and inspect each step.

Make the connections visible

Find a compound	Compare routes	Inspect each step
Search names, formulas and aliases; acetic finds Ethanoic acid.	Explore up to ten loop-free routes, with a maximum of six steps.	See the dataset's reagents, conditions and mechanism text alongside the compound sequence.

The checked-in example contains 21 compounds and 23 reaction variants. Route order uses a simple teaching_cost score. It does not calculate yield, safety, feasibility or an optimal laboratory synthesis. The dataset is incomplete and has not been verified as an NCERT reaction catalog; use a textbook or instructor to review its chemistry. NCERT textbooks are a reference for further study.

See the actual alias search

Try a conversion

With Docker installed, from this repository:

docker compose up --build

Open http://localhost:5173 → Pathway Finder. Choose Ethene as the starting compound and Ethanoic acid as the target, then select Find Pathway. Switch to Path 2 to inspect an alternative.

The Compounds page searches names, formulas and aliases. The API explorer is at http://localhost:8000/docs; http://localhost:8000/health reports the loaded graph size. Both services are bound to loopback. No account, API key or external database is required. Stop with docker compose down.

Inside the graph

flowchart LR
  JSON[Validated reactions.json] --> Graph[Directed graph with parallel reaction variants]
  Graph --> API[Read-only FastAPI service]
  API --> Browser[React compound browser and path finder]
  Browser --> Choice[Choose a route and inspect its steps]

Loading

Compounds use stable IDs; formulas and aliases are searchable display data. Different reagents can connect the same pair of compounds, so each reaction variant remains a distinct edge. Search excludes cycles, caps depth and ranks routes by the sum of their teaching costs.

This small JSON graph replaces the prototype's unavailable external database. It makes the demonstration repeatable without suggesting that the chemistry dataset is complete or ready for laboratory use.

Dataset and development

Run without Docker and check changes

Use Python 3.13 and Node.js 22.12+ or 24. In a Python virtual environment, from the repository root:

python -m pip install -r requirements-dev.txt
uvicorn main:app --reload --port 8000

In another terminal, from the repository root:

cd frontend
npm ci
npm run dev

Backend ALLOWED_ORIGINS is a comma-separated list of frontend origins. Frontend API_PROXY_TARGET selects the development API target; by default it uses http://127.0.0.1:8000.

From the repository root, in the Python environment:

python -m unittest discover -s tests -v

From frontend/:

npm run build
npm test

The backend checks dataset validation, search aliases, parallel reactions and bounded routes. Frontend tests exercise route-result handling; the build also checks TypeScript. CI runs both sides. Production runtime dependencies alone do not include the test HTTP client; install requirements-dev.txt for the backend checks.

For frontend dependency changes, retain the lockfile and run npm audit, the build and the tests from frontend/ before submitting the update.

Extend the teaching dataset

Edit data/reactions.json. Compounds and reactions need stable IDs, and each reaction needs a teaching_cost from 1 to 3. The service validates the dataset at startup and exposes no write API. See the graph implementation and tests for the current contract.

Add an individually checked chemistry source and review new reactions with a qualified instructor before claiming curricular coverage. Tests validate data structure and traversal, not the chemistry itself. For an issue, include the compound IDs, expected route and source in Issues.

Why keep the archive runnable?

The prototype explored a useful graph-modeling problem: formulas are poor identifiers, alternative reagents matter, and unconstrained route search quickly becomes misleading. Keeping a small integrated app makes those lessons inspectable.

The original standalone interface is preserved in chempath-frontend. This repository contains the runnable integrated version. The former hosted deployment is no longer maintained; no public deployment is advertised. MIT license.