ParkinSUM Companion

A provenance-first Parkinson medication-food interaction prototype for deterministic rule tracing, read-only algorithm observability, Firebase governance, and synthetic-data demos.

Educational architecture prototype only. Not medical advice or a clinical decision tool.

ParkinSUM Companion is a local-first Flutter prototype that demonstrates how a health-adjacent app can combine synthetic meal logging, medication context, deterministic rule checks, a read-only Algorithm Observatory, evidence-oriented explanations, and release safety guardrails without making clinical claims.

It is a production-architecture prototype designed for educational demonstrations, software architecture review, and academic discussion of local-first digital health prototypes. It is not a medical device and must not be used for diagnosis, treatment, medication timing, dietary guidance, clinical decision-making, patient care, or emergency support.

Public demos should use synthetic or sample data only.

What It Demonstrates

• Meal logging and medication-context capture for a Parkinson's disease education scenario.
• Deterministic food-drug interaction checks instead of black-box medical advice.
• Evidence-oriented explanations that show why a prototype rule fired.
• A read-only Algorithm Observatory that exposes registry coverage, production-path traces, fixed non-personal scenarios, and explicit model limitations.
• Local-first app behavior for public demos and development.
• Optional Firebase-backed paths for internal operator validation and governance.
• Public-release guardrails around disclaimers, security, contribution rules, and synthetic data.

Algorithm and Safety Boundary

ParkinSUM's conflict engine is deterministic and evidence-linked: no LLM sits inside it, and every educational rule that fires carries a structured explanation with source references, provenance, the input fields actually used, any missing or uncertain inputs, an explicit limitation, and a hard not-advice boundary.

Conflict classifications, scores, safety gates, and evidence remain deterministic. With explicit user consent, an optional loopback model may only rerank the rule-screened, non-BLOCK candidate whitelist or polish wording that the deterministic path has already produced. It cannot change medication data, conflict decisions, scores, rules, evidence, or safety gates.

Medication context must be catalog-backed and unit-explicit before any food-medication rule is evaluated. A bare numeric dose such as 100, an unstructured string such as "100 tablets", or a name without a unit such as levodopa 100 is rejected outright — ParkinSUM does not infer mg, tablet count, schedule, formulation, or release type from such input. Entries without an active ingredient, drug product variant, formulation, or provenance are treated as insufficient context and do not produce a conflict result.

High-value contributor work in this area includes:

• Medication context validation (lib/domain/usecases/medication_entry_validator.dart).
• Evidence-linked rule explanations (lib/domain/entities/rule_explanation.dart).
• Importer provenance fields (basis, scope, jurisdiction, confidence, source).
• Negative safety tests that prevent educational copy from drifting into medication timing, dose, dietary, or clinical-validation claims (test/medication_entry_validator_test.dart, test/rule_explanation_safety_test.dart).

See docs/RULE_ENGINE.md for the medication context gate, the structured rule-explanation template, a worked levodopa+protein example, and the negative-test expectations.

Mechanistic Conflict and Recommendation Engine

ParkinSUM now includes a deterministic, time-axis, literature-informed educational conflict engine that models meal composition, gastric emptying assumptions, small-intestinal arrival, a levodopa absorption opportunity window, an amino-acid competition proxy, overlapping-meal effects, and uncertainty bands. Every modeled assumption is backed by a local source registry (lib/domain/usecases/model_assumption_registry.dart) that cites entries in Bibliographies.md (MLA format).

The next-meal flow accepts a user-defined time window and a regional food library. Inside a narrowly supported medication domain it computes deterministic per-candidate overlap traces for inspection and sensitivity comparison. Those traces do not reorder recommendations: the production decision-influence boundary is trace_only. rankerUsed reports heuristic_legacy_fallback or, only after separate consent and whitelist validation, local_ai_safe_candidate_rerank; it never names the mechanistic trace as the ranker. The model does not decide when the user eats, does not produce medication timing or dietary advice, and abstains when the window, medication context, or applicability predicates are insufficient. Missing route is never promoted to oral, an unrecorded meal is never promoted to fasting, and a future candidate meal cannot alter an earlier dose's absorption window. A stale meal outside its explicit gastric-residence horizon also cannot unlock a current trace, and contradictory nested product/source metadata invalidates the medication context instead of authorizing a curve. The built-in generic carbidopa/levodopa entry deliberately carries an unspecified release type: until the product picker persists a governed product-level ingredient/route/form/release snapshot, selecting any concrete package forces the model context to remain unspecified even if its parent catalog row claims IR.

