User documentation

User documentation

Why AssayLink exists, where it sits in the assay landscape, and how scientists, stewards and project teams use it.

Mission

AssayLink is an AI-assisted platform for discovering, authoring, governing and reviewing reusable assay definitions in Pharma R&D. It is the intended successor to the Test Definition Portal (TDP): the place where an assay is defined once, in governed language, so later systems can capture and analyse results against that definition.

Today definitions live as ad-hoc JSON, Excel and ageing tools. Metadata is missing or unstandardised, finding a relevant assay is slow, and there is little room for automation. A new portal by itself does not fix that. Stewardship and a controlled vocabulary are what make data consistent across labs and interoperable across PDE, Helix, RedLIMS and reporting systems.

When a project needs “a CYP3A4 induction assay in human hepatocytes”, AssayLink should already hold an approved, findable definition — not another spreadsheet rewrite of the same assay.

Three things are first-class:

1. Modular templates — reusable assay definitions with versions, not runs.
2. Controlled vocabulary — preferred terms, synonyms, hierarchy and ontology links, under a data steward.
3. Explained matching — a free-text need mapped to templates with reasons, so a project can link the right definition.

What AssayLink does not do

AssayLink governs reusable assay definitions. It does not store experimental execution data, raw instrument files, or processed results, and it does not replace LIMS, ELN, PDE or Benchling. Those systems remain the systems of record for work that was actually run; they validate entered data against AssayLink templates.

Personas

Core concepts (plain language)

• Assay Template — a reusable definition of an assay (not a run).
• Template Version — a snapshot of metadata; immutable once approved.
• Vocabulary / Term — a governed controlled list and its concepts (preferred label, synonyms, parents).
• Field — one piece of information an assay definition captures, such as “Assay format”, “Species” or “Target”. Every field an author fills in on a template is a field defined in the metadata model.
• Metadata Field Definition — the rules for one field: whether it exists, is mandatory, multi-value, which vocabulary feeds it, and which section shows it. Changing this changes the wizard — no code deploy.
• Metadata Section — a steward-named group of fields, such as Classification or Biological System / Materials. The authoring wizard pages by section.
• Metadata Rule — when/then logic over field keys: show, require, or restrict vocabulary terms (for example CYP induction requiring Cell System and restricting Expected Readout).
• Metadata Quality Score — completeness, vocabulary compliance and consistency with active rules. Not a score of experimental results.
• Project Assay Link — a project’s use of a template version plus project context. Still not a run.
• Suggested Term — a candidate value from AI or users; only a steward can activate it into the vocabulary.

Using the POC role switcher

In this proof of concept, authentication is mocked. The header shows a Role control with the role name (Assay Definition Owner, Data Steward, Project Team Member). Hover to see the demo user. Changing the dropdown switches immediately and lands on that role’s dashboard. In a real deployment this comes from Entra ID / ALB SSO and cannot be changed in the UI.

Continue to the full user guide with screenshots →

↑ Back to contents

User documentation

User guide

Screenshot walkthrough of every major screen, organised by persona. Switch the header persona to match the section you are reading.

App chrome (all personas)

Every page shares the same header: the AssayLink logo (home), a role-filtered navigation on one row, and (in the POC) the Role switcher on the right. The dropdown shows the role; hover for the demo user’s name. Changing it switches immediately. Links you are not allowed to use simply do not appear — and typing a forbidden URL shows a clear “not permitted” page.

Assay Definition Owner

Demo user: Dr Amelia Ostrowski. Creates and maintains templates through review.

Dashboard

Three columns: My draft templates, Awaiting steward review, and Recently approved. Drafts offer an Edit shortcut.

Template catalogue

Templates are grouped into functional areas (ADME / DMPK is populated; HTS, Safety, In Vivo tiles are greyed placeholders for future scope). Open a group to see templates; filters sit at the top.

Template detail

Shows metadata, status, versions, review history, the Metadata Quality Score, and actions (submit, edit draft when allowed). Vocabulary-backed values render as governed terms. AssayLink does not show experimental result values.

Authoring wizard (new template)

A metadata-driven wizard paged by steward-configured sections (Assay Identity, Classification, Biological System / Materials, Detection, Readouts / Endpoints, …). Fields, obligation and dropdown values come from MetadataFieldDefinition; conditional rules show or require extra fields (for CYP induction: Target, Cell System, Species, Detection Type). Expected readouts are vocabulary categories, not measured values. A Metadata Quality Score updates as you fill. Hierarchy fields use the vocabulary tree; AI autofill (when enabled) is visibly marked as suggested until accepted.

