_{hero rendered procedurally by assets/readme/src/render_hero.py from src/three/airgl geodesy · seamless 8s loop · static poster at assets/readme/yaslogist-hero.png}

YASLOGIST AIR

_{simulation-grade air freight cockpit · CAI corridor intelligence · bilingual EN/AR · no carrier/customs live integration}

Live Preview · Quality Workflow · Kinetic Workflow · Reconstruction Log · Issues

---

01 / THE SYSTEM

◢ SYSTEM SURFACE YASLOGIST AIR is a static, client-only React cockpit for air-freight simulation. It computes chargeable weight, corridor carbon, indicative cost, ULD fit, AWB Mod-7 validity, cargo-village handoff, and demo consignment state from local constants only. boundary: no airline feed · no IATA booking feed · no Nafeza/customs feed · no backend database · no live AWB status.

◢ EXECUTION MATRIX runtime React 19 + TypeScript strict render Vite 6 + Tailwind CSS 4 + WebGL2 AIRGL state useState, localStorage, URL query params quality typecheck → tests → build → bundle budget → audit motion procedural hero GIF + SMIL SVG kinetics + in-app WebGL/scroll kinetics

02 / CORE CAPABILITIES

Capability	Engine	Output	Boundary
Chargeable weight	calculateAirFreight	CBM, volumetric kg, gross kg, chargeable kg, billing basis, density class.	Simulation math only.
Carbon comparison	calculateAirFreight	Freighter CO2e vs container-vessel benchmark for selected corridor.	Average factor estimate, not certified shipment emissions.
Indicative pricing	estimateAirFreightCost	Base freight, fuel, security, CAI terminal handling, Nafeza pre-validation fee.	Benchmark estimate, not a quotation.
ULD recommendation	recommendUld	AKE, PMC, RKN, RAP fit assessment with blockers and utilization.	Planning heuristic, not carrier load acceptance.
AWB validation	validateIataAwb	Mod-7 pass/fail, airline prefix lookup, correction suggestion.	Structure only, not booking/customs status.
3D twin	src/three/airgl/uld/*	PBR, thermal, X-ray inspection modes.	Procedural visualization, no live manifest.
Corridor globe	src/three/airgl/globe/*	Great-circle routes, aircraft arc motion, landmask, terminator.	Bundled route dataset.
Demo tracking	ConsignmentTracker	Five-stage cargo milestone cards for bundled samples.	Fail-closed for unknown identifiers.

03 / ENGINEERING ARCHITECTURE

Client topology

flowchart LR
    subgraph Boot["Boot Surface"]
      HTML[index.html]
      THEME[public/theme-init.js\npre-paint theme + direction]
      MAIN[src/main.tsx]
      HTML --> THEME --> MAIN
    end

    subgraph Providers["Context Layer"]
      I18N[src/lib/i18n.tsx\nEN/AR + RTL]
      THEMECTX[src/lib/theme.tsx\ndark/light persistence]
    end

    subgraph Shell["Application Shell"]
      APP[src/App.tsx]
      NAV[NavbarAir]
      EXP[ExperienceLayer\nscroll progress + reveals]
      HERO[CinematicStage\nscroll-scrubbed runway reel]
      ERR[ErrorBoundary]
    end

    subgraph Domains["Domain Modules"]
      MATH[src/lib/air-math.ts\nIATA 1:6000 + CO2e + cost]
      COR[src/lib/corridors.ts\nCAI corridor constants]
      ULD[src/lib/uld-fleet.ts\nfleet + fit recommendation]
      A11Y[src/lib/a11y.ts\nfocus trap]
      SIMLINK[src/lib/sim-link.ts\nshareable scenarios]
      LOOP[src/lib/scene-loop.ts\nquiescent frame budget]
    end

    subgraph UI["Lazy Feature Sections"]
      STATS[StatsAir]
      MISSION[MissionAir]
      VILLAGE[CargoVillageFlow]
      RADAR[FlightRadarHUD]
      ULDUI[ULDSelector + ULDViewer3D]
      SIM[CargoSimAir]
      CORUI[CorridorsAir + CorridorGlobe3D]
      TRACK[ConsignmentTracker]
      HANDOFF[HandshakeAirToLand]
      STANCE[StanceAir]
      MODALS[AwbModalAir + LegalModalAir]
    end

    subgraph AIRGL["AIRGL WebGL2 Engine"]
      GL[src/three/airgl/gl.ts]
      ULD3D[src/three/airgl/uld/*\nPBR / thermal / X-ray twin]
      GLOBE[src/three/airgl/globe/*\ngreat-circle corridor network]
    end

    MAIN --> I18N --> APP
    MAIN --> THEMECTX --> APP
    APP --> NAV
    APP --> EXP
    APP --> HERO
    APP --> ERR --> UI
    SIM --> MATH
    SIM --> COR
    SIM --> ULD
    SIM --> SIMLINK
    ULDUI --> ULD
    ULDUI --> AIRGL
    CORUI --> COR
    CORUI --> AIRGL
    TRACK --> COR
    MODALS --> A11Y
    AIRGL --> LOOP

Loading

Module inventory

Path	Role	Invariant
src/App.tsx	Shell, lazy section orchestration, modal ownership, analytics mount.	One Suspense + ErrorBoundary per feature section.
src/components/CargoSimAir.tsx	Scenario UI for dimensions, gross weight, route, cooling, cost/carbon, export.	All calculations delegated to pure library functions.
src/lib/air-math.ts	IATA volumetric divisor, AWB checksum/correction, CO2e, indicative pricing.	Finite positive inputs or synchronous RangeError.
src/lib/uld-fleet.ts	ULD constants and recommendation engine.	Horizontal rotation only; 90% broken-stowage reserve; active-cooling match required.
src/lib/corridors.ts	FRA/DXB/AMS/PVG ⇄ CAI lane constants and sea benchmarks.	One shared data source for simulator and corridor browser.
src/components/ConsignmentTracker.tsx	Bundled demo consignment lookup.	Unknown query returns not found; never synthesizes operational status.
src/three/airgl/	WebGL2 ULD digital twin and corridor globe.	Dedicated vendor-three chunk loads when a 3D canvas approaches within 200px of the viewport (eager fallback without IntersectionObserver); explicit resource disposal and no render-loop allocations.
scripts/check-bundle.mjs	Production asset budget gate.	App JS ≤ 515 KB raw; CSS ≤ 112 KB raw; exactly one vendor-three chunk ≤ 592 KB raw.
assets/readme/src/render_hero.py	Procedural README hero renderer (this page's opening visual).	Reuses repo geodesy, landmask, airport anchors and monogram geometry; periodic functions only, so the loop is seamless.

04 / SYSTEM BLUEPRINT

flowchart TB
    classDef cyan fill:#001F27,stroke:#00E5FF,color:#E6F7FA,stroke-width:2px;
    classDef dark fill:#0D1117,stroke:#334155,color:#E6EDF3;
    classDef warn fill:#25130B,stroke:#F59E0B,color:#FFEBC2;
    classDef fail fill:#2A0B12,stroke:#FF476F,color:#FFE3EA;

    A([VISITOR_INPUT]):::cyan --> B{finite + > 0?}:::dark
    B -- no --> X[RangeError: reject before UI mutation]:::fail
    B -- yes --> C[INPUT_NORMALIZED]:::cyan

    C --> D[CORRIDOR_SELECTED\nFRA/DXB/AMS/PVG ⇄ CAI]:::dark
    C --> E[PIECE_MODEL_BUILT\nL×W×H × pieces]:::dark
    C --> F[COOL_CHAIN_FLAGGED]:::dark

    E --> G[WEIGHT_ENGINE\nCBM · volumetric kg · gross kg · chargeable kg]:::cyan
    D --> H[CARBON_ENGINE\nfreighter tonne-km vs sea-lane benchmark]:::cyan
    D --> I[COST_ENGINE\nbase + fuel + security + CAI THC + Nafeza precheck]:::cyan
    E --> J[ULD_FIT_ENGINE\ninternal envelope · payload · 90% broken-stowage reserve]:::cyan
    F --> J

    G --> K[SIMULATION_MANIFEST]:::dark
    H --> K
    I --> K
    J --> K

    L[AWB_QUERY]:::cyan --> M{11 digits after strip?}:::dark
    M -- no --> N[STRUCTURAL_INVALID]:::fail
    M -- yes --> O{serial % 7 == check digit?}:::dark
    O -- no --> P[SUGGEST_CORRECT_DIGIT]:::warn
    O -- yes --> Q[CARRIER_PREFIX_RESOLVED]:::cyan

    R[TRACKER_QUERY]:::cyan --> S{bundled sample match?}:::dark
    S -- yes --> T[DEMO_MILESTONE_TIMELINE]:::cyan
    S -- no --> U[NOT_FOUND_FAIL_CLOSED]:::fail

    K --> V[LOCAL_EXPORT\ncopy / print / download .txt]:::dark
    Q --> V
    T --> V

Loading

Runtime state machine

stateDiagram-v2
    [*] --> ColdBoot
    ColdBoot --> ThemePrepaint: public/theme-init.js
    ThemePrepaint --> ReactRoot: src/main.tsx
    ReactRoot --> Providers: ThemeProvider + LanguageProvider
    Providers --> Shell: src/App.tsx
    Shell --> CinematicStage
    Shell --> LazySections
    LazySections --> StatsAir
    LazySections --> MissionAir
    LazySections --> CargoVillageFlow
    LazySections --> FlightRadarHUD
    LazySections --> ULDSelector
    LazySections --> CargoSimAir
    LazySections --> CorridorsAir
    LazySections --> ConsignmentTracker
    LazySections --> HandshakeAirToLand
    LazySections --> StanceAir
    LazySections --> FooterAir
    LazySections --> ErrorBoundary: chunk/render fault
    ErrorBoundary --> DegradedCard
    CargoSimAir --> LocalManifestExport
    ConsignmentTracker --> FailClosedNotFound: unknown AWB/flight query
    LocalManifestExport --> Shell
    FailClosedNotFound --> Shell

Loading

05 / EXECUTION INTELLIGENCE

sequenceDiagram
    actor U as User
    participant UI as Cargo simulator
    participant M as air-math
    U->>UI: change dimensions / weight / corridor
    UI->>M: validated numeric input
    M-->>UI: volume, chargeable weight, CO2e, block time, cost
    U->>UI: export manifest
    UI-->>U: copy / print / .txt (local only)

Loading

Stage	Behavior	Guarantee
boot	theme-init.js pre-paints theme + direction before React mounts.	No flash of wrong theme/direction in either locale.
validate	Numeric inputs checked finite > 0 before any UI mutation.	Synchronous RangeError, never NaN propagation.
compute	Pure functions: IATA 1:6000 volumetrics, GLEC CO2e, indicative cost, ULD fit.	Deterministic, unit-tested, zero network.
render	AIRGL WebGL2 twin + corridor globe in an isolated vendor-three chunk, imported as either 3D canvas approaches within 200px of view (eager fallback without IntersectionObserver).	Deferred engine transfer; quiescent frame budget; explicit GL disposal.
export	Manifest leaves the app only via clipboard / print / local .txt download.	No upload path exists.

06 / IGNITION

Local execution

npm ci
npm run dev -- --host 0.0.0.0
npm run check
npm run audit

CI contract

Gate	Command	Required State
Type safety	npm run typecheck	0 TypeScript errors.
Regression suite	npm test	All Vitest, Testing Library, a11y, CSP, theme, scene-loop tests pass.
Build	npm run build	Vite production bundle emits successfully.
Bundle budget	npm run check:bundle	Per-file and app-total JS/CSS ceilings respected; exactly one vendor-three chunk.
Supply chain	npm audit --omit=dev --audit-level=high	0 high/critical production vulnerabilities.

07 / DEEP SYSTEM ACCESS

Kinetic layer — how this page moves

hero	Procedural 8-second seamless loop: dot-shell planet (Fibonacci lattice + repo landmask), great-circle corridor arcs with the repo's apex profile, traveling pulses, hub rings, orbital traveler, solar terminator. Rendered by assets/readme/src/render_hero.py; every animation term is periodic, so the loop closes exactly.
statement	assets/readme/statement-typing.svg — SMIL terminal typing loop in the same Electric Cyan system.
dividers	assets/readme/divider-pulse.svg — traveling light pulse separators between sections.
factory	.github/workflows/kinetic-readme.yml runs every 12 hours, calls Platane/snk/svg-only@v3, writes assets/github-snake*.svg, writes Shields endpoint JSON, and commits the generated assets.

Live telemetry endpoint map

Signal	Endpoint	Source of Truth	Fail Threshold
quality gate	img.shields.io/github/actions/workflow/status	.github/workflows/quality.yml	any failed typecheck/test/build/budget/audit step
pipeline latency	img.shields.io/endpoint → assets/quality-latency.json	latest GitHub Actions run duration computed by kinetic workflow	> 600s renders amber; failed/missing run renders red/gray
zero-defect gate	img.shields.io/endpoint → assets/zero-defect-gate.json	latest quality.yml conclusion	anything except success
kinetic refresh	img.shields.io/endpoint → assets/kinetic-refresh.json	scheduled README asset generation timestamp	stale asset cadence beyond 12h schedule
stack versions	img.shields.io/github/package-json/dependency-version	package.json	dependency drift visible at read time
edge availability	img.shields.io/website	https://air.yaslogist.com	non-2xx/3xx response

Repository operating notes

Node	22.x
npm	10.x+
env	No required variables. Optional suite URLs are documented in .env.example.
deploy	Static Vite build. vercel.json ships CSP/security/cache headers.
assets	README motion assets in assets/ are generated by GitHub Actions; hero + SMIL kinetics live in assets/readme/; app assets remain in public/assets/.
README_SNAKE_USER	Optional repository variable overriding the contribution-grid username; defaults to repository owner.

Data + license boundary

YASLOGIST AIR is a decision-support simulation. It does not connect to airlines, airports, customs systems, IATA operational systems, Nafeza, shipment IoT, or third-party freight pricing APIs. Local demo data may look operational; it is versioned source code and must remain labelled as demonstration output.

Code follows the repository license policy. Project-supplied imagery in public/assets/ should be treated as project-owned/maintainer-provided unless separate license metadata is added. README kinetic assets are generated artifacts; no photographed or human-recorded motion is required.

08 / ENGINEERING STATUS

Surface	Status	Evidence
Volumetric / carbon / cost engines	✅ implemented, tested	src/lib/air-math.ts + Vitest suite
ULD fit engine + WebGL2 twin	✅ implemented, tested	src/lib/uld-fleet.ts, src/three/airgl/uld/*
Corridor globe + terminator	✅ implemented, tested	src/three/airgl/globe/* with embedded landmask
AWB Mod-7 validator	✅ implemented, tested	validateIataAwb + correction suggestion
Bilingual EN/AR + RTL	✅ implemented	src/lib/i18n.tsx, pre-paint direction
Live carrier / customs / Nafeza feeds	⛔ out of scope by design	simulation boundary, enforced fail-closed
Live AWB tracking	⛔ out of scope by design	bundled demo consignments only

09 / YASLOGIST

YASLOGIST is the permanent creative-engineering signature behind this repository — the parent identity of the multimodal logistics intelligence suite (air · land · sea). Each project keeps its own operational identity; the YASLOGIST DNA — architectural precision, luminous restraint, verified claims — carries through every surface. yaslogist.com · air.yaslogist.com · Electric Cyan #00E5FF

---

_{built for air.yaslogist.com · part of the YASLOGIST multimodal suite · hero + kinetics rendered procedurally from repository source data}