Trace sampling uses deterministic multi-point sampling (5–12 samples, capped) across the user-provided window; worst/best/average/per-sample values are surfaced as educational trace data, not as a validated optimization target. Gastric-emptying numerics live in a single GastricEmptyingParameterSet with per-parameter sourceRefs, and the amino-acid competition layer now applies a coarse, direction-only LNAA load factor per protein source (animal vs plant). Mixed actual-profile coverage is labeled hybrid, widens uncertainty, and does not publish a pseudo-measured whole-meal LNAA total. The runtime food repository is augmented at app boot with foods projected from CDSS observations so traces can use catalog-backed candidates, not only synthetic replay items. See docs/RUNTIME_MODEL_APPLICABILITY_RESEARCH_2026-08-17.md for the evidence and abstention boundary.

The data chain preserves fidelity end-to-end: missing nutrient data is carried as unknown, never coerced to a fake 0 g (missingNutrientFields → null components → lowered composition completeness → widened uncertainty); actual USDA FDC amino-acid fields (verified nutrient-number mapping) feed the LNAA layer in preference to the protein-source proxy; per-candidate CandidateMetadata (authority, jurisdiction match, completeness, provenance) is built from imported source data so official-in-jurisdiction outranks synthetic/seed. The medication dose is taken only from the user's entered dosage note (value + unit must both be explicit) — there is no private default; a missing/ambiguous dose yields insufficient context and blocks dose-dependent interpretation. The conflict engine evaluates each levodopa dose on a multi-dose time axis and aggregates with deterministic max-overlap, keeping per-dose traces.

Compact mechanistic-trace UI cards render alongside the existing recommendation and conflict-result views via an ExpansionTile so the new surface stays out of the way until a reviewer expands it. Raw trace JSON is never shown by default.

Synthetic replay scenarios are available via the CLI:

dart run tool/run_mechanistic_replay.dart
# or
npm run mechanistic:replay

The runner writes build/mechanistic_replay/latest.{json,md} and exits non-zero on any expectation mismatch or banned-phrase hit.

See docs/CONFLICT_ENGINE_MODEL.md for the layered model description and docs/REPLAY_RUNNER.md for the scenario format and CLI details. ParkinSUM does not overclaim clinical accuracy; the engine is an educational simulation, not a patient-care tool.

Educational Model Guardrails

The mechanistic conflict engine is not clinically calibrated. Its gastric-emptying values are literature-informed prototype parameters; the amino-acid (LNAA) competition layer is an educational proxy. It makes no patient-specific pharmacokinetic/pharmacodynamic prediction, gives no medication-timing, dietary, or dose guidance, and carries no clinical-validation claim. All importer adapters are fixture-validated (not live production ingestion); the optional live-source smoke harness is opt-in, excluded from normal tests, fetches official metadata only, and is not used for clinical advice. A fail-closed open-source influence inventory now separates conceptual research from authorized transferred artifacts; legal advice, artifact-level SBOM attestation, and complete cross-platform NOTICE verification remain open. See docs/OPEN_SOURCE_INFLUENCE_FIREWALL_RESEARCH_2026-08-18.md and docs/SOURCE_ACCESS_AND_LICENSES.md.

Algorithm Observatory

The read-only Algorithm Observatory makes the deterministic runtime easier to audit without changing its decisions. At capture commit 23619f1, the registry contains 58 algorithm descriptors. Reviewers can compare three fixed, non-personal scenarios, inspect the production-path trace and explanation tree, and review the result-affecting registry inventory. Live production-path output and static registry contracts are labeled separately so a declared contract is not mistaken for a runtime observation.

The interface keeps severity, confidence, and missingness separate. Its gastric and absorption curves are unitless educational sensitivity views—not gastric- emptying tests, absorbed-dose estimates, plasma concentrations, symptom predictions, or advice. The responsive screenshot below demonstrates browser layout reflow only; it is not physical-device, native-platform, accessibility, or clinical validation.

