Airmid Domain — Technical Specifications

Airmid — Evidence-Based Phytotherapy and Botanical Intelligence Platform

This document specifies what is actually implemented in the Airmid domain. Airmid is a pure library domain: 19 TypeScript libraries under libs/airmid/, with no applications and no standalone services. Every type, schema, enum, event, endpoint definition, and database table described below is traceable to source under libs/airmid/.

The document is organized to mirror how the code layers. It starts with the shared foundation (@airmid/core) — the types, entities, errors, events, and constants that every other library builds on — then covers the database schema, the API layer, and finally a summary surface for each scientific library. Reading this document alongside features.md gives a complete picture: features.md explains what each module does and why; this document specifies the exact types, enum values, table names, and function signatures involved.

The canonical planning backlog is Phase 35 of TODOS.md (35.1–35.20).

1. Library Inventory#

All 19 libraries are private workspace packages (version: 0.1.0, type: module, source entry ./src/index.ts). Every package depends on zod (catalog). @airmid/database additionally depends on knex and (dev) uuid. @airmid/ml additionally depends on @airmid/api (workspace:*). All packages carry vitest as a dev dependency.

Every Nx project carries the tags scope:airmid, layer:domain, type:lib.

2. Core Foundation Types (@airmid/core)#

Defined in libs/airmid/core/src/types.ts. All branded ID types use a Brand<T, B> nominal-typing helper and are validated against a UUID v4 pattern. Branded types catch a common class of bug where a CompoundId is accidentally passed where a SpeciesId is expected — the TypeScript compiler rejects such assignments even though both are strings at runtime.

2.1 Branded ID Types#

The following ID types are used as foreign keys throughout all domain entities and events:

2.2 Chemical Identifier Types#

Chemical identity management requires strict format validation — a corrupted CAS number or InChIKey breaks cross-database linking. These types enforce the official format rules for each identifier:

2.3 Enumerations#

All enumerations are TypeScript enums with string values. They are used as column types in the database schema (§8) and as discriminants in entity computed properties throughout the domain. The full set of enums:

• TaxonomicRank — Kingdom, Phylum, Class, Order, Family, Genus, Species, Subspecies, Variety, Cultivar.
• CompoundClass — Alkaloid, Flavonoid, Terpene, Terpenoid, Phenol, Polyphenol, Tannin, Saponin, Glycoside, Coumarin, Lignin, Steroid, EssentialOil, FattyAcid, Amino, Carbohydrate, Vitamin, Mineral, Other (19 members).
• GRADEQuality — High, Moderate, Low, VeryLow.
• OxfordLevel — Level1a, Level1b, Level2a, Level2b, Level3a, Level3b, Level4, Level5 (Oxford CEBM, March 2009).
• StudyDesign — SystematicReview, MetaAnalysis, RCT, CohortStudy, CaseControl, CaseSeries, CaseReport, CrossSectional, InVitro, InVivo, ExVivo, Computational.
• EvidenceStrength — Strong, Moderate, Limited, Insufficient, Conflicting.
• InteractionSeverity — Contraindicated, Major, Moderate, Minor, Theoretical.
• InteractionMechanism — CYP450Inhibition, CYP450Induction, PGPInhibition, ProteinBindingDisplacement, PharmacodynamicSynergy, PharmacodynamicAntagonism, GIAbsorptionAlteration, RenalClearanceChange, Other.
• AdverseReactionType — Allergic, Hepatotoxic, Nephrotoxic, Neurotoxic, Dermatologic, GI, Cardiovascular, Respiratory, Hematologic, Endocrine, Other.
• CausalityAssessment — Certain, Probable, Possible, Unlikely, Conditional, Unassessable (WHO-UMC categories).
• DosageForm — Tincture, Decoction, Infusion, Capsule, Tablet, Extract, EssentialOil, Poultice, Salve, Syrup, Powder, Tea, Cream, Oil (14 members).
• DosageUnit — mg, g, mL, drops, cups, tablespoons, teaspoons.
• PreparationType — Aqueous, Ethanolic, Hydroethanolic, Supercritical, ColdPressed, SteamDistilled, Macerated, Fermented.
• IUCNStatus — NotEvaluated, DataDeficient, LeastConcern, NearThreatened, Vulnerable, Endangered, CriticallyEndangered, ExtinctInWild, Extinct.
• CITESAppendix — None, AppendixI, AppendixII, AppendixIII.
• Pharmacopoeia — USP, EP, BP, JP, CP, IP, WHO, ESCOP, CommissionE, HMPC.
• RegulatoryStatus — Approved, MonographPublished, TraditionalUse, DietarySupplement, Restricted, Banned, UnderReview.