Edit draft

Owners can reopen drafts and “changes requested” versions. The template code is locked; metadata remains editable until submission.

Find an assay (matcher)

Describe an assay need in free text. The system extracts metadata (rule-based, optionally merged with an LLM), scores published templates, explains each match field by field, and names fields that active metadata rules still require. A Metadata Quality Score estimate is shown from the description — not from experimental results.

Data Steward

Demo user: Dr Sofia Lindqvist. Reviews templates and owns the semantic foundation (model + vocabulary).

Dashboard

Review queue

Lists submitted / in-review templates with the Metadata Quality Score (missing required fields, ungoverned values, rule warnings). Open a template to approve, reject, or request changes with comments and optional per-field notes.

Assay Definition Model

A field is one piece of information an assay definition captures — “Assay format”, “Species”, “Target”. Fields sit in steward-named sections (including Biological System / Materials). This screen is what the authoring wizard is generated from.

The knowledge model shows Assay Definition → sections → vocabularies → rules → quality. Section cards sit below. The field and vocabulary map shows scientific sections and fields on the left, vocabularies on the right, connectors for governed values. Conditional rules live under the Rules tab and the Conditional Rule Map.

Adding a field. Inputs marked * are required. The two settings that decide how the field behaves are:

• Data type — TERM means values must come from a governed vocabulary, so a vocabulary must be selected and the input type must be a SELECT, MULTISELECT or HIERARCHY_SELECT. Anything else (STRING, NUMBER, …) is entered freely.
• Section — which part of the assay definition model shows the field (for example Biological System / Materials). Fields added here immediately appear in the authoring wizard.

Retiring a field. Deprecate is the governed route: authors stop being offered the field, existing template values are kept so history stays readable, and the rules become read-only until the field is reactivated. Delete is only offered when no template has ever held a value for the field — it removes a mistyped or experimental field outright, and the audit entry survives the deletion.

Leave Applies to assay types unticked and the field applies to every assay type. Tick a branch and it only appears once an author selects that assay type or one beneath it — which is why a newly scoped field can look missing in the wizard until the assay type is chosen.

Conditional rules. Under the Rules tab, a steward writes when/then logic over field keys. The CYP induction rule is the demo: when Assay Type is CYP induction or a more specific type, require Target, Cell System, Species and Detection Type, and restrict Expected Readout to Fold Induction, Emax and NOEL. Hide / make-optional stay secondary. Rules never collect experimental numbers.

Vocabulary

Browse vocabularies, open a vocabulary to manage terms, synonyms, hierarchy and ontology mappings. Deprecate carefully; never delete history that templates rely on without a steward decision.

Suggested terms

AI and users may propose labels that are not yet governed. Only a steward can approve them into an active vocabulary term. This is the single gate for growing the terminology.

Change history

Project Team Member

Demo user: Tomas Berg. Starts from a MaRLay project (six-digit id), not from a blank matcher.

Dashboard and project list

Project detail and define assay

Open a project to see linked assays. “Define” starts a need description (high-level type + short text), runs matching pinned to that project, then lets you link a template version and add project-specific context.

Shared: catalogue and templates

All personas can browse the catalogue and open published templates. Creating, reviewing, and model edits remain role-gated.

Role gates

If you open a URL your role cannot use, AssayLink shows a clear forbidden page naming the capability and which role holds it.

Typical end-to-end scenarios

1. Author → review → publish: Owner creates a draft → submits → Steward reviews with comments → approves → Owner (or process) publishes / versions as needed.
2. Discover & link: Project member picks MaRLay project → describes need → selects recommended template → adds project fields → link.
3. Govern terminology: Matcher or author surfaces an unknown label → Suggested Term → Steward activates synonym or new term → future matches improve.
4. Evolve the model: Steward opens Assay Definition Model → changes a section, field or rule → wizard and Metadata Quality Score update immediately.

← Back to mission · Technical docs →

↑ Back to contents

Technical documentation

Technical documentation

For developers and coding agents: what AssayLink is, what is already built, and how to change it without breaking the product rules.

Agent brief (read this first)

Canonical project instructions also live in the repo root CLAUDE.md. Prefer this HTML pack for humans and offline export; keep CLAUDE.md as the short agent policy file.