Multi-Jurisdiction Metadata & Protein Redistribution

ParkinSUM's importer layer is multi-jurisdiction: source-adapter specs cover DailyMed (US), Health Canada DPD (CA), EMA + EU national registers (EU/EEA), NHS dm+d (GB), PMDA (JP), NMPA (CN), and food-composition sources (USDA FDC, Ciqual, China CDC), with a deterministic source-authority scorer (official-in-jurisdiction outranks others; reference translations are downgraded; seed/synthetic never overrides official; cross-jurisdiction conflicts are preserved, not merged). Canonical source/provenance metadata — jurisdiction, language, unit, basis, authority tier, completeness, limitation — is preserved from importer to runtime so the mechanistic engine and scorer can reason about it.

The next-meal scorer exposes protein-redistribution timing as an educational trace, not a diet optimizer. Inside the narrowly declared immediate-release applicability domain it shows a unitless overlap assumption and a non-clinical nutrition-adequacy proxy; outside that domain it abstains. The production recommendation order remains the conservative heuristic order—the mechanistic trace never selects a meal time or reorders food candidates.

See docs/IMPORTER_METADATA_FLOW.md for the canonical metadata model, source-authority policy, cross-jurisdiction conflict policy, completeness gate, and the protein-redistribution objective, and docs/MANUAL_VALIDATION.md for a hands-on walkthrough.

Fixture-tested medication source parsers now cover DailyMed, Health Canada DPD, EMA, PMDA, NHS dm+d (identity/coding — not a complete food-effect source), EU national registers (member-state identity vs full SmPC), and NMPA (fixture-validated / prototype, honestly downgraded). A SourceFetchClient abstraction (with an offline FixtureSourceFetchClient returning structured SourceFetchResults) keeps all tests deterministic; live fetch is optional and never used for clinical advice. Per-food amino-acid fields, when present, drive the LNAA competition layer in preference to the protein-source proxy. The conservative heuristic remains the only production recommendation ranker; the trace-only reason is surfaced in UI and replay.

Evidence & Traceability Architecture

ParkinSUM's most reviewable surface is its evidence and provenance layer. Conflict classifications, scores, safety gates, evidence links, and production traces are deterministic, source-linked, and serializable for review—without patient data. Any consent-gated loopback AI remains outside that decision path and is limited to the screened-whitelist and wording roles described above.

• Deterministic mechanistic replay — 41 synthetic scenarios, banned-phrase scanned (docs/REPLAY_RUNNER.md).
• CDSS-style source/provenance metadata with source-authority and metadata-completeness gates (docs/IMPORTER_METADATA_FLOW.md).
• FDC nutrient provenance tiers (analytical / calculated / imputed / unknown) as source-quality signals that affect modeled confidence, not advice.
• Multi-dose medication traces with per-dose modeled overlap.
• Local EvidenceTraceBundle — a ParkinSUM-local artifact (explicitly not a FHIR Bundle) pairing the two inspired views (docs/EVIDENCE_TRACE_BUNDLE.md).
• FHIR-inspired, non-conformant NutritionIntake / MedicationKnowledge views (PHI-free; inspired_not_conformant) with a conservative LOINC section-code trace.
• Source-quality perturbation report — shows how scoring moves when only source/provenance quality changes (docs/SOURCE_QUALITY_PERTURBATION_REPORT.md).
• Public preflight + Firestore rules contract release guardrails.

source/importer metadata → normalized facts (missing ≠ zero)
  → metadata completeness + source authority
  → mechanistic engine (per-dose) → replay / source-quality report
  → FHIR-inspired views + local EvidenceTraceBundle

Reviewer entry points: docs/EVIDENCE_AND_TRACEABILITY_DEMO_GUIDE.md (guided walkthrough), docs/CAPABILITY_MATRIX.md (implemented vs future work), docs/PUBLIC_VERIFICATION.md (exact commands), and the docs index. These artifacts are deterministic synthetic-data demonstrations — they are not clinical validation, and the source-quality report is not a clinical dashboard.

Demo Media