2.4 Plain Interfaces#

The following plain interfaces are used as the raw-data input to entity class constructors (§3). Each has a corresponding Zod schema that validates the data at the boundary.

TaxonomicClassification#

Represents a complete Linnaean classification from kingdom down to species, with optional infraspecific ranks. All required string fields enforce .min(1).

Validated by TaxonomicClassificationSchema (Zod).

BotanicalName#

Captures both the formal binomial name (enforced by regex to require Genus species capitalization format) and the human-facing vernacular names and synonyms used across databases:

Validated by BotanicalNameSchema. binomial must match /^[A-Z][a-z]+ [a-z]+$/.

DosageGuideline#

Structured dosage data with range bounds and frequency, enabling comparison across traditional, clinical, and pharmacopoeial dose recommendations:

Validated by DosageGuidelineSchema.

CompoundProperties#

Captures the physicochemical descriptors used by drug-likeness filters and ADMET prediction. The Lipinski Ro5 fields are all required; TPSA and rotatable bonds are optional because they may not be available for all natural product structures:

Validated by CompoundPropertiesSchema.

StudyMetadata#

Fields: design (StudyDesign), sampleSize (number), blinding ('none' \| 'single' \| 'double'), allocation ('random' \| 'quasi-random' \| 'non-random'), optional allocationConcealment, intentionToTreat, attritionRate, effectSize, confidenceInterval ([number, number]), pValue.

InteractionRecord#

Fields: herb (string), drug (string), mechanism (InteractionMechanism), severity (InteractionSeverity), evidenceLevel (EvidenceStrength), description (string), optional cyp450Enzymes (string[]). This is the shape used by the COMMON_HERB_DRUG_INTERACTIONS constant and the core interaction helper functions.

3. Core Domain Entities (@airmid/core)#

Defined in libs/airmid/core/src/entities.ts. Each entity is a class wrapping a Readonly<…Data> raw-data interface, with constructor validation (throws plain Error on invalid input), computed getters, and a toJSON() serializer. There are 15 entity classes, each with a matching …Data interface. The computed getters are where domain logic lives — for example, ClinicalTrial.evidenceLevel derives an Oxford evidence level from the study design, blinding, and allocation fields.

3.1 BotanicalSpecies#

Constructed from BotanicalSpeciesData: id (SpeciesId), taxonomy (TaxonomicClassification), botanicalName (BotanicalName), description, nativeRegion (string[]), habitat, growthForm, plantPartsUsed (string[]), iucnStatus (IUCNStatus), citesAppendix (CITESAppendix), imageUrls (string[]).

Computed: binomialName, fullName, family, isEndangered, isCITESListed, taxonomicPath, plantPartsUsed. Methods: belongsToFamily(family), hasMedicinalUse().

3.2 PhytochemicalCompound#

Constructed from PhytochemicalCompoundData: id (CompoundId), name, iupacName, casNumber, smiles, inchiKey, molecularFormula, molecularWeight, logP, compoundClass, hydrogenBondDonors, hydrogenBondAcceptors, rotatableBonds, polarSurfaceArea.

Computed: molecularWeight, isLipinskiCompliant, drugLikenessScore (0–5, Lipinski Ro5 + Veber rotatable-bond extension), compoundClassDescription, hasValidCAS, hasValidSMILES, logPCategory. Method: isNaturalProduct().

3.3 ClinicalTrial#

