diff --git a/README.md b/README.md index 9b1c73a..eadeaff 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,21 @@
-LOGISDATA — an audit gate sweeping across a simulated supply signal graph, leakage metrics and the five-stage audit rail +LOGISDATA — cinematic supply-chain audit intelligence: the real 8-node supply network under an animated emerald audit gate, with the five audit theatres, live reconciliation metrics and the YASLOGIST engineering signature -

LOGISDATA

+
+ + + +
-

Supply-Chain Audit Control Room

+# LOGISDATA + +### Supply-Chain Audit Control Room **One WebGL canvas. Five synchronized audit theatres. Two languages, one version of the truth.** +A permanent engineering signature of **YASLOGIST** · yaslogist.com + [![Next.js](https://img.shields.io/badge/Next.js-16-000000?style=for-the-badge&logo=nextdotjs&logoColor=white)](https://nextjs.org) [![React](https://img.shields.io/badge/React-19-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)](https://react.dev) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org) @@ -20,18 +28,24 @@ ![Database](https://img.shields.io/badge/PostgreSQL-optional-f59e0b?style=flat-square&labelColor=06121d) ![A11y](https://img.shields.io/badge/motion-reduction_aware-7dd3fc?style=flat-square&labelColor=06121d) -[**Quickstart**](#-quickstart) · [**System Architecture**](#-system-architecture) · [**Feature Matrix**](#-feature-matrix) · [**Core Workflows**](#-core-workflows) · [**Tech Stack**](#-tech-stack) · [**Social Preview**](#-social-preview-pipeline) +[**The System**](#the-system) · [**Capabilities**](#capabilities) · [**Architecture**](#architecture) · [**Blueprint**](#blueprint) · [**Execution**](#execution) · [**Ignition**](#ignition) · [**Deep Access**](#deep-access) · [**Status**](#status) · [**YASLOGIST**](#yaslogist)
+
+Animated technical statement cycling through the four reconciliations LOGISDATA audits: freight × telemetry, demand × orders, routes × GPS, WMS × shelf +
+ --- > [!NOTE] > **Abstract.** Supply-chain margin does not leak in one place — it leaks in the gap between four systems that each believe a different number. LOGISDATA is an executive audit instrument that puts those four disagreements on one canvas: freight billing versus telematics, consumer demand versus order amplification, planned routes versus GPS reality, and WMS master data versus what is physically on the shelf. It ships as a five-stage, scroll-choreographed control room with synchronized 3D operational models, full English/Arabic parity, and a hardened production posture. ---- + -## ▸ At a glance +## 01 / THE SYSTEM + +Margin leakage is not a reporting problem — it is a **reconciliation** problem. Each theatre of LOGISDATA stages one disagreement between systems of record, renders it twice (semantically in HTML, spatially in WebGL), and derives both surfaces from a single typed model so the numbers cannot drift apart. | Dimension | Value | Engineering consequence | | :--- | :--- | :--- | @@ -46,63 +60,67 @@ | **Initial shell payload** | 202,616 B gzip | measured against the 205,000 B production budget | | **Known vulnerabilities** | 0 (`npm audit`) | pinned toolchain plus an `esbuild` override | ---- +
+ +
-## ▸ System Architecture + -### Topology +## 02 / CORE CAPABILITIES -```mermaid -flowchart LR - classDef edge fill:#0b1c2a,stroke:#4de1c1,stroke-width:1px,color:#edf7fb - classDef srv fill:#10283a,stroke:#7dd3fc,stroke-width:1px,color:#edf7fb - classDef cli fill:#0b1c2a,stroke:#f59e0b,stroke-width:1px,color:#edf7fb - classDef opt fill:#0b1c2a,stroke:#6e8795,stroke-width:1px,stroke-dasharray:4 3,color:#a8becb +Every row below is implemented, exercised by the test suite, and visible in the running experience. Nothing on this matrix is aspirational. - visitor["Visitor
desktop · tablet · mobile"]:::edge + + + + + - subgraph server["Next.js App Router — server"] - direction TB - layout["layout.tsx
metadata · OG · fonts"]:::srv - page["page.tsx
server component"]:::srv - health["api/health
nodejs · force-dynamic"]:::srv - end + + + + + + - subgraph client["Client experience — use client"] - direction TB - shell["PresentationShell
capability probe + error boundary"]:::cli - loader["EngineLoader
static, engine-free"]:::cli - pres["Presentation
nav · prefs · keyboard"]:::cli - canvas["Canvas · ScrollControls
single WebGL context"]:::cli - rig["IndustrialScene
camera rig + focus curve"]:::cli - scenes["5 scene groups
network · scanner · matrix · terrain · grid"]:::cli - html["5 HTML sections
semantic tables + charts"]:::cli - end + + + + + - subgraph domain["Domain layer — pure TypeScript"] - direction TB - data["lib/data.ts
typed audit model"]:::srv - i18n["lib/i18n.ts
Intl EN/AR formatters"]:::srv - focus["lib/sceneFocus.ts
shared focus curve"]:::srv - end + + + + + - subgraph plane["Optional data plane"] - direction TB - db["db/index.ts
lazy bounded pool"]:::opt - pg[("PostgreSQL
Drizzle ORM")]:::opt - end + + + + + - visitor --> layout --> page --> shell - shell --> loader - shell -. "dynamic import once WebGL is confirmed" .-> pres - pres --> canvas --> rig --> scenes - canvas --> html - scenes --> focus - html --> data - scenes --> data - html --> i18n - visitor --> health --> db -. "only if DATABASE_URL" .-> pg -``` + + + + + + + + + + + + + + + +
#CapabilitySurfaceImplementationState
Experience
01Five-stage audit narrativesections/*Full-viewport sections bound to a shared section index✅ Shipped
02Synchronized 3D modelsthree/*Supply network, laser audit gate, demand matrix, route terrain, warehouse grid✅ Shipped
03Cinematic camera choreographyIndustrialSceneDual-target interpolation with frame-rate-independent damping✅ Shipped
04Deferred engine bootPresentationShellnext/dynamic + ssr:false after the WebGL capability probe; no cover-screen CTA✅ Shipped
05Animated metric countersMetricCounterIntersectionObserver (0.35) → rAF cubic ease-out over 1250 ms✅ Shipped
Localization
06English / Arabic paritylib/data.tsEvery copy node is LocalizedText; the compiler enforces coverage✅ Shipped
07Native RTL inversionPresentationdocumentElement.dir + lang flipped on toggle; CSS logical properties✅ Shipped
08Locale-correct numeralslib/i18n.tsIntl.NumberFormat with ar-EG digits and compact USD✅ Shipped
09Arabic display typography@fontsource-variable/cairoSelf-hosted variable font — no third-party font request✅ Shipped
Accessibility
10Keyboard navigationPresentationArrows · Page Up/Down · Home · End, with modifier and text-field guards✅ Shipped
11Semantic analyticssections/*Real <table> markup, aria-labelledby, aria-current="step"✅ Shipped
12Motion reductionuseReducedMotionProgrammatic scrolling drops to behavior: "auto"✅ Shipped
13Visible focus statesglobals.css:focus-visible outline on every interactive control✅ Shipped
Performance
14Background-tab suspensionPresentationvisibilitychange → frameloop="never": no GPU work when hidden✅ Shipped
15Tiered fill costCanvasDevice-derived DPR clamp, adaptive regression while scrolling, alpha:false, powerPreference:"high-performance"✅ Shipped
16Allocation-free render loopIndustrialSceneModule-level vectors + refs; no per-frame object churn✅ Shipped
17React-free label updatesFocusFadeLabelOpacity written straight to the DOM node inside useFrame✅ Shipped
Resilience & platform
18Recoverable engine failureExperienceBoundaryClass boundary with a retry action and telemetry-friendly logging✅ Shipped
19Database-optional runtimedb/index.tsPool constructed lazily; importing the module never throws✅ Shipped
20Bounded connection pooldb/index.tsmax clamped to 1–50, 5 s connect timeout, 30 s idle reap✅ Shipped
21Honest health contractapi/health200 live · 503 only when a configured database is unreachable✅ Shipped
22Production security headersnext.config.tsCSP plus eight defense headers, including HSTS preload in production builds✅ Shipped
23Animated social cardtools/og-imageReproducible 1200×630 GIF + PNG fallback from design tokens✅ Shipped
24Scenario-consistent evidencelib/export.tsCSV rows and executive JSON summaries derive from the selected scenario; JSON includes illustrative provenance✅ Shipped
25Honest simulation stateLiveTelemetryFeedBilingual fixture-simulation disclosure; no interval or audio work while closed✅ Shipped
26Native modal lifecycleuseNativeDialogPlatform modality and Escape handling, deterministic initial focus, invoker-focus restoration✅ Shipped
27Calculator provenanceRecoveryCalculator / HandoutViewBilingual fixed-assumption disclosure; illustrative, not a forecast✅ Shipped
28Context-safe global shortcutslib/keyboard.tsSection keys yield to focused controls, IME composition, handled events, modifiers, and open modals✅ Shipped
29Accessible operating modesScenarioSwitcher / LiveTelemetryFeedRoving radio focus, arrow/Home/End selection, localized pressed filters, and truthful running/paused status✅ Shipped
+ + + +## 03 / ENGINEERING ARCHITECTURE ### Runtime boundaries @@ -160,64 +178,109 @@ focus(offset, i) = clamp(1 − |pagePosition − i| / 1.08, 0, 1) | [`src/lib/useNativeDialog.ts`](LOGISDATA/src/lib/useNativeDialog.ts) | Shared native modal lifecycle | Initial focus, Escape/platform close, and invoker-focus restoration | | [`src/lib/types.ts`](LOGISDATA/src/lib/types.ts) | Domain types | `LocalizedText` makes an untranslated string a compile error | | [`src/db/index.ts`](LOGISDATA/src/db/index.ts) | Lazy, bounded PostgreSQL pool | Never constructed at import time | -| [`src/app/api/health/route.ts`](LOGISDATA/src/app/api/health/route.ts) | Liveness + optional readiness | Honest status codes — see [Operations](#-operations) | +| [`src/app/api/health/route.ts`](LOGISDATA/src/app/api/health/route.ts) | Liveness + optional readiness | Honest status codes — see [Operations](#operations) | | [`tools/og-image/`](tools/og-image) | Deterministic social-card renderer | Regenerates the animated GIF from design tokens | ---- + -## ▸ Feature Matrix +## 04 / SYSTEM BLUEPRINT - - - - - +### Topology - - - - - - +```mermaid +flowchart LR + classDef edge fill:#0b1c2a,stroke:#4de1c1,stroke-width:1px,color:#edf7fb + classDef srv fill:#10283a,stroke:#7dd3fc,stroke-width:1px,color:#edf7fb + classDef cli fill:#0b1c2a,stroke:#f59e0b,stroke-width:1px,color:#edf7fb + classDef opt fill:#0b1c2a,stroke:#6e8795,stroke-width:1px,stroke-dasharray:4 3,color:#a8becb - - - - - + visitor["Visitor
desktop · tablet · mobile"]:::edge - - - - - + subgraph server["Next.js App Router — server"] + direction TB + layout["layout.tsx
metadata · OG · fonts"]:::srv + page["page.tsx
server component"]:::srv + health["api/health
nodejs · force-dynamic"]:::srv + end - - - - - + subgraph client["Client experience — use client"] + direction TB + shell["PresentationShell
capability probe + error boundary"]:::cli + loader["EngineLoader
static, engine-free"]:::cli + pres["Presentation
nav · prefs · keyboard"]:::cli + canvas["Canvas · ScrollControls
single WebGL context"]:::cli + rig["IndustrialScene
camera rig + focus curve"]:::cli + scenes["5 scene groups
network · scanner · matrix · terrain · grid"]:::cli + html["5 HTML sections
semantic tables + charts"]:::cli + end - - - - - - - - - - - - - + subgraph domain["Domain layer — pure TypeScript"] + direction TB + data["lib/data.ts
typed audit model"]:::srv + i18n["lib/i18n.ts
Intl EN/AR formatters"]:::srv + focus["lib/sceneFocus.ts
shared focus curve"]:::srv + end - -
#CapabilitySurfaceImplementationState
Experience
01Five-stage audit narrativesections/*Full-viewport sections bound to a shared section index✅ Shipped
02Synchronized 3D modelsthree/*Supply network, laser audit gate, demand matrix, route terrain, warehouse grid✅ Shipped
03Cinematic camera choreographyIndustrialSceneDual-target interpolation with frame-rate-independent damping✅ Shipped
04Deferred engine bootPresentationShellnext/dynamic + ssr:false after the WebGL capability probe; no cover-screen CTA✅ Shipped
05Animated metric countersMetricCounterIntersectionObserver (0.35) → rAF cubic ease-out over 1250 ms✅ Shipped
Localization
06English / Arabic paritylib/data.tsEvery copy node is LocalizedText; the compiler enforces coverage✅ Shipped
07Native RTL inversionPresentationdocumentElement.dir + lang flipped on toggle; CSS logical properties✅ Shipped
08Locale-correct numeralslib/i18n.tsIntl.NumberFormat with ar-EG digits and compact USD✅ Shipped
09Arabic display typography@fontsource-variable/cairoSelf-hosted variable font — no third-party font request✅ Shipped
Accessibility
10Keyboard navigationPresentationArrows · Page Up/Down · Home · End, with modifier and text-field guards✅ Shipped
11Semantic analyticssections/*Real <table> markup, aria-labelledby, aria-current="step"✅ Shipped
12Motion reductionuseReducedMotionProgrammatic scrolling drops to behavior: "auto"✅ Shipped
13Visible focus statesglobals.css:focus-visible outline on every interactive control✅ Shipped
Performance
14Background-tab suspensionPresentationvisibilitychange → frameloop="never": no GPU work when hidden✅ Shipped
15Tiered fill costCanvasDevice-derived DPR clamp, adaptive regression while scrolling, alpha:false, powerPreference:"high-performance"✅ Shipped
16Allocation-free render loopIndustrialSceneModule-level vectors + refs; no per-frame object churn✅ Shipped
17React-free label updatesFocusFadeLabelOpacity written straight to the DOM node inside useFrame✅ Shipped
Resilience & platform
18Recoverable engine failureExperienceBoundaryClass boundary with a retry action and telemetry-friendly logging✅ Shipped
19Database-optional runtimedb/index.tsPool constructed lazily; importing the module never throws✅ Shipped
20Bounded connection pooldb/index.tsmax clamped to 1–50, 5 s connect timeout, 30 s idle reap✅ Shipped
21Honest health contractapi/health200 live · 503 only when a configured database is unreachable✅ Shipped
22Production security headersnext.config.tsCSP plus eight defense headers, including HSTS preload in production builds✅ Shipped
23Animated social cardtools/og-imageReproducible 1200×630 GIF + PNG fallback from design tokens✅ Shipped
24Scenario-consistent evidencelib/export.tsCSV rows and executive JSON summaries derive from the selected scenario; JSON includes illustrative provenance✅ Shipped
25Honest simulation stateLiveTelemetryFeedBilingual fixture-simulation disclosure; no interval or audio work while closed✅ Shipped
26Native modal lifecycleuseNativeDialogPlatform modality and Escape handling, deterministic initial focus, invoker-focus restoration✅ Shipped
27Calculator provenanceRecoveryCalculator / HandoutViewBilingual fixed-assumption disclosure; illustrative, not a forecast✅ Shipped
28Context-safe global shortcutslib/keyboard.tsSection keys yield to focused controls, IME composition, handled events, modifiers, and open modals✅ Shipped
29Accessible operating modesScenarioSwitcher / LiveTelemetryFeedRoving radio focus, arrow/Home/End selection, localized pressed filters, and truthful running/paused status✅ Shipped
+ subgraph plane["Optional data plane"] + direction TB + db["db/index.ts
lazy bounded pool"]:::opt + pg[("PostgreSQL
Drizzle ORM")]:::opt + end ---- + visitor --> layout --> page --> shell + shell --> loader + shell -. "dynamic import once WebGL is confirmed" .-> pres + pres --> canvas --> rig --> scenes + canvas --> html + scenes --> focus + html --> data + scenes --> data + html --> i18n + visitor --> health --> db -. "only if DATABASE_URL" .-> pg +``` -## ▸ Core Workflows +### Scroll-driven camera choreography + +One scroll offset drives the camera, every scene transform and every label's opacity — deriving all of them from a single number is what keeps 3D and HTML in lockstep at any frame rate. + +```mermaid +flowchart LR + classDef n fill:#0b1c2a,stroke:#4de1c1,color:#edf7fb + classDef o fill:#10283a,stroke:#7dd3fc,color:#edf7fb + + s["scroll.offset
0 → 1"]:::n --> p["page = offset × (5 − 1)"]:::n + p --> i["current = floor(page)
local = page − current"]:::n + i --> t["transition = smoothstep(local)"]:::n + t --> cam["camera position + lookAt
lerp → exponential damp"]:::o + p --> f["focus = clamp(1 − abs(page − index) ÷ 1.08)"]:::n + f --> sc["group scale 0.56 → 1.00"]:::o + f --> lb["label opacity + visibility"]:::o + s --> native["native scroll geometry
sectionFromScrollTop"]:::n + native --> ui["hash · nav highlight · progress · live region"]:::o +``` + +### Health and readiness + +```mermaid +flowchart TD + classDef q fill:#10283a,stroke:#7dd3fc,color:#edf7fb + classDef ok fill:#0b1c2a,stroke:#4de1c1,color:#edf7fb + classDef bad fill:#0b1c2a,stroke:#fb5b5b,color:#edf7fb + + a["GET /api/health"]:::q --> b{"DATABASE_URL set"}:::q + b -- no --> c["database: not-configured
HTTP 200"]:::ok + b -- yes --> d["race: SELECT 1 vs 2000 ms timeout"]:::q + d -- resolves --> e["database: ready
HTTP 200"]:::ok + d -- rejects or timeout --> f["database: unavailable
HTTP 503"]:::bad + g["HEAD /api/health"]:::q --> h["HTTP 204 · no body · no DB touch"]:::ok +``` + +> [!TIP] +> Point container **liveness** probes at `HEAD /api/health` (cheap, never touches the pool) and **readiness** probes at `GET`. A presentation with no database attached stays healthy by design — it is not degraded, it is simply stateless. + + + +## 05 / EXECUTION INTELLIGENCE ### W-01 · Cold start and engine handoff @@ -244,27 +307,7 @@ sequenceDiagram Note over S,P: Any throw inside P is caught by ExperienceBoundary →
"Retry engine" panel instead of a blank document ``` -### W-02 · Scroll-driven camera choreography - -One scroll offset drives the camera, every scene transform and every label's opacity — deriving all of them from a single number is what keeps 3D and HTML in lockstep at any frame rate. - -```mermaid -flowchart LR - classDef n fill:#0b1c2a,stroke:#4de1c1,color:#edf7fb - classDef o fill:#10283a,stroke:#7dd3fc,color:#edf7fb - - s["scroll.offset
0 → 1"]:::n --> p["page = offset × (5 − 1)"]:::n - p --> i["current = floor(page)
local = page − current"]:::n - i --> t["transition = smoothstep(local)"]:::n - t --> cam["camera position + lookAt
lerp → exponential damp"]:::o - p --> f["focus = clamp(1 − abs(page − index) ÷ 1.08)"]:::n - f --> sc["group scale 0.56 → 1.00"]:::o - f --> lb["label opacity + visibility"]:::o - s --> native["native scroll geometry
sectionFromScrollTop"]:::n - native --> ui["hash · nav highlight · progress · live region"]:::o -``` - -**Guarantees** +### W-02 · Guarantees of the choreography - URL, navigation, progress, and live-region state derive from the native scroll event—not the GPU frame loop—so they remain correct when rendering is throttled or suspended. - Damping uses `1 − e^(−k·Δt)`, which is frame-rate independent across 30, 60, and 144 Hz. @@ -292,7 +335,7 @@ sequenceDiagram Theme follows the same pattern against `logisdata.theme`, additionally setting `colorScheme` so native form controls and scrollbars match the active surface. -### W-04 · Freight invoice audit (the domain loop the product exists for) +### W-04 · Freight invoice audit — the domain loop the product exists for | Step | Input | Control | Output | | :--- | :--- | :--- | :--- | @@ -304,73 +347,9 @@ Theme follows the same pattern against `logisdata.theme`, additionally setting ` The HTML table renders the ledger; the `AuditScanner` scene renders the same rows as a laser gate reconciling telemetry against contract. Both read the identical array — there is no "presentation copy" of the numbers that can drift from the model. -### W-05 · Health and readiness - -```mermaid -flowchart TD - classDef q fill:#10283a,stroke:#7dd3fc,color:#edf7fb - classDef ok fill:#0b1c2a,stroke:#4de1c1,color:#edf7fb - classDef bad fill:#0b1c2a,stroke:#fb5b5b,color:#edf7fb - - a["GET /api/health"]:::q --> b{"DATABASE_URL set"}:::q - b -- no --> c["database: not-configured
HTTP 200"]:::ok - b -- yes --> d["race: SELECT 1 vs 2000 ms timeout"]:::q - d -- resolves --> e["database: ready
HTTP 200"]:::ok - d -- rejects or timeout --> f["database: unavailable
HTTP 503"]:::bad - g["HEAD /api/health"]:::q --> h["HTTP 204 · no body · no DB touch"]:::ok -``` - -> [!TIP] -> Point container **liveness** probes at `HEAD /api/health` (cheap, never touches the pool) and **readiness** probes at `GET`. A presentation with no database attached stays healthy by design — it is not degraded, it is simply stateless. - -### W-06 · Social preview generation - -```bash -cd tools/og-image && npm install -npm run build # → LOGISDATA/public/og-image-animated.gif + og-image.png -``` - -The renderer reads the same tokens as `globals.css` and the same graph as `lib/data.ts`, so the card cannot drift from the product. See [Social preview pipeline](#-social-preview-pipeline). - ---- - -## ▸ Tech Stack - -### Application runtime - -| Layer | Technology | Version | Why it is here | -| :--- | :--- | :--- | :--- | -| Framework | **Next.js** (App Router) | `^16.3.7` | Server components for the shell, route handlers for health, first-class code splitting for the engine boundary | -| UI runtime | **React** | `19.2.6` | Concurrent rendering; `useState` initializers read persisted preferences without a flash | -| Language | **TypeScript** | `5.9.3` | `strict: true`; `LocalizedText` turns a missing translation into a build failure | -| 3D | **Three.js** | `^0.185.1` | Industry-standard WebGL abstraction with a predictable memory model | -| 3D bindings | **@react-three/fiber** | `^9.7.0` | Declarative scene graph; `useFrame` for allocation-free animation | -| 3D helpers | **@react-three/drei** | `^10.7.7` | `ScrollControls`, `Scroll`, `Html`, `Line`, `Float` | -| Motion | **Framer Motion** | `^12.43.0` | Entry choreography plus `useReducedMotion` as a first-class input | -| Icons | **lucide-react** | `^1.48.0` | Tree-shaken SVG icons, no icon font | -| Styling | **Tailwind CSS 4** + CSS custom properties | `4.1.17` | Utility layer for structure, tokenized variables for theme and RTL | -| Typography | **Cairo Variable** | `^5.3.0` | One self-hosted variable face that covers Latin and Arabic | - -### Data plane (optional) - -| Layer | Technology | Version | Why it is here | -| :--- | :--- | :--- | :--- | -| ORM | **Drizzle ORM** | `0.45.2` | Typed SQL with zero runtime reflection | -| Driver | **node-postgres** | `8.20.0` | Explicit, bounded pooling with predictable timeouts | -| Migrations | **drizzle-kit** | `^0.31.11` | `schema.ts` is intentionally empty — the deck owns no tables yet | - -### Toolchain and asset pipeline - -| Layer | Technology | Version | Why it is here | -| :--- | :--- | :--- | :--- | -| Linting | **ESLint 9** flat config + `eslint-config-next` | `9.39.4` | Core Web Vitals ruleset, `.next`/`out`/`build` globally ignored | -| CSS build | **@tailwindcss/postcss** | `4.1.17` | Tailwind 4 pipeline without a legacy PostCSS chain | -| Supply chain | **`overrides.esbuild`** | `0.25.12` | Pins a transitive dependency to keep `npm audit` at zero findings | -| OG renderer | **@napi-rs/canvas** + **gifenc** | see [`tools/og-image`](tools/og-image) | Deterministic vector rasterization and a hand-tuned GIF encoder | + ---- - -## ▸ Quickstart +## 06 / IGNITION **Requirements** — Node.js 22+, npm. A GPU is recommended but not required; the experience degrades gracefully through `ExperienceBoundary`. @@ -417,11 +396,63 @@ curl -s localhost:3000/api/health | jq | `npm run budget` | Gzipped landing payload against a 205,000 B ceiling; current measured result 202,616 B | ✅ | | `npm run check` | Types, lint, unit tests, and production build in sequence | ✅ | ---- + + +## 07 / DEEP SYSTEM ACCESS + +
+Application runtime — framework, 3D, motion, typography + +
+ +| Layer | Technology | Version | Why it is here | +| :--- | :--- | :--- | :--- | +| Framework | **Next.js** (App Router) | `^16.3.7` | Server components for the shell, route handlers for health, first-class code splitting for the engine boundary | +| UI runtime | **React** | `19.2.6` | Concurrent rendering; `useState` initializers read persisted preferences without a flash | +| Language | **TypeScript** | `5.9.3` | `strict: true`; `LocalizedText` turns a missing translation into a build failure | +| 3D | **Three.js** | `^0.185.1` | Industry-standard WebGL abstraction with a predictable memory model | +| 3D bindings | **@react-three/fiber** | `^9.7.0` | Declarative scene graph; `useFrame` for allocation-free animation | +| 3D helpers | **@react-three/drei** | `^10.7.7` | `ScrollControls`, `Scroll`, `Html`, `Line`, `Float` | +| Motion | **Framer Motion** | `^12.43.0` | Entry choreography plus `useReducedMotion` as a first-class input | +| Icons | **lucide-react** | `^1.48.0` | Tree-shaken SVG icons, no icon font | +| Styling | **Tailwind CSS 4** + CSS custom properties | `4.1.17` | Utility layer for structure, tokenized variables for theme and RTL | +| Typography | **Cairo Variable** | `^5.3.0` | One self-hosted variable face that covers Latin and Arabic | + +
-## ▸ Operations +
+Data plane (optional) — ORM, driver, migrations + +
+ +| Layer | Technology | Version | Why it is here | +| :--- | :--- | :--- | :--- | +| ORM | **Drizzle ORM** | `0.45.2` | Typed SQL with zero runtime reflection | +| Driver | **node-postgres** | `8.20.0` | Explicit, bounded pooling with predictable timeouts | +| Migrations | **drizzle-kit** | `^0.31.11` | `schema.ts` is intentionally empty — the deck owns no tables yet | -### Health endpoint contract +
+ +
+Toolchain and asset pipeline + +
+ +| Layer | Technology | Version | Why it is here | +| :--- | :--- | :--- | :--- | +| Linting | **ESLint 9** flat config + `eslint-config-next` | `9.39.4` | Core Web Vitals ruleset, `.next`/`out`/`build` globally ignored | +| CSS build | **@tailwindcss/postcss** | `4.1.17` | Tailwind 4 pipeline without a legacy PostCSS chain | +| Supply chain | **`overrides.esbuild`** | `0.25.12` | Pins a transitive dependency to keep `npm audit` at zero findings | +| OG renderer | **@napi-rs/canvas** + **gifenc** | see [`tools/og-image`](tools/og-image) | Deterministic vector rasterization and a hand-tuned GIF encoder | + +
+ + + +
+Operations — health endpoint contract + +
```http GET /api/health # readiness — Cache-Control: no-store @@ -447,7 +478,12 @@ HEAD /api/health # liveness — 204, no body, no pool access | `SELECT 1` succeeds | `ready` | `200` | Fully operational | | Unreachable or >2 s | `unavailable` | `503` | Page the on-call, not the presenter | -### Security posture +
+ +
+Operations — security posture + +
Applied to every route by [`next.config.ts`](LOGISDATA/next.config.ts). Production responses carry nine security headers; API responses additionally carry `Cache-Control: no-store, max-age=0`. @@ -465,9 +501,14 @@ Applied to every route by [`next.config.ts`](LOGISDATA/next.config.ts). Producti `poweredByHeader` is disabled, `compress` is enabled and `reactStrictMode` is on. ---- +
+ + + +
+Social preview pipeline — the compiled Open Graph card -## ▸ Social preview pipeline +
The Open Graph card is not a screenshot — it is **compiled**, from the same tokens and the same graph data the product renders. @@ -524,13 +565,52 @@ node generate-og.mjs --frame=13 # inspect any single frame Metadata is wired in [`src/app/layout.tsx`](LOGISDATA/src/app/layout.tsx): the animated GIF is listed first for both `openGraph.images` and `twitter.images`, with the PNG immediately behind it for scrapers that cannot decode GIF. Set `NEXT_PUBLIC_SITE_URL` in production so both resolve to absolute URLs. ---- +
+ + + +## 08 / ENGINEERING STATUS -## ▸ Repository layout +### The README hero asset + +The cinematic hero at the top of this document is an **original, procedurally rendered animation** produced for this repository — not a screenshot, not stock footage, not a typing banner. + +| Property | Value | +| :--- | :--- | +| Animated hero | [`assets/readme/yaslogist-hero.gif`](assets/readme/yaslogist-hero.gif) | +| Static poster | [`assets/readme/yaslogist-hero.png`](assets/readme/yaslogist-hero.png) | +| Geometry | `1920 × 720` (2.67:1 — full README content width) | +| Motion | 125 frames · 80 ms · **10.0 s seamless loop** | +| Scene | The real 8-node / 10-edge supply graph from `lib/data.ts`, the five audit theatres, the audit-gate sweep, and the illustrative $2.1T / 3.8% / 6.4x metrics | +| Compression | 255-colour global palette, 8×8 Bayer dither, inter-frame deltas | +| Weight | 7.3 MB · poster 282 KB | +| Supporting motion | [`kinetic-statement.svg`](assets/readme/kinetic-statement.svg) · [`divider-pulse.svg`](assets/readme/divider-pulse.svg) · [`yaslogist-signature.svg`](assets/readme/yaslogist-signature.svg) | + +Every animated quantity in the hero is periodic over the loop, so the wrap step measures the same as any interior frame step — there is no seam, no flash and no reset. + +### Shipped versus illustrative + +| Category | State | +| :--- | :--- | +| All 29 capability-matrix rows | ✅ **Implemented and tested** — unit suite locally, full browser suite in CI | +| Architecture diagrams, module map, health contract | ✅ **Verified against source** at the documented commit | +| Metrics, freight rows, demand tiers, routes, bins | ⚠️ **Illustrative model data** — presentation-realistic, not extracted from production systems | +| PostgreSQL layer | ⚠️ **Optional and dormant** — `schema.ts` is empty; the deck owns no tables | + +> [!WARNING] +> Every figure in this deck is **illustrative and presentation-realistic** — modelled to be defensible in an executive conversation, not extracted from a production system. Validate against authoritative ERP, TMS, WMS, invoice and telematics sources before any operational or investment decision. The architecture is built so that swapping `lib/data.ts` for a live adapter changes no component contract. + +### Repository layout ```text LOGISDATA/ -├── README.md this whitepaper +├── README.md this document +├── assets/readme/ cinematic hero, poster and secondary motion +│ ├── yaslogist-hero.gif animated README hero (primary) +│ ├── yaslogist-hero.png static poster (fallback) +│ ├── kinetic-statement.svg cycling technical statement +│ ├── divider-pulse.svg luminous section divider +│ └── yaslogist-signature.svg closing brand animation ├── LOGISDATA/ the Next.js application │ ├── public/ │ │ ├── og-image-animated.gif animated social card (primary) @@ -545,20 +625,34 @@ LOGISDATA/ └── og-image/ deterministic OG card renderer ``` ---- + -## ▸ Data policy +## 09 / YASLOGIST -> [!WARNING] -> Every figure in this deck is **illustrative and presentation-realistic** — modelled to be defensible in an executive conversation, not extracted from a production system. Validate against authoritative ERP, TMS, WMS, invoice and telematics sources before any operational or investment decision. The architecture is built so that swapping `lib/data.ts` for a live adapter changes no component contract. +
+YASLOGIST — engineering signature, yaslogist.com +
---- +
+ +**LOGISDATA** is the product. **YASLOGIST** is the permanent engineering signature beneath it — the creative-technical system this control room is designed, rendered and documented under. + +| | | +| :--- | :--- | +| **Product identity** | LOGISDATA — Supply-Chain Audit Control Room | +| **Signature** | YASLOGIST | +| **Website** | [yaslogist.com](https://www.yaslogist.com) | +| **Repository** | [github.com/YASLOGIST/LOGISDATA](https://github.com/YASLOGIST/LOGISDATA) |
+*Control the signal. Protect the margin.* + **Ahmed Yasser Ali** · Reg. `211010269` Arab Academy for Science, Technology & Maritime Transport — Executive Data Lab -*Control the signal. Protect the margin.* +
+ +© YASLOGIST · LOGISDATA v3.1.0 · engineered, animated and documented as one visual system
diff --git a/assets/readme/divider-pulse.svg b/assets/readme/divider-pulse.svg new file mode 100644 index 0000000..d00d765 --- /dev/null +++ b/assets/readme/divider-pulse.svg @@ -0,0 +1,42 @@ + + LOGISDATA — luminous section divider + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/readme/kinetic-statement.svg b/assets/readme/kinetic-statement.svg new file mode 100644 index 0000000..2359422 --- /dev/null +++ b/assets/readme/kinetic-statement.svg @@ -0,0 +1,42 @@ + + LOGISDATA — kinetic technical statement + + + + + + + + + + + + + + + + + + 01 · FREIGHT BILLING × TELEMETRY — RECONCILED ON ONE CANVAS + + + + 02 · CONSUMER DEMAND × ORDER AMPLIFICATION — QUANTIFIED + + + + 03 · PLANNED ROUTES × GPS REALITY — RECONCILED + + + + 04 · WMS MASTER DATA × PHYSICAL SHELF — VERIFIED + + + + + + + + + + diff --git a/assets/readme/yaslogist-hero.gif b/assets/readme/yaslogist-hero.gif new file mode 100644 index 0000000..5954b8a Binary files /dev/null and b/assets/readme/yaslogist-hero.gif differ diff --git a/assets/readme/yaslogist-hero.png b/assets/readme/yaslogist-hero.png new file mode 100644 index 0000000..dfa5762 Binary files /dev/null and b/assets/readme/yaslogist-hero.png differ diff --git a/assets/readme/yaslogist-signature.svg b/assets/readme/yaslogist-signature.svg new file mode 100644 index 0000000..5dc3c0e --- /dev/null +++ b/assets/readme/yaslogist-signature.svg @@ -0,0 +1,70 @@ + + YASLOGIST — engineering signature + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ENGINEERING SIGNATURE + + + + YASLOGIST + + + + YASLOGIST + + + + + + + + + + + + + + + + + + + + yaslogist.com +