These are commit-identified runtime web captures from a local-mode build using fresh synthetic onboarding data and fixed, non-personal Observatory fixtures. They document the interface at main@23619f1; they do not establish clinical accuracy, physical-device compatibility, native-platform behavior, accessibility conformance, or a deployed-backend result.

_{Algorithm Observatory overview: fixed scenarios, production-path trace, and registry snapshot at the capture commit.}

Conflict composition and explanation tree expose inputs, outputs, evidence, and limitations.	Registry-backed coverage distinguishes live traces from static contracts.
Capability Center surfaces local-mode configuration and implementation boundaries.	Responsive browser viewport (390×844); layout evidence only, not a physical-device claim.

Open the fresh local-mode dashboard capture

Capture provenance, privacy review, and evidence limits are recorded in docs/assets/screenshots/README.md and docs/media-capture-checklist.md.

Quick Start

Install Flutter, Node.js, and npm first. Then run these commands from the repository root:

git clone https://github.com/albertzhzhou-droid/ParkinSUM.git
cd ParkinSUM
flutter pub get
flutter run -d chrome

Evaluate the prototype locally:

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test
npm ci
npm run public:preflight
npm run rules:contract

Run the deterministic evidence artifacts (synthetic data; not clinical validation):

dart run tool/run_mechanistic_replay.dart            # or: npm run mechanistic:replay
dart run tool/run_source_quality_perturbation_report.dart  # or: npm run source:quality

See docs/PUBLIC_VERIFICATION.md for what each command checks, its expected output, and what failure means.

The default public-demo path is local mode. Firebase-backed commands are retained for internal operator validation and require project access.

Release

The current public showcase target is v0.2.0-beta. Release materials are tracked in CHANGELOG.md, docs/release/v0.2.0-beta-notes.md, docs/release/synthetic-demo-data.md, and docs/release/release-checklist.md. The earlier alpha materials remain at docs/release/v0.1.0-alpha-notes.md.

A scoped release-metadata package is published to GitHub Packages (npm registry) as @albertzhzhou-droid/parkinsum-companion on each tagged release; see packages/npm/README.md.

Any Android APK generated for this beta must be labeled as a beta/demo/debug artifact unless production signing is handled in a separate release process.

Project Website

A lightweight GitHub Pages landing page is available in docs/site/index.html. Setup instructions are in docs/site/README.md.

An animated Liquid Glass-style showcase wiki is available in docs/wiki/index.html. GitHub Wiki-compatible Markdown pages are staged in docs/github-wiki/ so they can be published to the repository Wiki interface.

Contribute

Start with the contribution guide, then choose a scoped item from the public contribution backlog. Use the structured GitHub issue templates for bugs, features, documentation improvements, and research-rule evidence requests. A small real contributor PR request is drafted in docs/mentor-pr-request.md for classmates or mentors who want to test the project without making medical claims. Public examples must use synthetic or sample data only.

Secondary creators who need to fork the project, configure local GitHub authentication, and submit updates by pull request should follow the secondary creator token flow. The repository documents fork-scoped token permissions and setup steps, but never stores real token values.

Architecture Overview

flowchart LR
  UI["Flutter UI"]
  State["App State"]
  Data["Local-first Data Layer"]
  Rules["Deterministic Rule Engine"]
  Evidence["Evidence Explanation Layer"]
  Observatory["Read-only Algorithm Observatory"]
  AI["Consent-gated Loopback AI"]
  Output["Educational Awareness Output"]

  UI --> State
  State --> Data
  Data --> Rules
  Rules --> Evidence
  Evidence --> Output
  Rules --> Observatory
  Evidence --> Observatory
  Rules -->|"screened non-BLOCK whitelist"| AI
  AI -->|"rerank or wording only"| Output

Loading

The app separates user-facing screens, app state, local data handling, deterministic rule evaluation, read-only observability, and evidence-oriented explanation copy. The optional AI branch cannot write back to medication data, rules, classifications, scores, evidence, or safety gates. Firebase services are available for internal validation, but the public prototype should be evaluated with synthetic data and conservative claims.

See docs/ARCHITECTURE.md and docs/RULE_ENGINE.md for more detail.

Safety Boundary

ParkinSUM Companion is an educational awareness prototype only.

