Airmid Domain — Architecture

Airmid — Evidence-Based Phytotherapy and Botanical Intelligence Platform

Airmid is a scientific platform spanning the complete knowledge stack for evidence-based herbal medicine. Named after the Celtic goddess of herbalism and healing, the domain brings rigorous scientific methodology to natural product medicine — bridging traditional ethnobotanical knowledge through modern pharmacological science to clinical decision support and regulatory compliance.

The problem Airmid solves is fundamental: herbal medicine exists at the intersection of millennia of traditional knowledge and cutting-edge computational science, but no unified platform integrates them. A clinician asking whether a patient's herbal supplement is safe with their warfarin needs a system that understands CYP450 enzyme kinetics, reads current clinical trial evidence, respects ethnobotanical context, and meets regulatory reporting standards — all at once. Airmid is that system.

The domain is a pure library domain with no standalone service applications. It comprises 19 libraries under libs/airmid/, each covering a distinct scientific discipline, with no apps/airmid/ or services/airmid/ directories. These libraries are consumed by other applications in the Oshun ecosystem rather than running independently.

Domain Purpose#

Airmid is organized around scientific disciplines rather than application concerns. Each library represents a coherent scientific module with its own domain data, algorithms, and evidence base. This design reflects the underlying reality of phytotherapy science: drug-herb interactions (a clinical concern), molecular docking (a computational chemistry concern), and IUCN conservation status (an environmental concern) are genuinely separate disciplines requiring separate expertise — not aspects of a single "herbal product" record.

Library Organization#

The 19 libraries are arranged in layers from scientific foundation to clinical application. The layout below shows the path of a library (core) to its platform function, along with the breadth of each module.

libs/airmid/
├── core/             # Foundation: branded IDs, enums, taxonomic classification, botanical
│                     # names, dosage guidelines, 15 domain entity classes, 8 error classes,
│                     # 13 domain event types, reference-data constants, validation helpers
│
├── ethno/            # Ethnobotanical knowledge — TCM, Ayurveda, Unani, African TM, Indigenous
│                     # Americas, cross-system correlation
│
├── phytochem/        # Computational phytochemistry — 55-entry natural-products compound
│                     # database, molecular properties (logP, TPSA, QED, Fsp3), drug-likeness
│                     # (Lipinski, Veber, Ghose, Egan, Muegge), ADMET, toxicity, 3D structure,
│                     # metabolite prediction
│
├── evidence/         # Evidence database — ClinicalTrials.gov integration, systematic reviews,
│                     # GRADE grading, effect sizes, NNT/NNH, forest plot data
│
├── interactions/     # Drug-herb CDS — 80+ interaction entries, CYP450 PK, transporter and PD
│                     # interactions, severity tiers, quantitative inhibition prediction
│
├── docking/          # Computational CADD — AutoDock Vina scoring, binding site detection,
│                     # virtual screening, PAINS filtering, QSAR, molecular dynamics
│
├── network/          # Network pharmacology — target identification, PPI networks, pathway
│                     # enrichment (KEGG), GO analysis, synergy prediction
│
├── formulation/      # Formulation science — synergy analysis (Chou-Talalay, Bliss, Loewe, HSA),
│                     # extraction chemistry, stability prediction, bioavailability enhancement
│
├── microbiome/       # Microbiome pharmacology — prebiotic effects (45+ entries), metabolite
│                     # production (30+ metabolites), dysbiosis correction (18 patterns)
│
├── precision/        # Precision herbal medicine — CPIC pharmacogenomics (9 CYP450 genes),
│                     # Activity Score, genotype-response database (48 entries)
│
├── quality/          # Quality control — DNA barcoding (Needleman-Wunsch), spectroscopic
│                     # fingerprinting, chromatographic profiling, pharmacopoeial compliance
│
├── safety/           # Safety and toxicology — WHO-UMC causality, Naranjo ADR, RUCAM,
│                     # hepatotoxicity (25+ herbs), nephrotoxicity, special populations (40+ herbs)
│
├── regulatory/       # Regulatory affairs — pharmacopoeia compliance (USP, PhEur, BP, JP, ChP, IP),
│                     # EMA/HMPC, FDA/DSHEA, global jurisdiction mapping, labeling requirements
│
├── sustainability/   # Conservation biology — IUCN (60+ species), CITES, FairWild, MSY,
│                     # cultivation data (35+ species), environmental LCA footprint
│
├── ml/               # AI/ML — biomedical NLP (200+ herb patterns), MPNN for molecular
│                     # properties, SMILES Transformer, TransE KG embeddings, RAG Q&A
│
├── vision/           # Computational botany — leaf analysis (120+ species), flower analysis
│                     # (60+ species), bark analysis (50+ trees), Bayesian multi-organ matching
│
├── clinical/         # Clinical integration — FHIR R4, LOINC codes (30+), SNOMED CT herbs (20+),
│                     # ICD-10-CM conditions (25+), CDS Hooks, interaction alerts at point of care
│
├── api/              # External bioinformatics connectors (10 databases: PubMed, PubChem, ChEMBL,
│                     # UniProt, STRING, KEGG, DrugBank, ClinicalTrials.gov, WHO VigiBase, Natural
│                     # Medicines), 8-pipeline ETL framework, OpenAPI 3.1 spec (44 endpoint
│                     # definitions), SMILES/SMARTS utilities, multi-format export and reporting
│
└── database/         # PostgreSQL schema — Knex.js migrations (17 tables, 5 materialized views,
│                     # 35 enum types) and Zod schema definitions for all domain entities

