Cicada Architecture

Cicada's forecasting pipeline processes FHIR input through a series of steps that mirror the CDSi Logic Specification.

Pipeline Overview#

FHIR Parameters (input)
       │
  1. Parse ──────────▶ VaxPatient (demographics, doses, observations)
       │
  2. Map ────────────▶ Map<String, VaxAntigen> (one per target disease)
       │
  3. Evaluate ───────▶ Each dose checked against series requirements
       │
  4. Forecast ───────▶ Series determines need + recommended dates
       │
  5. Select Best ────▶ VaxGroup scores and picks best series
       │
  6. Aggregate ──────▶ Vaccine group forecasts (multi-antigen grouping)
       │
FHIR Parameters (output)

Step 1: Parse#

The PatientForAssessment Riverpod provider extracts a VaxPatient from the FHIR Parameters input. It parses:

• Patient demographics (birth date, sex)
• Immunization history (CVX codes, dates administered)
• Clinical conditions, allergies, observations, procedures, and medications

Each clinical resource is cross-referenced against the observation crosswalk to identify CDSi observation codes (e.g., "patient is immunocompromised", "patient is pregnant").

Step 2: Map#

antigenMap() distributes each administered dose to the antigens it targets. A single CVX code (e.g., CVX 94 for MMR-Varicella) may map to multiple antigens (Measles, Mumps, Rubella, Varicella). The CVX-to-antigen mapping comes from the schedule supporting data.

Step 3: Evaluate#

Each VaxAntigen contains one or more VaxGroups, each containing one or more VaxSeries. For each series, doses are evaluated in order per CDSi Figure 6-1:

1. Inadvertent Administration — Was the vaccine given inadvertently?
2. Age Validity — Was the patient within the valid age range?
3. Interval — Was the minimum interval from the previous dose met?
4. Live Virus Conflict — Was there a conflicting live virus vaccine given too recently?
5. Vaccine Type — Was the administered vaccine an allowable type for this dose?

The first failing check determines the evaluation reason. Valid doses are added to the series' evaluated dose list.

Step 4: Forecast#

Each series determines its forecast need:

• Check for immunity (clinical evidence or completed series)
• Check for contraindications (both preferable and allowable vaccines)
• Determine series completeness (all target doses satisfied?)
• If not complete, calculate forecast dates using conditional skip logic and interval calculations

Step 5: Select Best Series#

VaxGroup scores and prioritizes series using CDSi Table 8-14:

• Complete/Immune series are preferred over in-process
• In-process preferred over zero-dose
• Among ties, standard series preferred over risk series
• Score considers number of valid doses, number of not-valid doses, and closest forecast date

Step 6: Aggregate#

Multi-antigen vaccine groups (e.g., DTaP/Tdap/Td covers Diphtheria + Tetanus + Pertussis) aggregate recommendations from constituent antigens. The administerFullVaccineGroup flag determines whether to recommend the full combination or allow individual components.

Model Hierarchy#

VaxPatient
 └── VaxAntigen (one per target disease: Measles, Tetanus, HepB, etc.)
      └── VaxGroup (groups series by vaccine group: MMR, DTaP/Tdap/Td, etc.)
           └── VaxSeries (one CDSi series: standard, risk, evaluation-only)
                └── VaxDose (one administered dose with evaluation status)

VaxPatient#

Parsed patient with demographics, past doses, and observations. Created by the PatientForAssessment provider from FHIR Parameters.

VaxAntigen#

One instance per target disease (e.g., Measles). Contains groups, handles immunity and contraindication checks. The set of antigens comes from activeAntigenMap (CDC or WHO depending on ForecastMode).

VaxGroup#

Groups related series by vaccine group. Implements the CDSi series scoring and best-series selection algorithm. A vaccine group like MMR contains multiple series (e.g., standard 2-dose MMR, catch-up).

VaxSeries#

Tracks one CDSi series definition. Evaluates administered doses against target dose requirements, manages conditional skip logic ("if patient already received X, skip dose Y"), and generates forecast dates with earliest/recommended/past-due/latest.

Series types:

• Standard — Always included for evaluation
• Risk — Only included when patient has a matching observation (e.g., immunocompromised) and falls within the indication age range
• Evaluation-only — Used for dose evaluation but does not generate forecasts

VaxDose#

An individual administered dose with its evaluation outcome:

• Valid — Meets all requirements for the target dose
• Not Valid — Fails one or more checks (with specific reason)
• Sub-standard — Partially valid (e.g., grace period)
• Extraneous — Not needed by the series

Key Types#

VaxDate#

Extends DateTime with CDSi date arithmetic:

final birthDate = VaxDate(2024, 1, 15);
final sixMonths = birthDate.change('6 months');    // 2024-07-15
final dueDate = birthDate.change('6 months 4 days'); // 2024-07-19

// Sentinel values
VaxDate.min(); // 1900-01-01
VaxDate.max(); // 2999-12-31

AntigenSupportingData#

Immutable data class containing the complete definition for one antigen: target disease, vaccine group, series definitions (with dose rules, intervals, allowable vaccines), immunity criteria, and contraindications. Deserialized from generated JSON.

ScheduleSupportingData#

Global schedule data shared across all antigens: live virus conflicts, vaccine groups, vaccine-group-to-antigen map, CVX-to-antigen map, and observation definitions (clinical condition crosswalk).

State Management#

Cicada uses Riverpod (non-Flutter variant) with ProviderContainer for managing shared state during a forecast run:

• patientForAssessmentProvider — Parses FHIR Parameters into VaxPatient
• observationsProvider — Shared observation state across evaluation
• seriesGroupCompleteProvider — Tracks series group completion across antigens (used for conditional skip logic)
• operationOutcomesProvider — Collects OperationOutcome issues (errors/warnings)

A new ProviderContainer is created for each forecast invocation, ensuring thread safety and isolation.

Generated Code#

Supporting data files in cicada/lib/generated_files/ are produced by the generator pipeline and should not be hand-edited:

• CDC: One .dart file per antigen + schedule_supporting_data.dart + barrel file
• WHO: Same structure in generated_files/who/ with who prefix on variable names

The generator reads from CDSi XML/Excel specifications (CDC) or Excel workbooks (WHO) and produces Dart files with AntigenSupportingData.fromJson() and ScheduleSupportingData.fromJson() calls containing the full specification data. WHO Excel source files live in cicada_generator/lib/WHO/antigen/ (22 .xlsx) and WHO/schedule/ (5 .xlsx).