Constructed from ClinicalTrialData: id (TrialId), title, registryId, studyDesign, phase, population, sampleSize, duration, intervention, control, primaryOutcome, results, conclusion, blinding, allocation, attritionRate, effectSize, pValue, confidenceInterval, journal, publicationDate, doi, speciesId.

Computed: isRCT, evidenceLevel (Oxford level from study design + blinding + allocation), sampleSizeCategory, hasStatisticalSignificance, qualityScore (composite 0–100), isBlinded, isRandomized, yearPublished. Method: meetsInclusionCriteria(minSampleSize, maxPValue).

3.4 EvidenceRecord#

Constructed from EvidenceRecordData: id, speciesId, condition, indication, gradeQuality, oxfordLevel, evidenceStrength, studyCount, supportingTrialIds (TrialId[]), summary, recommendation, lastReviewDate.

Computed: isHighQuality, recommendationStrength, needsMoreResearch, isOutdated (no review in > 5 years), studyCountCategory. Method: summarize().

3.5 DrugHerbInteraction#

Constructed from DrugHerbInteractionData: id (InteractionId), speciesId, drugName, drugClass, severity, mechanism, description, clinicalEvidence (EvidenceStrength), monitoringRequired, monitoringParameters (string[]), managementGuideline.

Computed: isContraindicated, requiresMonitoring, affectsCYP450, clinicalSignificance, safetyMargin. Method: generateClinicalWarning().

3.6 AdverseEvent#

Constructed from AdverseEventData: id (AdverseEventId), speciesId, reactionType, description, severity ('mild' \| 'moderate' \| 'severe' \| 'fatal'), causalityAssessment, patientAge, patientSex ('male' \| 'female' \| 'other'), dose, duration, outcome, concomitantMedications (string[]), reportSource, reportDate.

Computed: isSeriousEvent, causalityStrength, isExpectedReaction, requiresReporting, outcomeCategory.

3.7 TraditionalUse#

Constructed from TraditionalUseData: id, speciesId, tradition, indication, preparation, dosage, plantPart, region, historicalPeriod, culturalContext, referenceSource.

Computed: tradition, hasScientificValidation (always false — callers must cross-reference EvidenceRecord), geographicOrigin, historicalDepth, preparationComplexity.

3.8 PharmacognosyMonograph#

Constructed from MonographData: id (MonographId), speciesId, pharmacopoeia, monographId, title, qualityMarkers (QualityMarkerEntry[] — marker, minValue, maxValue, unit), identityTests (string[]), purityTests (string[]), assayMethod, storageConditions, shelfLifeMonths, lastRevisionDate.

Computed: pharmacopoeia, qualityMarkerCount, hasAssayMethod, isCurrentEdition (revised within 10 years), shelfLifeMonths. Method: meetsQualityStandard(marker, value).

3.9 ProteinTarget#

Constructed from ProteinTargetData: id, uniprotId, name, geneName, organism, function, subcellularLocation, molecularWeight, aminoAcidLength, bindingSites (BindingSiteEntry[] — name, residues, type: 'active_site' \| 'allosteric' \| 'cofactor' \| 'other'), associatedPathways (string[]), associatedDiseases (string[]), compoundIds (CompoundId[]), pdbIds (string[]).

Computed: hasValidUniprotId, hasStructuralData, bindingSiteCount, hasActiveSite, isDrugTarget, sizeCategory, diseaseAssociationCount, hasAllostericSite.

3.10 BiologicalPathway#

Constructed from BiologicalPathwayData: id (PathwayId), name, keggId, category, description, organismSpecific, nodeCount, edgeCount, keyEnzymes (string[]), substrates, products, regulators, associatedCompoundIds (CompoundId[]), associatedDiseases (string[]).

Computed: hasValidKeggId, complexityCategory, averageConnectivity, hasCompoundInteractions, isDiseaseAssociated, isOrganismSpecific, enzymeCount.

3.11 QualityMarker#