Total: 19 library projects (0 applications, 0 standalone services).

Scientific Domain Architecture#

The layers below move from foundation to application. Data flows upward: the core and database libraries provide shared types and persistence scaffolding; the data integration layer feeds live external knowledge; the scientific layers analyze and synthesize that knowledge; and the clinical layer applies it to patient-specific decisions.

┌────────────────────────────────────────────────────────────────────┐
│  CLINICAL AND DECISION SUPPORT LAYER                               │
│  @airmid/clinical · @airmid/interactions · @airmid/safety         │
│  @airmid/precision · @airmid/regulatory                           │
├────────────────────────────────────────────────────────────────────┤
│  SCIENTIFIC ANALYSIS LAYER                                         │
│  @airmid/docking · @airmid/network · @airmid/formulation          │
│  @airmid/microbiome · @airmid/phytochem                           │
├────────────────────────────────────────────────────────────────────┤
│  KNOWLEDGE SYNTHESIS LAYER                                         │
│  @airmid/evidence · @airmid/ml · @airmid/vision                  │
│  @airmid/ethno · @airmid/sustainability · @airmid/quality         │
├────────────────────────────────────────────────────────────────────┤
│  DATA INTEGRATION LAYER                                            │
│  @airmid/api (PubMed, PubChem, ChEMBL, UniProt, STRING, KEGG,    │
│  DrugBank, ClinicalTrials.gov, WHO VigiBase, Natural Medicines)   │
├────────────────────────────────────────────────────────────────────┤
│  FOUNDATION                                                        │
│  @airmid/core · @airmid/database                                  │
└────────────────────────────────────────────────────────────────────┘

Core Design Patterns#

1. Evidence Hierarchy#

All claims in Airmid are associated with an evidence level. Rather than treating a centuries-old traditional remedy the same as a double-blind RCT result, the platform grades every assertion according to the quality of evidence behind it. The hierarchy, from strongest to weakest, is:

1. GRADE High — Multiple high-quality RCTs with consistent results
2. GRADE Moderate — RCTs with limitations, or strong observational evidence
3. GRADE Low — Observational evidence with limitations
4. GRADE Very Low — Case reports, in vitro, or traditional use only
5. Preclinical — Animal or cell studies only
6. Traditional Use — Ethnobotanical evidence without clinical data

Every dosage guideline, interaction entry, and safety assessment is tagged with an evidence grade. Clinical decision tools filter and present information according to the applicable evidence level, so a clinician sees high-certainty evidence prominently and lower-certainty evidence in appropriate context.

2. Pharmacological Reductionism and Systems Thinking#

Airmid integrates two complementary pharmacological philosophies that have historically been in tension:

• Reductionist (@airmid/phytochem, @airmid/docking, @airmid/interactions): Single compound, single target. Identify active compounds, predict their ADMET profiles, model their receptor interactions, and check their drug interaction potential.

• Systems thinking (@airmid/network, @airmid/microbiome): Whole herb, whole system. Network pharmacology models the herb as a multi-compound mixture that modulates biological networks. Microbiome pharmacology accounts for gut microbial transformation of herbal compounds — the same compound can produce entirely different downstream metabolites depending on an individual's gut microbiome composition.

@airmid/formulation bridges these two philosophies by modeling how combinations of compounds in a formula interact (synergy, antagonism) and how the extraction method and delivery form affects bioavailability.

3. Separation of Scientific Knowledge and Clinical Application#

