Skip to content

Instantly share code, notes, and snippets.

@patricksavalle

patricksavalle/l-gevity-architecture.md

Created May 3, 2026 11:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save patricksavalle/21e4d5c0d470f0ea6a6eaf180459ba59 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save patricksavalle/21e4d5c0d470f0ea6a6eaf180459ba59 to your computer and use it in GitHub Desktop.
Download ZIP
Dependency graph of L-GEVITY as enforced by ESLint rules
Raw
l-gevity-architecture.md

Architecture Dependency Graph (Visual)

These diagrams render as interactive dependency graphs in GitHub markdown.

System-Wide Dependency Graph

graph TB
    subgraph frontend["Frontend (packages/shared-ui)"]
        subgraph presentation["Presentation Layer"]
            Component["🎨 Components<br/>(_includes/*, js/components/)"]
            Page["📄 Pages<br/>(js/pages/)"]
            PageData["📊 Page Data<br/>(js/page-data/)"]
        end

        subgraph orchestration["Orchestration Layer"]
            App["⚙️ App<br/>(js/app/)"]
            Pipeline["📈 Pipeline<br/>(js/pipeline/)"]
            Engine["🧠 Engine<br/>(js/biometric-engine/)"]
            ProgramEngine["📅 Program Engine<br/>(js/program-engine/)"]
            Evaluator["🔢 Evaluator<br/>(js/biometric-evaluator/)"]
            Metrics["📏 Metrics<br/>(js/metrics/)"]
            Schedule["📋 Schedules<br/>(js/schedules/)"]
        end

        subgraph service_layer["Service Layer"]
            Service["🔌 Services<br/>(js/services/)"]
            SharedUtil["🛠️ Utils<br/>(js/utils/)"]
            BiometricData["🧬 Biometrics Data<br/>(js/biometrics/)"]
        end
    end

    subgraph content["Content (packages/shared-content)"]
        SharedContent["📝 Content<br/>(layouts, prose)"]
    end

    subgraph backend["Backend (packages/api)"]
        ApiEntry["🚀 Azure Functions<br/>(src/index.ts)"]
        Handler["🎯 Handlers<br/>(src/domain1, 2, 3)"]
        ApiService["⚙️ Services<br/>(src/services/)"]
        ApiUtil["🛠️ Utils<br/>(src/utils/)"]
    end

    %% Frontend internal flows (allowed)
    Component -->|events bridge| App
    Page -->|events bridge| App
    PageData -.->|data| Page

    App -->|config| Schedule
    App -->|run| ProgramEngine
    App -->|recalculate| Pipeline
    Pipeline -->|facade| Engine
    Pipeline -->|format| Metrics
    Pipeline -->|evaluate| Evaluator
    ProgramEngine -->|validate| ProgramEngine

    %% Forbidden flows (marked with ❌)
    Component -->|❌ FORBIDDEN| Service
    Page -->|❌ FORBIDDEN| Service
    PageData -->|❌ FORBIDDEN| Service
    Service -->|❌ FORBIDDEN| Component
    Service -->|❌ FORBIDDEN| Page
    Service -->|❌ FORBIDDEN| App

    Metrics -->|❌ FORBIDDEN| Pipeline
    Evaluator -->|❌ FORBIDDEN| Pipeline
    ProgramEngine -->|❌ FORBIDDEN| Pipeline
    Schedule -->|❌ FORBIDDEN| Pipeline

    %% Content isolation
    SharedContent -->|❌ FORBIDDEN| Component
    SharedContent -->|❌ FORBIDDEN| Service
    SharedContent -->|❌ FORBIDDEN| App

    %% Backend flows
    ApiEntry --> Handler
    Handler --> ApiService
    Handler --> ApiUtil
    ApiService --> ApiUtil

    %% Frontend to backend (via HTTP)
    Component -.->|HTTP| ApiEntry
    Service -.->|HTTP| ApiEntry

    classDef foundation fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef sealed fill:#fff3cd,stroke:#ffc107,stroke-width:3px
    classDef forbidden fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    classDef public fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px

    class Engine sealed
    class Component,Page,PageData,Service foundation
    class App,Pipeline,ProgramEngine public
Loading

Frontend Z-Axis (Detailed)

