SummerProject2026/docs/architecture.md

flowchart TD
    SOURCE[(Private inspection histories<br/>read-only source)]
    SAMPLE[Private page-sampled histories<br/>up to 10,000 vehicles<br/>keyed vehicle tokens]
    SOURCE -->|read-only bounded export| SAMPLE

    SAMPLE --> STAGE[Normalize labels<br/>deduplicate and validate]
    STAGE --> EPISODES[Build 30-day episodes<br/>first attempt is the target]
    EPISODES --> MART[Point-in-time feature mart<br/>returning vehicles only]

    subgraph SPLITS[Private development chronology]
        direction LR
        CONTEXT[2010-15<br/>history context]
        TRAIN[2016-22<br/>train]
        TUNE[2023<br/>tune]
        CAL[2024<br/>calibrate]
        HOLDOUT[2025<br/>one-time holdout]
        SHADOW[2026 partial<br/>shadow context]
    end
    MART -.-> SPLITS

    MART --> LOGISTIC[Regularized logistic + Platt<br/><b>final prototype model</b>]
    MART --> TREE[Histogram gradient boosting + Platt<br/><b>benchmark only</b>]

    LOGISTIC --> PRIVATE[Private model artifacts<br/>manifests, checksums, metrics]
    TREE --> PRIVATE
    HOLDOUT -.-> REPORT[Private/report-only<br/>one-time comparison]
    PRIVATE -.-> REPORT

    MART --> EXPORT[Aggregate, suppress,<br/>round, validate]
    PRIVATE -.->|pre-2025 diagnostics only| EXPORT

    subgraph PUBLIC[dashboard/public/data - public boundary]
        direction TB
        MANIFEST[data_manifest.json]
        OVERVIEW[overview_period_county.json]
        COHORTS[cohort_scorecard.json]
        AGE[age_risk_curve.json]
        COVERAGE[coverage_quality.json]
        FILTERS[filter_catalog.json]
        DIAGNOSTICS[model_diagnostics.json]
        HASHES[sha256_manifest.json]
    end
    EXPORT --> PUBLIC

    PUBLIC --> CONTRACT[Fail-closed browser validation]
    CONTRACT --> SITE[Static dashboard<br/>semantic HTML + CSS<br/>vanilla ES modules + inline SVG]

    subgraph VIEWS[Presentation-ready views]
        direction TB
        V1[Overview]
        V2[Sample cohorts]
        V3[Model & benchmark]
        V4[Data & methods]
    end
    SITE --> VIEWS

    subgraph GUARDRAILS[Publication guardrails]
        direction TB
        G1[Private 10,000-vehicle sample<br/>not population estimates]
        G2[Minimum episode, vehicle,<br/>and binary-class support]
        G3[No identifiers, raw/operational rows,<br/>credentials, or row-level predictions]
        G4[No county population rankings<br/>or vehicle-level prediction service]
    end
    EXPORT -.-> GUARDRAILS

    SITE --> DEMO[Allowlisted local static server<br/>same-network live demo]

    subgraph TESTS[Verification]
        direction LR
        PY[Python pipeline/model/export tests]
        JS[Node dashboard contract tests]
    end
    MART -.-> PY
    PUBLIC -.-> JS

    classDef private fill:#fff3e0,stroke:#b45309,color:#3b2415
    classDef model fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e
    classDef public fill:#ecfdf5,stroke:#047857,color:#064e3b
    classDef warning fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d

    class SOURCE,SAMPLE,STAGE,EPISODES,MART,PRIVATE,REPORT private
    class LOGISTIC,TREE model
    class PUBLIC,CONTRACT,SITE,VIEWS,DEMO public
    class GUARDRAILS warning