> For the complete documentation index, see [llms.txt](https://docs.neurolabai.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurolabai.io/engineering-and-scientific-assurance/system-architecture.md).

# System Architecture

Neurolab separates the user interface, request routing, route-specific inference, governed graph data, report assembly, and optional language-model explanation. Each layer has a different responsibility and trust boundary.

## End-to-end flow

```mermaid
flowchart LR
    User["Researcher"] --> App["Neurolab web application"]
    App --> Routes["Application request routes"]
    Routes --> Service["Inference and report service"]
    Service --> Router{"Input route"}
    Router -->|"KG-resident name"| Known["Known-compound B0 ensemble"]
    Router -->|"SMILES or supplied receptors"| Novel["Structure retriever and mechanism reasoner"]
    Known --> Compose["Structured report composition"]
    Novel --> Compose
    Model["Predictive-model release"] -.-> Known
    Facts["Facts-and-evidence release"] -.-> Known
    Facts -.-> Novel
    Facts -.-> Compose
    Compose --> Report["Versioned report, reliability, and support"]
    Report --> Views["Report, inspector, explorer, raw data, chat, graph, and brain"]
    Report -.-> LLM["Report-grounded explanation"]
    LLM -.-> Views
```

## Application boundary

The browser communicates through application-owned routes. This allows the application layer to validate input, present streaming progress, translate errors, and ground follow-up questions without exposing service topology as the user-facing contract.

Section Inspector and Data Explorer read an existing report; neither creates a second prediction or changes the canonical ranking. Data Explorer resolves natural language to a structured, bounded action over supported report sections and candidates. It does not execute SQL, arbitrary paths, or mutations.

## Route boundary

The route decision is a scientific boundary, not merely a performance optimization.

* **Known compounds** run against the transductive v43.262 B0 ensemble. The query must resolve to a compound represented by the model and graph release.
* **Novel structures** do not execute B0. They use separately packaged chemistry-to-receptor, retrieval, and mechanism artifacts.
* **Caller-conditioned structures** use the novel-route machinery while keeping user-supplied receptor assumptions explicitly attributed to the caller.

Validation from one route does not transfer automatically to another.

## Model and facts release boundary

Predictive checkpoints and facts-and-evidence data are versioned independently. The architecture can preserve the v43.262 predictive model while using a separately released facts-and-evidence package for identity resolution, evidence coverage, receptor context, and report support. v44.16 remains a candidate until a served report or release announcement identifies it as active.

This separation allows provenance and evidence quality to improve without silently changing learned model scores. Every exported report should retain both release identities.

## Knowledge-graph boundary

One governed graph lineage supports several projections:

* a checkpoint-bound message-passing projection for the known-route GNN;
* compact artifacts for structure retrieval and reasoning;
* response-safe facts, evidence records, and support graphs; and
* reference layers that are not model inputs.

The Knowledge Graph Explorer receives a report-local artifact rather than the complete graph. Provenance, license, support scope, filters, coverage, and truncation determine what can appear.

## Report and evidence boundary

Report composition brings together outputs with different origins. A value can be model-generated while its support contains measured facts, derived relationships, or contextual paths. Evidence state and support scope must remain visible after composition.

When provenance, relation direction, or release identity cannot be resolved safely, the system should leave the record unavailable rather than infer a stronger claim.

## Language-model boundary

The conversational layer runs after the structured result. It can explain attached fields and navigate the report, but it is not the source of model rankings, graph facts, reliability states, or release identity.

## Developing account-owned state

Accounts, preferences, Workbenches, Molecular Portfolios, and Data Studio introduce a separate state layer around reports. Their purpose is to organize and compare research artifacts. They do not change the scientific result stored in those artifacts, and their availability remains in development.

## Failure behavior

The architecture favors explicit boundary states:

* unresolved names can return `needs_smiles` without a report;
* unavailable fields remain empty, null, omitted, or withheld;
* bounded section queries cannot invent candidates or modify scores;
* low-applicability structure queries can abstain;
* unrecognized receptor genes can be disclosed;
* unsupported graph records remain unavailable; and
* an assistant answer must not invent a missing report field.

These states protect interpretation and should be retained in downstream exports.

Next: [Model Inference](/engineering-and-scientific-assurance/model-inference-overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.neurolabai.io/engineering-and-scientific-assurance/system-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.