graph LR
    subgraph Y3["Y=3: Presentation"]
        Component["Components<br/>_includes/*<br/>js/components/"]
        Page["Pages<br/>js/pages/"]
        PageData["Page Data<br/>js/page-data/"]
    end

    subgraph Y2["Y=2: Orchestration"]
        App["App<br/>events.js<br/>app.js"]
        Pipeline["Pipeline<br/>calculation<br/>cache"]
        ProgramEngine["Program Engine<br/>schedule<br/>eligibility"]
        Evaluator["Evaluator<br/>expression<br/>eval"]
    end

    subgraph Y1["Y=1: Services"]
        Service["Services<br/>storage<br/>auth<br/>etc"]
        Utils["Utils<br/>helpers"]
    end

    subgraph Y0["Y=0: Computation"]
        Engine["Engine<br/>biometric<br/>calculations<br/>🔒 SEALED"]
    end

    %% Allowed flows
    Component -->|events| App
    Page -->|events| App
    PageData -->|data| Page

    App -->|orchestrate| Pipeline
    App -->|run| ProgramEngine
    Pipeline -->|facade| Engine
    Pipeline -->|format| Evaluator

    %% Forbidden flows
    Component -->|❌| Service
    Page -->|❌| Service
    PageData -->|❌| Service
    Service -->|❌| Component
    Service -->|❌| App

    classDef presentation fill:#e3f2fd,stroke:#1976d2
    classDef orchestration fill:#f3e5f5,stroke:#7b1fa2
    classDef services fill:#fff3e0,stroke:#e65100
    classDef computation fill:#e8f5e9,stroke:#388e3c
    classDef sealed fill:#fff3cd,stroke:#ffc107,stroke-width:3px

    class Component,Page,PageData presentation
    class App,Pipeline,ProgramEngine,Evaluator orchestration
    class Service,Utils services
    class Engine sealed,computation
Loading

App Module (4-Tier)

graph TD
    subgraph Tier3["Tier 3: Entry/Composition"]
        AppJs["app.js<br/>⭐ ONLY THIS<br/>IMPORTS BRIDGE"]
        Nav["navigation.js"]
        Prompts["Prompts<br/>(paywall, pwa)"]
    end

    subgraph Tier2["Tier 2: Bridge"]
        Bridge["bridge.js<br/>🔒 SERVICE↔WINDOW<br/>ISOLATED"]
    end

    subgraph Tier1["Tier 1: Setup/Infrastructure"]
        Auth["auth.js"]
        Demo["demo.js"]
        Guard["guard.js"]
        Ready["ready.js"]
    end

    subgraph Tier0["Tier 0: Foundation (SEALED)"]
        Events["events.js<br/>🔒 EVERYTHING<br/>DEPENDS ON IT"]
    end

    %% Allowed flows
    AppJs --> Bridge
    Nav --> Events
    Prompts --> Events
    Auth --> Events
    Demo --> Events
    Guard --> Events
    Ready --> Events
    Bridge --> Events

    %% Forbidden flows (marked)
    Auth -->|❌| Bridge
    Auth -->|❌| AppJs
    Demo -->|❌| Bridge
    Demo -->|❌| AppJs
    Guard -->|❌| Bridge
    Guard -->|❌| AppJs
    Ready -->|❌| Bridge
    Ready -->|❌| AppJs

    classDef entry fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    classDef bridge fill:#fff3cd,stroke:#ffc107,stroke-width:3px
    classDef setup fill:#e3f2fd,stroke:#1976d2
    classDef foundation fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px

    class AppJs,Nav,Prompts entry
    class Bridge bridge
    class Auth,Demo,Guard,Ready setup
    class Events foundation
Loading

Program Engine (3-Tier + Singleton Pattern)