What is implemented today

Non-negotiable engineering rules

• Layering: app/ → server/services/ → server/repositories/ → server/db.ts. Components never call Prisma.
• Domain types live in src/domain/, framework-free, with Zod.
• Metadata model is data — sections, fields, rules and vocabulary terms; never hard-code controlled values in UI components.
• AI only under src/server/ai/, Zod-validated, cannot activate vocabulary terms or approve templates.
• Auth checks only via src/server/auth/ (guardCapability / requireCapability).
• Build context is src/web/ — nothing the Docker image needs may live above that folder.
• Before claiming work done: npm run lint, npm run typecheck, npm test in src/web.

Repository map

ph-rnd-assaylink/
├── CLAUDE.md                 # Agent/project policy (short)
├── config.yml                # ONLY infra file to edit
├── terraform/                # DO NOT MODIFY (upstream)
├── docs/                     # Markdown ADRs & product notes (source material)
├── .github/workflows/ci.yml  # Our CI
├── docker-compose.yml        # Local Postgres
├── dev.sh                    # One-command local start
└── src/web/                  # Entire application (Docker build context)
    ├── prisma/               # Schema, migrations, seed
    ├── public/docs/          # THIS documentation (static HTML)
    ├── src/app/              # Routes, server actions
    ├── src/components/       # UI
    ├── src/domain/           # Types + Zod
    ├── src/server/           # services, repositories, ai, auth, integrations
    └── tests/                # unit, integration, e2e

Markdown under repo docs/ (ADRs, meeting notes) remains the historical design record. Prefer linking to those for deep decisions; this HTML site is the navigable export for users and agents.

Architecture → · Implementation detail → · How to continue development →

↑ Back to contents

Technical documentation

Architecture

One Next.js service, layered domain code, metadata and vocabulary as data.

Runtime shape

Browser
  │  /docs  → static HTML (public/docs)
  │  UI     → Server Components + server actions
  ▼
Next.js 15 (App Router)  —  ECS Fargate "web", port 3000
  ├── app/                 routes, actions
  ├── server/services/     business rules
  ├── server/repositories/ Prisma only
  ├── server/ai/           providers, extraction, scoring
  ├── server/integrations/ MaRLay client (mock today)
  └── domain/              Zod + types
  ▼
PostgreSQL (schema assaylink)

• /health — 200 without touching the DB (ALB health check).
• /api/readiness — DB-touching readiness for humans/dashboards.

Layering rules

Domain data model (summary)

• User — demo users with roles.
• Vocabulary / VocabularyTerm — governed terminology.
• MetadataSection — steward-named groups of fields (authoring pages by these).
• MetadataFieldDefinition — the assay metadata model as rows.
• MetadataRule — conditional show / require / restrict-term logic.
• AssayTemplate / AssayTemplateVersion — definitions + immutable snapshots.
• TemplateFieldValue — values for a version (term and/or text).
• TemplateReview — steward decisions and requested changes.
• SuggestedTerm — pending vocabulary candidates.
• ProjectAssayLink — project ↔ template version + context.
• ChangeLog — audit trail.

Full narrative: repo docs/domain-model.md and ADRs 0002, 0007–0010. Schema: src/web/prisma/schema.prisma. AssayLink does not store experimental execution data.

AI architecture

• Provider interface in server/ai/provider.ts.
• Implementations: mock (default), claude, azure-openai.
• Extraction: mock/rules first, optional LLM merge (metadata-extractor.ts), parse via parse-raw-extraction.ts.
• Scoring / ranking stays deterministic over governed terms (template-recommender.ts, scoring.ts).
• Unrecognised values → SuggestedTerm, never auto-activated.
• After ranking, the matcher runs the same metadata-rule evaluator as authoring and attaches rule-required gaps plus a Metadata Quality Score estimate.

See docs/adr/0005-ai-provider-abstraction.md and docs/ai-recommendation.md.

Authentication & authorisation

POC: signed cookie + role switcher (ENABLE_ROLE_SWITCHER). Pages: guardCapability. Mutations: requireCapability. Capability map in server/auth/roles.ts. Production path: ALB OIDC header → map groups to roles in current-user.ts only (docs/adr/0006-auth-strategy.md).

Deployment constraints