Scientific knowledge (compound databases, pharmacological data, evidence base, ethnobotanical knowledge) lives in domain libraries and is never hard-coded with patient-specific logic. Clinical application (@airmid/clinical, @airmid/interactions) applies this knowledge in patient context — taking patient-specific factors (current medications, conditions, genetic profile) as inputs and producing patient-specific recommendations as outputs.

This separation means the scientific database can be updated independently of the clinical application logic. A new drug-herb interaction discovered in a clinical trial can be added to @airmid/interactions without touching @airmid/clinical.

4. Real Data Sources Only#

Every external data source in @airmid/api uses real, documented API endpoints (10 databases — see EXTERNAL_DATABASE_CONFIGS) with correct URL structures, authentication, rate limiting, and response parsing. The ETL pipeline framework defines 8 scheduled pipelines (PIPELINE_DEFINITIONS) and 18 transformation rules for keeping the Airmid knowledge base current; the framework provides the extraction/transformation/load functions and scheduling computation, while the runtime scheduler is supplied by the consuming application. No mock or placeholder data is used for scientific reference data.

5. Computational Tools in TypeScript#

Core computational algorithms — molecular property calculation, drug-likeness assessment, AutoDock Vina scoring, Needleman-Wunsch sequence alignment, and Bayesian classification for plant identification — are implemented in TypeScript rather than relying on external computational chemistry servers. This makes the libraries deployable without external chemistry tooling dependencies, while remaining open to integration with RDKit or other tools via Python subprocess when higher fidelity is needed.

Library Dependency Graph#

In the current code each library is largely self-contained — every library defines its own types.ts rather than importing a shared type surface. The actual cross-library imports under libs/airmid/ are minimal:

@airmid/evidence   → @airmid/core
@airmid/docking    → @airmid/api
@airmid/ml         → @airmid/api   (declared in ml/package.json as workspace:*)
@airmid/phytochem  → @airmid/api

@airmid/core       (no @airmid imports)
@airmid/database   (no @airmid imports — does not import @airmid/core)
@airmid/api        (no @airmid imports)

@airmid/clinical, @airmid/interactions, @airmid/network, @airmid/precision,
@airmid/safety, @airmid/formulation, @airmid/microbiome, @airmid/quality,
@airmid/regulatory, @airmid/sustainability, @airmid/vision, @airmid/ethno
                   (no @airmid imports — each is fully self-contained)

Only @airmid/ml declares an internal dependency in its package.json (@airmid/api); the @airmid/api import seen in @airmid/docking and @airmid/phytochem is not declared in their package.json files. The foreseen layering — clinical consuming interactions/safety/evidence, etc. — is not yet wired through code imports.

Dependencies on Other Oshun Domains#

The Airmid libraries currently import no other Oshun domain packages — there are no @sophia/* or shared @oshun/* imports anywhere under libs/airmid/. The integrations below are planned, not yet wired through code.

Position in the Oshun Ecosystem#

The boundary between Airmid and Sophia exists because Sophia owns the general knowledge graph infrastructure (entity linking, research corpus management, cross-domain ontology) while Airmid owns the domain-specific phytotherapy algorithms and curated databases. Data would cross this boundary in both directions: Airmid would contribute structured herb-compound-target triples and curated clinical evidence to Sophia's knowledge graph, while Sophia's research corpus and semantic search would enhance Airmid's evidence synthesis and Q&A capabilities.

Airmid's @airmid/core events module (AirmidEventType, createAirmidEvent) builds typed domain events, but there is no event-bus binding in the domain today. When shared infrastructure is wired in, these events (species registration, interaction discovery, adverse event reporting, evidence grade changes) will flow to other Oshun wellness or health features via the shared event bus.

Build and Test Configuration#

• Build executor: @nx/js:tsc
• Test executor: @nx/vite:test (Vitest)
• Tags: scope:airmid, type:lib, layer:domain

When Nx is unavailable (for example, due to duplicate project detection from worktrees), use these direct invocations:

# Type check a library
cd libs/airmid/<library> && npx tsc --noEmit

# Run tests
cd libs/airmid/<library> && npx vitest run

# Run all airmid tests
npx vitest run libs/airmid/

Test Coverage Expectations#

Tests for each library are expected to verify three categories of correctness, not merely data flow:

• Domain-specific algorithms (not just CRUD) — e.g., GRADE scoring logic, CYP inhibition prediction, Naranjo score calculation, IUPAC property formulas.
• Known ground-truth values from literature — e.g., "hypericin molecular weight is 504.45 Da", "SJW + warfarin interaction is major severity". Tests that pass against hardcoded or random returns do not count.
• Edge cases relevant to patient safety — e.g., contraindicated interactions are never downgraded, null results do not cause exceptions.