graph TD
    External["🌐 External Code<br/>(components, pages, services)"]

    subgraph Public["✅ PUBLIC API"]
        Singleton["programEngine<br/>SINGLETON<br/>← import only from here"]
    end

    subgraph Internal["🔒 INTERNAL (Hidden)"]
        Collector["schedule-collector.js<br/>Eligibility engine<br/>❌ Don't import directly"]
        Validator["schedule-validation.js<br/>Pure validator<br/>❌ Don't import directly"]
    end

    Storage["🗄️ action-log-repository<br/>(services/storage)"]
    BiometricEval["🔢 expression-evaluator<br/>(biometric-evaluator)"]
    Pipeline["📈 calculation-pipeline<br/>(pipeline)"]
    Schedules["📋 Schedules<br/>(js/schedules/)"]

    %% Allowed flows
    External -->|✅ ONLY THIS| Singleton
    Singleton --> Collector
    Singleton --> Validator
    Collector --> Validator

    Collector --> Storage
    Collector --> BiometricEval
    Collector --> Pipeline
    Validator -.->|no imports|External

    Singleton --> Schedules
    Singleton --> Storage

    %% Forbidden flows
    External -->|❌ FORBIDDEN| Collector
    External -->|❌ FORBIDDEN| Validator
    Collector -->|❌ FORBIDDEN| Singleton

    classDef public fill:#d1ecf1,stroke:#17a2b8,stroke-width:3px
    classDef internal fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    classDef forbidden fill:#f8d7da,stroke:#dc3545,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#e3f2fd,stroke:#1976d2

    class Singleton public
    class Collector,Validator internal
    class External external
Loading

Biometric Engine (5-Tier + Sealed)

graph TD
    Pipeline["📈 Pipeline<br/>(ONLY ALLOWED IMPORTER)"]

    subgraph Engine["🔒 SEALED BIOMETRIC ENGINE"]
        Facade["biometric-engine.js<br/>✅ PUBLIC FACADE"]

        subgraph Tier5["Tier 5: Orchestration"]
            Orchestrator["Orchestrator<br/>coordinates all tiers"]
        end

        subgraph Tier4["Tier 4: Calculators"]
            Calc["Risk calculations<br/>disease models<br/>scoring engines"]
        end

        subgraph Tier3["Tier 3: Domain Helpers"]
            Helpers["Cohort comparison<br/>percentile mapping<br/>thresholds"]
        end

        subgraph Tier2["Tier 2: Data Transform"]
            Transform["Normalization<br/>derivation<br/>filtering"]
        end

        subgraph Tier1["Tier 1: Foundation"]
            Foundation["Constants<br/>schemas<br/>registry"]
        end
    end

    External["🌐 Everything Else<br/>(components, services, etc.)"]

    %% Allowed flow (ONLY)
    Pipeline -->|facade| Facade
    Facade --> Orchestrator

    %% Internal tier flows
    Orchestrator --> Tier4
    Tier4 --> Tier3
    Tier3 --> Tier2
    Tier2 --> Tier1

    %% Forbidden flows
    External -->|❌ FORBIDDEN| Facade
    External -->|❌ FORBIDDEN| Tier5
    External -->|❌ FORBIDDEN| Tier4
    External -->|❌ FORBIDDEN| Tier3
    External -->|❌ FORBIDDEN| Tier2
    External -->|❌ FORBIDDEN| Tier1

    classDef sealed fill:#fff3cd,stroke:#ffc107,stroke-width:3px
    classDef facade fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
    classDef tier fill:#e8f5e9,stroke:#388e3c
    classDef forbidden fill:#f8d7da,stroke:#dc3545,stroke-dasharray: 5 5
    classDef external fill:#e3f2fd,stroke:#1976d2

    class Engine,Facade sealed,facade
    class Orchestrator,Calc,Helpers,Transform,Foundation tier
    class External external
Loading

API Layering (5-Layer + Domain Isolation)