• Change infra only via config.yml. Never edit terraform/.
• Docker: docker build -f src/web/Dockerfile ./src/web — build context is the service folder.
• DATABASE_URL may be composed from POSTGRES_* parts at runtime (server/db-url.ts).

Architecture decision records

Source files: docs/adr/*.md in the repository root.

↑ Back to contents

Technical documentation

Implementation details

Concrete map of routes, services, seed data, and tests.

Run locally

./dev.sh              # Postgres, migrate, seed, next dev
./dev.sh --reset      # wipe DB then seed
./dev.sh --no-seed    # skip seed

App: http://localhost:3000. Docs: http://localhost:3000/docs/. Work only inside src/web for npm scripts.

Primary routes

Key server modules

Template lifecycle

Statuses and legal transitions live in domain/status.ts (DRAFT, SUBMITTED, IN_REVIEW, CHANGES_REQUESTED, APPROVED, PUBLISHED, REJECTED, …). Editable when isTemplateEditable is true (draft / changes requested).

Seed data

• Sources: src/web/data/seed-sources/*.json (examples, not the schema).
• PK In Vitro Stability.json is seeded as a Draft needing review (CIA-style block despite the filename) — source preserved verbatim.
• Field definitions, sections, rules and vocabularies: prisma/seed/data/.
• Seeded CYP induction rule requires Target, Cell System, Species, Detection Type and restricts Expected Readout to Fold Induction, Emax, NOEL.
• Users: owner, steward, project member with stable ids for demos.

Testing

CI: .github/workflows/ci.yml — lint, typecheck, unit tests, build.

This documentation pack

• Location: src/web/public/docs/ (served as /docs/index.html; bare /docs redirects there via next.config.ts).
• Export: zip/copy the folder; relative CSS/images work offline.
• Single-file export: assaylink-docs.html — every page plus base64 screenshots in one ~7 MB file, rebuilt with npm run docs:bundle (scripts/build-docs-bundle.mjs). It re-assembles the per-page HTML, so prose is never duplicated.
• Refresh screenshots (app up + seeded): npm run docs:screenshots → scripts/capture-docs-screenshots.mjs. Run docs:bundle afterwards so the download matches.

↑ Back to contents

Technical documentation

Continuing development (agent playbook)

Instructions for a third-party coding agent picking up this repository cold. Scope, constraints, and safe next work.

How an agent should work here

1. Read CLAUDE.md and this page before large edits.
2. Treat meeting notes (docs/meeting-notes.md) and the product brief as product-context authoritative for workflow and scope.
3. Prefer changing data (sections, field definitions, rules, vocabulary, catalogue groups) over hard-coding UI enums.
4. Keep AI behind server/ai/; validate with Zod; route new terms to SuggestedTerm.
5. Put business rules in services; Prisma only in repositories.
6. Add unit tests for domain logic you touch; run lint, typecheck, and tests before reporting completion.
7. Do not modify terraform/. Infra changes go through config.yml only.
8. Application code that must ship in the container belongs under src/web/.

Good next increments (examples)

• Wire real ALB OIDC into current-user.ts without changing call sites of requireCapability.
• Replace MaRLay mock with HTTP while keeping the same client surface.
• Add further sections (operational metadata, assay parameters, protocol) via seed + field definitions — avoid schema redesign for simple fields. FUTURE sections already reserve protocol, instruments and data outputs.
• Expand catalogue groups with real templates beyond ADME when sources exist.
• Improve LLM extraction prompts / merge policy; keep ranking deterministic.
• Richer ontology mapping UX; bulk import of terms with steward review.
• Keep docs screenshots current after major UI changes (npm run docs:screenshots).

Do not

• Build a separate frontend/backend split without a new ADR.
• Let the LLM approve templates or activate vocabulary terms.
• Store execution/run data, raw instrument files or processed results in AssayLink tables.
• Collect experimental numbers (Fold Induction of 12, Ct, peak area) as metadata fields — those names are expected-readout terms.
• Put reusable subtypes in the primary demo UX — use Template Version and Project Assay Link.
• Hard-code assay format/type options in React components.
• Put package.json or Prisma above src/web/.
• Claim “done” without lint/typecheck/tests when you changed code.

Definition of done (code change)

cd src/web
npm run lint
npm run typecheck
npm test
# optional: npm run test:e2e
# optional: npm run docs:screenshots   # if UI changed meaningfully

Domain language (use these names)

← Technical hub · User guide

↑ Back to contents