Constructed from QualityMarkerData: id, speciesId, compoundId, markerName, markerType ('active_constituent' \| 'indicator' \| 'adulterant' \| 'contaminant'), minConcentration, maxConcentration, unit, analyticalMethod, pharmacopoeiaReference, acceptanceCriteria.

Computed: isActiveConstituent, isAdulterantMarker, isContaminantMarker, concentrationRange, targetConcentration. Methods: isWithinSpec(measuredValue), deviationFromTarget(measuredValue).

3.12 DNABarcode#

Constructed from DNABarcodeData: id, speciesId, locus, sequence, sequenceLength, gcContent (0–1), accessionNumber, primerForward, primerReverse, referenceDatabase, similarityThreshold (0–1), authenticates (boolean).

Computed: isStandardLocus (ITS, ITS2, rbcL, matK, trnH-psbA), gcContentCategory, isValidForAuthentication, sequenceLengthCategory, hasAccessionNumber. Method: isAboveThreshold(querySimilarity).

3.13 SpectroscopicFingerprint#

Constructed from SpectroscopicFingerprintData: id, speciesId, technique ('HPLC' \| 'HPTLC' \| 'GC-MS' \| 'LC-MS' \| 'NMR' \| 'IR' \| 'UV-Vis' \| 'Raman'), samplePreparation, instrumentParameters, peakCount, majorPeaks (SpectroscopicPeak[] — position, intensity, assignment), referenceStandard, similarityScore (0–1), isAuthentic, rawDataUrl.

Computed: isChromatographic, isSpectroscopic, complexityCategory, passesAuthentication (similarity ≥ 0.9 and isAuthentic), dominantPeak, hasRawData.

3.14 FormulationRecipe#

Constructed from FormulationRecipeData: id, name, description, form, preparationType, ingredients (FormulationIngredient[] — optional speciesId, name, amount, unit, optional plantPart, role: 'primary' \| 'adjuvant' \| 'corrective' \| 'vehicle' \| 'preservative'), instructions (string[]), totalVolume, totalVolumeUnit, shelfLifeDays, storageConditions, indications (string[]), contraindications (string[]).

Computed: ingredientCount, primaryIngredientCount, isSimple, hasContraindications, shelfLifeCategory, primaryIngredients, adjuvantIngredients, complexityCategory, stepCount.

3.15 ConservationStatus#

Constructed from ConservationStatusData: id, speciesId, iucnStatus, citesAppendix, populationTrend ('increasing' \| 'stable' \| 'decreasing' \| 'unknown'), estimatedPopulation (number | null), threatFactors (string[]), conservationActions (string[]), assessmentDate, assessmentAuthority, range (string[]), protectedAreaCoverage (0–100), sustainableHarvestingPossible (boolean).

Computed: isThreatened, isExtinct, isCITESListed, isPopulationDeclining, urgencyLevel, canBeSustainablyHarvested, threatCount, conservationActionCount, hasAdequateProtection.

4. Core Errors (@airmid/core)#

Defined in libs/airmid/core/src/errors.ts. Airmid errors carry structured metadata beyond a simple message string — severity, a domain-specific error code, and a freeform details record. This allows callers to handle errors programmatically (e.g., escalating Fatal severity interactions differently from Warning severity taxonomy errors).

4.1 AirmidErrorSeverity#

Enum: Info, Warning, Critical, Fatal.

4.2 AirmidErrorCode#

A template-literal union: AIRMID_TAXONOMY_${string}, AIRMID_COMPOUND_${string}, AIRMID_INTERACTION_${string}, AIRMID_EVIDENCE_${string}, AIRMID_DOSAGE_${string}, AIRMID_CONTRAINDICATION_${string}, AIRMID_QUALITY_${string}, AIRMID_REGULATORY_${string}.

4.3 Error Classes#

AirmidError is the base class (Error subclass) carrying code, severity, details (Record<string, unknown>), timestamp, and a toJSON() returning SerializedAirmidError. The eight domain-specific subclasses map to the most clinically significant error categories. Note that ContraindicationError and DosageExceedanceError default to the highest severities — these represent patient-safety critical conditions.