graph TD
    External["HTTP Requests<br/>(from frontend)"]

    subgraph APIStack["API STACK (packages/api)"]
        Entry["Entry<br/>src/index.ts<br/>(Azure Functions)"]

        subgraph Handlers["Handler Layer (Domain-Isolated)"]
            H1["Domain 1<br/>src/domain1/**<br/>(handlers)"]
            H2["Domain 2<br/>src/domain2/**<br/>(handlers)"]
            H3["Domain 3<br/>src/domain3/**<br/>(handlers)"]
        end

        subgraph ServiceLayer["Service Layer"]
            Services["Services<br/>src/services/**<br/>(shared logic)"]
        end

        subgraph UtilLayer["Util Layer (Leaf)"]
            Utils["Utils<br/>src/utils/**<br/>(helpers)"]
        end

        subgraph ConfigLayer["Config Layer (Leaf)"]
            Config["Config<br/>src/config/**<br/>(constants)"]
        end
    end

    %% Allowed flows
    External --> Entry
    Entry --> H1
    Entry --> H2
    Entry --> H3

    H1 --> Services
    H2 --> Services
    H3 --> Services

    Services --> Utils
    Config --> Utils

    %% Forbidden flows (cross-domain)
    H1 -->|❌ FORBIDDEN| H2
    H1 -->|❌ FORBIDDEN| H3
    H2 -->|❌ FORBIDDEN| H1
    H2 -->|❌ FORBIDDEN| H3
    H3 -->|❌ FORBIDDEN| H1
    H3 -->|❌ FORBIDDEN| H2

    %% Forbidden upward flows
    Services -->|❌ FORBIDDEN| H1
    Services -->|❌ FORBIDDEN| H2
    Services -->|❌ FORBIDDEN| H3
    Services -->|❌ FORBIDDEN| Entry

    Utils -->|❌ FORBIDDEN| Services
    Utils -->|❌ FORBIDDEN| H1
    Config -->|❌ FORBIDDEN| Services

    classDef entry fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
    classDef handler fill:#e3f2fd,stroke:#1976d2
    classDef service fill:#fff3e0,stroke:#e65100
    classDef util fill:#f3e5f5,stroke:#7b1fa2
    classDef config fill:#f8d7da,stroke:#dc3545
    classDef forbidden fill:#f8d7da,stroke:#dc3545,stroke-dasharray: 5 5

    class Entry entry
    class H1,H2,H3 handler
    class Services service
    class Utils util
    class Config config
Loading

Component Base Classes (Boundary Rules)

graph TB
    Allowed["✅ ALLOWED IMPORTS"]

    BaseComponents["Base Components<br/>(js/components/)"]

    External1["chart.js<br/>(external NPM)"]
    External2["External libs"]

    App["app layer<br/>(events)"]
    Pipeline["pipeline layer<br/>(calculations)"]
    Metrics["metrics layer<br/>(formatting)"]

    Forbidden["❌ FORBIDDEN IMPORTS"]

    HigherComponents["Higher components<br/>(_includes/components/)"]
    Pages["Pages"]
    Other["Other modules"]

    %% Allowed
    BaseComponents -->|✅| External1
    BaseComponents -->|✅| External2
    BaseComponents -->|✅| App
    BaseComponents -->|✅| Pipeline
    BaseComponents -->|✅| Metrics

    %% Forbidden
    BaseComponents -->|❌| HigherComponents
    BaseComponents -->|❌| Pages
    BaseComponents -->|❌| Other

    classDef base fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
    classDef allowed fill:#d4edda,stroke:#28a745
    classDef forbidden fill:#f8d7da,stroke:#dc3545

    class BaseComponents base
    class External1,External2,App,Pipeline,Metrics allowed
    class HigherComponents,Pages,Other forbidden
Loading

Cross-Layer Rules Summary

graph LR
    subgraph rule1["🔒 Engine Encapsulation"]
        A1["Everything else"]
        A2["❌ engine internals"]
        A3["✅ engine facade"]
        A4["Pipeline"]
        A1 -->|forbidden| A2
        A1 -->|allowed| A3
        A3 --> A4
    end

    subgraph rule2["🚫 Pipeline Gating"]
        B1["metrics/evaluator<br/>program-engine<br/>schedule-config"]
        B2["❌ cannot use"]
        B3["pipeline"]
        B4["app/component<br/>service/page"]
        B5["✅ can use"]
        B1 -->|forbidden| B3
        B4 -->|allowed| B3
    end

    subgraph rule3["🔌 Service Isolation"]
        C1["Components<br/>Pages"]
        C2["❌ direct import"]
        C3["Services"]
        C4["events bridge<br/>window listener"]
        C1 -->|forbidden| C3
        C1 -->|allowed| C4
        C4 -.-> C3
    end

    subgraph rule4["📋 shared-content"]
        D1["shared-content"]
        D2["❌ cannot import"]
        D3["component/service<br/>page-script<br/>app/metrics"]
        D1 -->|forbidden| D3
    end

    classDef rule fill:#f0f4ff,stroke:#5e7ce0,stroke-width:2px
    classDef allowed fill:#d4edda,stroke:#28a745
    classDef forbidden fill:#f8d7da,stroke:#dc3545

    class rule1,rule2,rule3,rule4 rule
Loading

Legend

Symbol Meaning
🔒 Sealed/Encapsulated module
✅ Allowed import
❌ Forbidden import
← Depends on
-.-> Indirect/event-based flow
--- Solid line = direct import
- - - Dashed line = forbidden
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment