I want to… Understand the science
Science
How microbial electrochemical systems work, what they produce, and how performance is measured.
MESSAI · Onboarding · about 6 minutes
From research papers to usable experiment records
MESSAI connects microbial electrochemical research, structured experimental data, and modeling tools. Start here to understand the science, find your workspace, and see what the platform can — and cannot — support.
01
Choose your starting point
Four routes. Each one ends with something small and concrete you can actually do — the full list is in 08.
I want to… Explore the research
Research workspace
Find papers, compare parameters, and inspect the evidence behind a result.
Open the research workspace Reference: Part II · 08 Pipeline →
I want to… Evaluate a process
Operator workspace
Explore reactor configurations and economic assumptions — with their limitations visible.
I want to… Work on the platform
Developer guide
Get access, understand the architecture, and complete a small verified corpus run.
Engineer quickstart Reference: Part II · Running the corpus →
02
How the science works
Every device in the taxonomy is a variation on one cell. What changes is the reaction you drive and the product you harvest.
Two facts govern everything downstream. The literature reports the same quantity in mutually incompatible ways — different normalisation bases, peak versus steady-state, undeclared reference electrodes — so raw numbers cannot simply be averaged. And the headline metrics are heavy-tailed across orders of magnitude, so a single number is almost always the wrong answer.
Full treatment: thermodynamics, kinetics, EET, the taxonomy →
03
What makes the data usable
A paper on its own is not data. It becomes usable when each measurement is attached to the conditions it was taken under, and normalised so it can sit beside a measurement from another paper.
The six stages a paper passes through
- 01 Acquire Discover candidate papers, resolve them to a DOI, fetch the PDF, store the bytes in R2, parse the text.
- 02 Screen Decide whether a paper is in scope, and classify it into the taxonomy before anything is extracted from it.
- 03 Extract Pull numeric values out of the paper with a snippet, a unit, an extractor version and a confidence.
- 04 Sync Land the extracted rows in the database with their provenance, and couple each to the conditions it was measured under.
- 05 Harmonize binding constraint Assign a canonical slug, normalise the unit to SI, and mark the row modelable — or not.
- 06 Promote Move verified rows up the environment ladder — local, then staging, then production — schema first, data second.
Six stages, named once. The reference parts also describe a five-step acquisition sub-sequence, an eight-step runbook and a five-layer architecture view — those are substeps and layers of these six, and each says so where it appears.
04
Where the work happens
One repository, four deployed zones, one PostgreSQL database behind them, and one object store for the PDF bytes. Only the API zone writes to the database.
messai-site
Site
Marketing, learning and legal pages. Astro.
messai-ai
Web
Research, papers, parameters, admin. The only zone with cross-zone rewrites.
messai-lab
Lab
The simulator, reactor models and 3D.
messai-api
API
Every route handler. The only zone that writes to the database.
The schema behind them carries 120 Prisma models, counted on
development on 2026-09-12.
The interactive architecture model, the schema browser and the package inventories →
05
What the corpus holds
Four different counting units, so these are cards and not a funnel: papers with extracted rows outnumber papers with a stored PDF, because legacy cohorts were imported without one. Each card names what it counts, where it was measured, and when.
Measured 23,579 Papers in the corpus ResearchPaper rows not soft-deleted. Staging · 2026-09-08 Measured 7,598 Papers with a stored PDF Papers whose pdfHash is set, i.e. the bytes are in R2. Staging · 2026-09-07 Measured 199,896 Extracted value rows ExtractedParameterData rows across all four extractors, legacy cohorts included. Staging · 2026-09-07 Measured 31,924 Rows usable for modelling Rows with a canonical slug, an SI-normalised value, and applicable_to_modeling set. 16% of the extracted rows. Staging · 2026-09-07
Re-measure before quoting any of these. A number without its database and its date is not a number.
06
What this supports, and what it does not
Deployment and validation are separate. A feature can be available and unvalidated; a number can be measured on staging and not yet deployed. The vocabulary below is used the same way everywhere on this page.
- Available
- Deployed and usable now. Says nothing about whether it is validated.
- Measured
- A number that was measured, on a named database, on a named date.
- Experimental
- Built and reachable, but its output is not yet trusted for a decision.
- Blocked
- Cannot proceed until a named dependency lands. The blocker is stated.
- Planned
- Scheduled, not started. Lives on the roadmap, not in the product.
- Deprecated
- Superseded. Kept only so old artifacts remain readable.
- Available
Search 23,579 papers and inspect where any extracted number came from
Every value carries its source paper; about half also carry the verbatim snippet, with the extractor version and a confidence. Where the snippet is missing, the record says so rather than implying a quote.
- Available
Get a calibrated interval for a performance parameter
The served hierarchical priors report a 90% band whose measured coverage is 89–91%. It is honest and it is wide — 4.1 decades on power density.
- Blocked
Beat a class-median baseline on paper-disjoint held-out data
No. On the one paper-disjoint held-out set, 0 of 4 targets pass the ≥10% RMSE-reduction gate against a class×domain median; typical held-out error on power density is 0.80 dex (about ×6) for every model and baseline alike.
- Blocked
Model an arbitrary paper end-to-end from its PDF
Harmonization is the binding constraint: 16% of extracted rows are modelable. Acquisition has also been stalled since the last discovery run in May 2026, so recent literature is thin — 23% of visible 2025–26 papers have a PDF.
- Experimental
Turn a curated paper into CapEx, OpEx, LCOE and a GWP offset
The TEA and LCA chain runs, and its assumptions are inspectable. Treat the output as a structured argument about which assumptions dominate, not as a costed quote.
Withdrawn claim: “Extraction succeeds on ~75% of papers”. Published with no cohort, denominator or date. Per-extractor row and paper counts are on the Atlas; a success RATE is not currently measured. What is measured instead →
07
Decisions already made
These were argued and settled. The rejected options are recorded as history so the argument is not re-run — and, in the first case, so nobody picks up a fix that was explicitly ruled out.
How is the duplicate-ConditionSet defect fixed?
Decided
Collapse the duplicates first, then add @@unique([paperId, label]), then emit sets at sync time and reuse an existing set instead of creating one.
Because
The unique key already names `runId`, which the backfill never sets; Postgres treats NULLs as distinct, so the constraint never fires.
Rejected — do not run
Setting runId on the backfill. It makes each re-run legitimately distinct — the exact behaviour being stopped. Do not run it.
Which extractor runs in bulk?
Decided
Arm B — v2's flat transport with the v1.2 sub-prompt families ported onto it as separate flat calls. Measured on a 20-paper slice on 2026-09-10 (PR #902): 95% precision [92–98], 62% modelable, $0.05 per paper.
Because
v2's current prompt sourced 99 of 214 values from OTHER papers — reference lists and review tables — where arm B sourced 0 of 109. CMA v3 (Opus) recalls more but costs $0.93 per paper at 64% precision.
Rejected — do not run
v2's current prompt as-is (50% precision, and $0.16 per paper rather than the documented $0.05), CMA v3 for bulk, the three-pass variant, and resurrecting orchestrator.ts. Caveat that could reverse this: the gold set is LLM-adjudicated, not human-verified.
What classifies a paper first — regex or the title/abstract model?
Decided
Three writer tiers, in this order: free regex over everything, then the title/abstract classifier ONLY where primarySystemType is still NULL, then paid full-text extraction last.
Because
Each tier costs more than the one before it, and each only touches what the cheaper tier could not settle, so the order is a cost order rather than a confidence order.
Rejected — do not run
Running the classifier first over the whole corpus. Documented exception to the tier order: classify-paper-type.ts nulls primarySystemType for REVIEW and FUNDAMENTAL papers as leakage, and both other writers put it back — so the result depends on which ran last.
08
Your first task
Onboarding should end with the right next action, not with a finished reading list. Pick the one that matches your route.
- Science Read one performance figure and say which normalisation basis it uses — and why that makes two published numbers non-comparable. Start with the science →
- Research workspace Open one measurement and trace it back to the sentence in the paper it came from. Open the research workspace →
- Operator workspace Identify which single assumption moves one economic result the most. Open the lab →
- Developer guide Complete one three-paper smoke run and report which gates it passed. Engineer quickstart →
09
The reference library
Everything above is the summary. The detail lives on one page, the atlas, as five tabs — the full procedures, the commands and flags, the measured tables, and the incident history. Each subject has exactly one tab as its home.
- Part I · 17 sections · ~35 min Onboarding atlas The reference for the science (what an MES is, the taxonomy, thermodynamics, biofilm and EET, the metrics), plus access, acquisition tooling, priors, the held-out audit, the July 2026 week, the roadmap, the ranked gaps and a glossary.
- Part II · 11 sections · ~80 min Running the corpus Everything corpus: commands, flags, gates and troubleshooting for an actual run — the state of each pipeline layer, the fixes that must land before money is spent, the extraction schema, the coupling defect — plus the pipeline reference, categorisation and ontology, and how the corpus grows, with every corpus diagram.
- Part III · 10 sections · ~45 min Platform map The interactive UML model of the infrastructure, the four Vercel zones, the Prisma schema, the 3D and P&ID stacks, the open-source packages, and the dependency order between the gaps.
- Part IV · 5 sections · ~25 min Operators & public claims The TEA and LCA chain that turns a curated paper into CapEx, OpEx, LCOE and a GWP offset; the gaps published on /proof; and the backtest and multi-class runbooks behind the accuracy claims.
- Part V · 2 sections · ~10 min P&ID symbol library The full ISA-5.1 symbol plate the reactor sheets are drawn from, and the rules that keep a drawn sheet from claiming more than the spec knows.
docs/onboarding on GitHub — the markdown these parts were built from →