Utilities: isAirmidError(error) (type guard), formatAirmidError(error) (human-readable string with severity badge).

5. Core Domain Events (@airmid/core)#

Defined in libs/airmid/core/src/events.ts. The AirmidEventType constant object provides 13 event type strings. There is no event bus in the domain; createAirmidEvent builds typed event objects and resetEventCounter resets the in-process ID counter. When the planned Oshun event bus integration is wired in, these events will flow to other domains without any changes to the event payloads.

Every event object (AirmidEvent<T>) carries type, payload, timestamp (ISO 8601), eventId, and source (defaults to 'airmid-core').

5.1 Payload Shapes#

Each payload carries the minimum fields needed by downstream consumers to act on the event without querying the database — for example, InteractionIdentifiedPayload includes both herb and drug names so a notification service can generate an alert without a separate lookup.

6. Core Constants and Reference Data (@airmid/core)#

Defined in libs/airmid/core/src/constants.ts. These constants are the hard-coded scientific reference data that does not change frequently and does not belong in the database — enzyme identifiers, curated short interaction lists, WHO-recognized herb lists, and pharmacological parameters.

• CYP450_ENZYMES — 12 major cytochrome P450 enzyme identifiers (CYP3A4, CYP2D6, CYP2C9, CYP2C19, CYP1A2, CYP2E1, CYP2B6, CYP2A6, CYP2C8, CYP3A5, CYP3A7, CYP2J2).
• COMMON_HERB_DRUG_INTERACTIONS — curated InteractionRecord[] covering St. John's Wort, Ginkgo, Panax ginseng, Kava, Valerian, Garlic, Echinacea, Milk thistle, Grapefruit, and Goldenseal.
• WHO_ESSENTIAL_MEDICINES_HERBS — 25 WHO-recognized medicinal plants, each { binomial, commonName, primaryUse }.
• GRADE_QUALITY_FACTORS — five downgrade factors (risk of bias, inconsistency, indirectness, imprecision, publication bias) and three upgrade factors (large effect, plausible confounding, dose-response), each with a maxReduction/maxIncrease.
• THERAPEUTIC_CATEGORIES — 20 categories (Adaptogen, Analgesic, etc.), each { category, description, examples }.
• ELEMENT_SYMBOLS — all 118 periodic-table element symbols, used for molecular-formula validation.
• BIOAVAILABILITY_ROUTES — five administration routes with typical bioavailability fractions.
• MEDICINAL_PLANT_FAMILIES — 10 major medicinal plant families with characteristic compounds and example genera.
• CYP450_COMPOUND_CLASS_PROFILES — maps 11 compound classes to the CYP enzymes each inhibits or induces.

7. Core Validation and Pharmacology Functions#

The following utility modules in @airmid/core provide standalone functions used throughout the domain. They operate on the plain interfaces and enums from §2 rather than on entity class instances.

7.1 Validation (libs/airmid/core/src/validation.ts)#

validateCASNumber (check-digit validation), validateTaxonomy, getRequiredRanksForLevel, validateDosage, validateSMILES, validateMolecularFormula, validateEvidenceGrade.

7.2 Pharmacology (libs/airmid/core/src/pharmacology.ts)#

calculateBioavailability, estimateHalfLife, classifyDrugLikeness (returns LipinskiResult), calculateTherapeuticIndex, assessCYP450Risk (returns CYP450RiskAssessment), calculateDoseEquivalence.

7.3 Taxonomy (libs/airmid/core/src/taxonomy.ts)#

formatBinomial, parseBotanicalName (returns ParsedBotanicalName), getPlantFamily, validateBinomialNomenclature, buildTaxonomicPath, getCommonFamilies.

7.4 Evidence (libs/airmid/core/src/evidence.ts)#

gradeEvidence, classifyStudyQuality, calculateEffectSize, assessPublicationBias, generateEvidenceSummary, isRCTQuality.

7.5 Interactions (libs/airmid/core/src/interactions.ts)#

assessInteractionRisk, getCYP450Profile, checkContraindications, formatInteractionWarning, rankInteractionsBySeverity, getMonitoringRecommendation.

8. Database Schema (@airmid/database)#

Located at libs/airmid/database/src. The library exports Zod schema modules (schema/) and Knex migration functions (migrations/). It does not open database connections — it provides schema definitions and migration runners that a consuming application wires to a PostgreSQL connection.

The schema was designed with several production concerns in mind: uuid-ossp for UUID generation, pg_trgm for full-text trigram search, an airmid_update_timestamp() trigger for automatic updated_at maintenance, soft-delete support via deleted_at columns, and 5 materialized views for commonly aggregated queries that would otherwise require expensive joins.

8.1 Migrations#

Six ordered migration files (timestamp-prefixed 20260318100001–…6). They must be applied in order — later migrations reference tables and enum types created by earlier ones.

1. initial_setup — enables PostgreSQL extensions uuid-ossp and pg_trgm, creates the airmid_update_timestamp() trigger function, and creates 35 custom enum types (growth_form, plant_part, iucn_status, cites_appendix, compound_class, solubility_class, extraction_method, study_design, trial_phase, blinding_type, allocation_type, grade_quality, oxford_level, evidence_strength, interaction_severity, interaction_mechanism, clinical_evidence_level, adverse_reaction_type, adverse_event_severity, causality_assessment, adverse_event_outcome, patient_sex, medical_tradition, pharmacopoeia_source, regulatory_jurisdiction, regulatory_status_value, regulatory_category, marker_region, reference_database, spectroscopic_technique, activity_type, population_trend, harvest_sustainability, cultivation_status, airmid_audit_action).
2. core_tables — botanical_species, phytochemical_compounds, plant_compound_associations, clinical_trials, evidence_records.
3. safety_tables — drug_herb_interactions, adverse_event_reports, traditional_use_records, pharmacopoeia_monographs, regulatory_statuses.
4. genomics_targets — dna_barcodes, spectroscopic_fingerprints, protein_targets, compound_target_associations, biological_pathways, conservation_records, airmid_audit_logs.
5. materialized_views — five materialized views (mv_species_compound_evidence, mv_species_interaction_summary, mv_top_studied_species, mv_evidence_by_condition, mv_compound_activity_summary), each with a unique index, refreshed with REFRESH MATERIALIZED VIEW CONCURRENTLY.
6. soft_delete — adds deleted_at columns, partial indexes, cascade triggers, and soft_delete / restore / purge helper functions.

Total: 17 base tables plus 5 materialized views.

8.2 Tables (createTable calls)#

The 17 tables are distributed across three migration files according to their domain grouping:

8.3 Zod Schema Modules#

schema/index.ts re-exports 15 modules: common, botanical-species, phytochemicals, plant-compounds, clinical-trials, evidence-records, drug-interactions, adverse-events, traditional-use, pharmacopoeia, regulatory, genomics, targets-pathways, conservation, audit.

The common.ts module provides shared building blocks used across all other schema modules: UuidSchema (UUID v4), TimestampSchema (ISO datetime, with or without offset), UrlSchema, DoiSchema, CasNumberSchema, InChIKeySchema, PaginationSchema, SortDirectionSchema, SortSchema, DateRangeFilterSchema, NumericRangeFilterSchema, JsonValueSchema, JsonObjectSchema, StringArrayJsonSchema.

Each entity module exports a row schema plus matching …CreateInputSchema (omits id, createdAt, updatedAt) and …UpdateInputSchema (partial). Example: BotanicalSpeciesSchema has fields id, binomialName (regex /^[A-Z][a-z]+ [a-z]+$/), genus, species, subspecies?, authority, family, commonNames (JSON array), synonyms (JSON array), description, nativeRegion, habitat, growthForm, plantPartUsed (≥ 1), iucnStatus, citesAppendix, isEndemic, imageUrls, createdAt, updatedAt.

Note a field naming divergence between the two layers: the database schema uses singular plantPartUsed and adds isEndemic, while the core BotanicalSpeciesData entity uses plural plantPartsUsed without isEndemic. Consuming code must account for this mapping at the persistence boundary.

9. API Layer (@airmid/api)#

Located at libs/airmid/api/src. @airmid/api does not run an HTTP server. It provides: external bioinformatics database connectors, an ETL pipeline framework, an OpenAPI 3.1 endpoint specification (as data and a generator), SMILES/SMARTS cheminformatics utilities, and data-export/reporting functions.

9.1 External Database Connectors#

EXTERNAL_DATABASE_CONFIGS defines 10 external bioinformatics databases, each with name and baseUrl. The following table shows each database and its base URL as configured in the library:

URL builders cover each database (e.g. buildPubMedSearchURL, buildPubMedFetchURL, buildPubChemPropertyURL, buildPubChemNameSearchURL, buildPubChemSMILESSearchURL, buildChEMBLMoleculeURL, buildChEMBLActivityURL, buildUniProtSearchURL, buildUniProtEntryURL, buildSTRINGNetworkURL, buildSTRINGPartnersURL, buildSTRINGEnrichmentURL, buildKEGGFindURL, buildKEGGListURL, buildKEGGLinkURL, buildKEGGPathwayURL, buildClinicalTrialsSearchURL). Response parsers (parseNCBIResponse, parsePubMedArticleXML, parsePubChemResponse, parseChEMBLResponse, parseChEMBLActivities, parseUniProtResponse, parseSTRINGResponse, parseKEGGResponse, parseKEGGCompoundList) map raw responses to typed objects. Retry support: calculateExponentialBackoff, DEFAULT_RETRY_CONFIG, isRetryable, isRateLimitError, getEffectiveRateLimit (3/s NCBI without key, 10/s with key), plus validateDatabaseURL and getDatabaseConfig.

9.2 ETL Pipeline Framework#

PIPELINE_DEFINITIONS defines 8 scheduled pipelines (PubMed weekly, PubChem monthly, ChEMBL monthly, ClinicalTrials.gov weekly, UniProt quarterly, STRING quarterly, KEGG quarterly, VigiBase monthly). TRANSFORMATION_RULES defines 18 transformation rules (CAS check-digit validation, InChIKey format validation, SMILES canonicalization, species-name resolution with 40+ mappings, unit harmonization, cross-reference mapping, deduplication, confidence scoring). Pipeline functions: createPipeline, runETLExtraction, runETLTransformation, runETLLoad, updatePipelineStatus, calculateNextRun, getTransformationRulesForPipeline. Data-integrity helpers: computeSHA256Hex, trackProvenance, verifyProvenanceChecksum. Normalizers: normalizeCASNumber, normalizeAuthorName, normalizeOrganism, resolveSpeciesName, canonicalizeSMILES, convertUnit, convertToMicromolar, convertToDaltons, validateCASCheckDigit, validateInChIKey.

9.3 Cheminformatics Utilities#

Two cheminformatics modules handle SMILES and SMARTS processing in TypeScript, without external chemistry tool dependencies:

smiles-canonical.ts exports parseSmiles, canonicalSmiles, emitCanonicalSmiles, morganCanonicalRanks (plus Atom, Bond, Molecule types). smarts.ts exports parseSmarts, matchSmarts, smartsMatchesSmiles, findAllSmartsMatches, countSmartsMatches (plus SmartsAtomQuery, SmartsBondQuery, SmartsPattern types).

9.4 OpenAPI 3.1 Endpoint Specification#

AIRMID_API_ENDPOINTS is a typed array of 44 OpenAPI 3.1 endpoint definitions across 12 resource tags. generateOpenAPISpec() assembles a complete OpenAPI 3.1 document (info, servers, bearerAuth security scheme, ProblemDetail schema, tags). This is a published specification used by a consuming application; the library itself does not serve these routes.

Authentication is a JWT Bearer token (bearerAuth security scheme) for all secured endpoints. All errors follow RFC 7807 (application/problem+json); standard responses for 400, 401, 403, 404, 429, and 500 are attached to every secured endpoint.