• It does not diagnose, treat, monitor, prevent, or manage disease.
• It does not provide individualized dietary, medication, clinical, or emergency advice.
• It has no patient-outcome validation or clinical-use approval.
• It should not be connected to real health records for public demos.
• Screenshots, tests, walkthroughs, and examples should use synthetic or sample data only.

Read DISCLAIMER.md and docs/PUBLIC_DEMO_BOUNDARY.md before presenting or reusing the project.

Repository Map

Path	Purpose
lib/app/	Flutter app bootstrap and top-level app wiring.
lib/features/	User-facing flows such as dashboard, meals, medications, onboarding, import, and recommendations.
lib/core/	Shared models, state, services, database adapters, constants, i18n, and copy helpers.
lib/domain/	Entities, repositories, deterministic rule use cases, recommendation orchestration, and evidence-oriented runtime logic.
lib/data/	Local and remote data-source implementations, importers, and repository implementations.
test/	Focused Flutter and Dart tests for rule execution, importers, onboarding, Firebase boundaries, and recommendation copy.
tool/	Public preflight, Firebase governance, release, monitoring, and operator-validation scripts.
docs/	Architecture, rule-engine, release, public-boundary, risk, security-adjacent, and operations documentation.

Current Status

• Public release type: prototype showcase.
• Current public release target: v0.2.0-beta.
• Package name: parkinsum_companion.
• Current app version: 0.2.0+2.
• Default public-demo backend: local mode.
• Firebase backend mode: internal operator validation only.
• Public contact: parkinsumservice@gmail.com.
• Public readiness gate: npm run public:preflight should report zero BLOCKER findings before publication.

Public GitHub visibility does not claim external clinical, legal, privacy, regulatory, or patient-outcome approval.

Roadmap

Near-term work is tracked in ROADMAP.md. Current priorities include:

• Maintain commit-identified local-mode desktop/responsive captures and keep unsafe legacy media retired.
• Keep the rule engine evidence-linked and auditable.
• Improve accessibility, localization, and caregiver-oriented educational flows.
• Expand sample-data walkthroughs without adding real patient data.
• Maintain release, security, and public-readiness checks as the prototype changes.

Citation / Academic Use

ParkinSUM Companion may be cited as a software prototype or educational research artifact. Do not cite it as a clinical intervention, medical device, treatment system, or patient-outcome study.

Suggested citation format:

Zhou, Z. ParkinSUM Companion: a local-first Flutter prototype for Parkinson's disease diet-medication education. GitHub repository, 2026. Available at: https://github.com/albertzhzhou-droid/ParkinSUM

If you discuss the project academically, include the safety boundary: educational awareness only, synthetic/demo data only, and no diagnosis, treatment, medication timing, dietary guidance, clinical decision-making, or patient-care use.

Documentation

Start here

• Documentation index
• Public verification guide
• Contribution guide
• Rule engine overview
• Project website
• Animated showcase wiki
• GitHub Wiki source pages

Architecture

• Architecture overview
• Conflict engine model
• Importer & metadata flow
• Evidence trace bundle

Safety and release

• Disclaimer
• Security policy
• Roadmap
• Contribution guide
• Contribution backlog
• Secondary creator token flow
• Mentor/classmate PR request
• Changelog
• Citation metadata
• Repository metadata recommendations
• Social preview brief
• Rule engine testing
• Impact one-page summary
• Impact technical case study
• Impact project pitch
• Impact FAQ
• Impact safety and ethics
• v0.2.0-beta release notes
• v0.1.0-alpha release notes
• Synthetic demo data
• Synthetic demo scenarios
• Release checklist
• Project website
• Animated showcase wiki
• GitHub Wiki source pages
• GitHub Pages setup
• Public showcase readiness
• Public demo boundary
• Release checklist
• Known risks

Demo and impact

• Synthetic demo scenarios
• Media capture checklist
• Impact one-page summary

Contributing

Contributions are welcome when they keep the public prototype boundary intact. Good first areas include documentation, UI strings, accessibility notes, synthetic sample interactions, and focused tests. Start with CONTRIBUTING.md.

Do not submit personal health information, real medication schedules, credentials, service account keys, private Firebase exports, or raw operator logs.