9.5 Rate-Limit Tiers#

RATE_LIMIT_TIERS defines 4 tiers. The CDS Hooks endpoint requires enterprise tier because it is called synchronously from within an EHR workflow and needs to handle high-frequency clinical traffic.

Rate-limit functions: checkRateLimit, getRateLimitTier. Request validation: validateRequest. RFC 7807 helpers: createProblemDetail, createValidationError. Cursor pagination (base64-encoded position): generateCursorPagination, encodeCursor, decodeCursor.

9.6 Webhooks and API Documentation#

api-documentation.ts exports WEBHOOK_SPECIFICATIONS (12 webhook event types — species.updated, species.created, compound.added, compound.updated, interaction.discovered, interaction.updated, evidence.published, evidence.retracted, safety.alert, pipeline.completed, pipeline.failed, report.generated), getWebhookSpec, generateWebhookPayload, verifyWebhookSignature (HMAC-SHA256), computeHMACSHA256, plus generateTypeScriptClient, generateCodeExample, generateAllCodeExamples.

9.7 Data Export and Reporting#

data-export.ts exports exportToJSON, exportToCSV (RFC 4180), exportToXML, exportToRDFTurtle (linked data), exportToSDF (cheminformatics Structure-Data File), escapeCSVField, escapeXML. Reporting: REPORT_TEMPLATES (6 templates), listReportTemplates, generateReport. Open-data assessment: assessFAIRCompliance (Findable, Accessible, Interoperable, Reusable scoring).

10. Scientific Library Surface#

The remaining scientific libraries each expose a typed module surface through src/index.ts. Rather than duplicating all field-level detail here (consult the library source for exhaustive types), this section documents the headline data magnitudes and key function names that define each library's public contract.

Each library's types.ts defines its own domain types, unions, and Zod schemas; those types are not duplicated here — consult the library source for exhaustive field-level detail.

11. Configuration#

Airmid libraries are configured through their callers. There is no .env file or environment-variable loader inside libs/airmid/. Configuration that is expressed in code:

• External database base URLs and rate limits — EXTERNAL_DATABASE_CONFIGS in @airmid/api (the NCBI E-utilities client distinguishes a 3/s unkeyed rate limit from a 10/s keyed rate limit via getEffectiveRateLimit).
• ETL pipeline schedules — PIPELINE_DEFINITIONS in @airmid/api.
• API rate-limit tiers — RATE_LIMIT_TIERS in @airmid/api.
• OpenAPI servers — generateOpenAPISpec() lists production, staging, and local-development server URLs.
• Database connection — @airmid/database provides Knex migrations and Zod schemas only; the connection string is supplied by the migration runner / consuming application.

12. Technology Stack and Build#

Cheminformatics algorithms (SMILES canonicalization, SMARTS substructure matching, AutoDock Vina scoring, Needleman-Wunsch alignment, molecular property formulas) are implemented in TypeScript; there is no Python subprocess or RDKit dependency in the current code.

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 a library's tests
cd libs/airmid/<library> && npx vitest run

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

13. Acceptance Criteria#

The following criteria must all pass. They are phrased as observable test outcomes rather than code assertions, so they can be evaluated against any test runner output.

• All 19 libraries type-check (npx tsc --noEmit) and pass their Vitest suites.
• Branded ID schemas reject non-UUID strings; CAS_NUMBER_PATTERN and INCHI_KEY_PATTERN reject malformed identifiers.
• Entity constructors throw on missing required fields and on out-of-range numeric inputs (e.g. pValue outside 0–1, gcContent outside 0–1).
• Domain-correctness tests assert known literature values (e.g. compound molecular weights, established herb-drug interaction severities) rather than shape-only assertions.
• Contraindicated interactions are never downgraded by clinical-decision logic.
• The 6 database migrations apply in order and create the 17 base tables, 5 materialized views, and 35 enum types described in §8.
• generateOpenAPISpec() produces a valid OpenAPI 3.1 document covering all 44 endpoints in §9.4.