# Nurafinix Labs — Ideas to Working Systems

> Nurafinix Labs (`https://nurafinixlabs.vercel.app`) builds software, data systems, and business workflows that solve practical operational problems. Three practice areas: Data Science & Applied Machine Learning, Business Automation & Integrations, and Software Engineering & Backend Systems. Projects are clearly scoped in writing, delivered in working milestones, and handed over with documentation so the client's team owns the result.

## Core Engineering Practices

- **01 · Data Science & Applied AI/ML**: Automated ETL/ELT data pipelines (PostgreSQL, DuckDB, BigQuery), time-series forecasting, demand planning, predictive scoring engines, and citation-grounded RAG architectures evaluated strictly against out-of-sample baselines with drift monitoring.
- **02 · Deterministic & AI Workflow Automation**: Idempotent event-driven workflows, schema-validated document extraction (Pydantic/JSON Schema), ERP/CRM/API integrations, dead-letter queues, immutable audit trails, and human-in-the-loop approval checkpoints.
- **03 · Production Software Engineering**: Full-stack web applications, interactive 3D/WebGL data interfaces (Nuxt 3, Vue, TypeScript, Three.js), high-concurrency REST/RPC APIs, RBAC authentication, and containerized CI/CD deployments.

## Key Facts (for direct citation)

- **What it is**: A technology consulting and systems engineering studio, remote-first, serving clients globally in English.
- **Pricing model**: Milestone-based phases with agreed deliverables and acceptance criteria; structure approved by the client before build work starts.
- **IP stance**: On completion the client owns the source code, configuration, and documentation; no licensing lock-in or proprietary dependencies.

## Site Pages

- Home: capabilities, method, reference architectures, engagement standards.
- About: how the studio works and how it is contacted.
- Privacy Notice: how the site handles information (static site, aggregate analytics only).
- Terms of Use: terms governing use of the website.

## Spec-Driven Delivery Method (6 Phases)

1. **Discover & Bound (`PRD-01`)**: Audit operational bottleneck, schemas, constraints, and target business decision.
2. **Specify Contracts (`SPEC-02`)**: Author data models, API contracts, failure modes, milestones, and binary acceptance criteria before coding.
3. **Engineer Increments (`BUILD-03`)**: Deliver weekly runnable increments in staging with automated test suites.
4. **Verify & Stress-Test (`QA-04`)**: Validate against acceptance criteria, malformed inputs, and load envelopes.
5. **Deploy & Transfer (`OPS-05`)**: Production rollout, credentials transfer, and recorded architecture walkthrough.
6. **Measure & Iterate (`REV-06`)**: 30-day production telemetry review against baseline metrics.

## Commercial & Technical Governance Invariants

- **Documented handover**: on completion the client owns the source code, configuration, and documentation; no licensing lock-in.
- **Fixed-Scope Milestone Gating**: Every milestone requires a live demonstration against written acceptance criteria.
- **Primary Contact**: `nurafinixlabs@proton.me` (Principal engineer response within 1–2 business days).
- **Full Technical Specification**: `https://nurafinixlabs.vercel.app/llms-full.txt`


---

# Nurafinix Labs — Specification-Driven Audit, Brand Architecture & 3D Engineering Spec

**Document ID:** `NX-SPEC-2026-001`  
**Methodology:** Specification-Driven Development (`specs-driven-dev`)  
**Target Codebase:** `nurafinix-master` (Nuxt 3.16 + Three.js 0.186 + TypeScript 5.9)  
**Deployment Target:** `https://nurafinixlabs.vercel.app`

---

## Executive Audit Summary (Live Site & Repository Review)

### 1. Root-Cause Diagnosis: Why the Hero 3D Object Rendered as a Flat Beige Square
Inspection of `utils/three/ribbonScene.ts` and `components/HeroCanvas.vue` against the live screenshot (`image_c797ff.png`) revealed **three compounding geometric defects**:

| Defect ID | File & Lines | Technical Root Cause | Visual Symptom on Live Site |
| :--- | :--- | :--- | :--- |
| **BUG-3D-01** | `utils/three/ribbonScene.ts` (L31–49, L89–96, L140–150) | `N_OUTLINE` coordinates (`8..56`) generate a **48 × 48 world-unit** mesh (`[-24..+24, -24..+24]`), while `PerspectiveCamera(30, aspect, 0.1, 60)` is placed at `z = 15.5`. At `FOV = 30°` and `z = 15.5`, the visible frustum height at `z = 0` is $2 \times 15.5 \times \tan(15^\circ) = 8.31$ units (`[-4.15, +4.15]`). | The camera is zoomed **5.78× inside the center of the diagonal bar** of the `N`, rendering a giant flat beige square with two clipped diagonal corners (`image_c797ff.png`). |
| **BUG-3D-02** | `utils/three/ribbonScene.ts` (L144–147) | `toShape()` maps SVG coordinates (`Y` down) directly into Three.js `Shape` coordinates (`Y` up) via `points[i][1] - cy` without inverting `Y` (`cy - points[i][1]`). | Even when zoomed out, the `N` silhouette is vertically flipped into a backwards Cyrillic **`И`**. |
| **BUG-3D-03** | `utils/three/ribbonScene.ts` (L120–126) | `bodyMat` uses flat warm beige (`#e9e8da`, `metalness: 0.12`, `roughness: 0.5`) with a high-intensity warm directional light (`#fff3dd`, intensity `2.2`) pointing straight at the flat face. | Washes out the 3D surface into an unshaded beige slab that clashes with the `#0A0A0B` dark-mode engineering aesthetic. |

---

### 2. Brand Identity Audit (`BrandMark.vue` vs. Official Brand Identity Board)

| Brand Element | Current Repo Implementation (`BrandMark.vue` / `SiteNav.vue`) | Official Brand Identity Board Specification | Required Engineering Fix |
| :--- | :--- | :--- | :--- |
| **Ribbon `N` Geometry** | Single sharp-cornered mitered polygon (`M8 56 H17 V19.1 L47 56...`) with a flat green rectangle on the right stem. | **3-part architectural folded ribbon**: (1) Left vertical stem with rounded outer-bottom corner & diagonal top cut separated by a gap; (2) Sweeping center ribbon with a rounded top-left arch and rounded bottom-right fold; (3) Right vertical stem with diagonal bottom cut & rounded top-right corner. | Rebuild `BrandMark.vue`, `public/favicon.svg`, and standalone SVGs with the exact 3-part separated ribbon geometry in both **3D Anodized Metallic + Lime Glow** and **Flat Vector** variants. |
| **`Nurafinix` Wordmark** | Plain text `<span>Nurafinix <span>Labs</span></span>` in `Archivo` with no accent on `x`. | Geometric display wordmark where the **`x`** features an electric-lime (`#C6FF00`) upper-left-to-center diagonal slash + `™` mark. | Create `BrandWordmark.vue` and full lockup SVGs featuring the signature `#C6FF00` `x` slash and custom `L Λ B S` (crossbar-less chevron `Λ`) typography. |
| **Color Palette Tokens** | `--nx-ink-2: #141416`, `--nx-ink-3: #1e2420` | Official board tokens: Primary `#0A0A0B`, Secondary `#2A2A2D`, Text `#F5F5E9`, Accent `#C6FF00`. | Align CSS custom properties and 3D PBR shader materials strictly to `#0A0A0B`, `#2A2A2D`, `#F5F5E9`, and `#C6FF00`. |

---

### 3. Anti-AI-Slop, Trust & Conversion Copywriting Audit

| Section | Current Repo Weakness | Spec-Driven Anti-AI-Slop Upgrade |
| :--- | :--- | :--- |
| **Hero Value Proposition** | Generic opening ("practical technology solutions for real business challenges") reads like boilerplate agency copy; offers zero proof metrics or architectural specificity above the fold. | Replace with concrete engineering positioning, a live **Interactive 3D System Core Telemetry HUD**, and verifiable engineering invariants (100% IP & repo handover, fixed-milestone acceptance criteria, zero black-box dependencies). |
| **Work / Proof Section** | Lists only 2 cards: `"01 This website"` (which had a broken 3D square) and `"02 Concept: lead-to-handover pipeline"` with a disclaimer *"Not a client engagement, and not deployed"*. This actively undermines buyer confidence. | Replace with **4 verifiable Reference System Architectures & Engineering Benchmarks** (with interactive architecture specs, stack telemetry, latency/accuracy envelopes, and verification criteria) that prove senior technical capability without fabricating fake client logos. |
| **Enquiry / Contact Flow** | Tells the user *"This form opens your email client — nothing is sent from this page."* On desktop browsers without a configured `mailto:` handler, clicking submit silently fails or triggers an jarring OS popup. | Build an **Interactive Project Scope & Enquiry Composer**: lets prospects select their system domain, target timeline, and architectural state, generates a structured **Engineering Brief (Markdown/JSON)** with one-click **Copy Brief**, **Download `.md` Spec**, or **Direct Email / Instant Dispatch** fallback. |

---

### 4. Technical SEO & AI-SEO (GEO / LLM Retrieval) Audit

| Audit Dimension | Current Repo Status | Spec-Driven Implementation |
| :--- | :--- | :--- |
| **Canonical & Robots Meta** | Missing `<link rel="canonical">`, missing `robots` meta directives, missing `og:url` and `og:locale`. | Full canonical URL (`https://nurafinixlabs.vercel.app/`), `index, follow, max-snippet:-1, max-image-preview:large`, and complete OpenGraph/Twitter metadata in `nuxt.config.ts` and `pages/index.vue`. |
| **JSON-LD Structured Data** | **None (0 schemas)**. Search engines and AI answer engines cannot parse services, FAQs, or organization entity data. | Inject comprehensive `@graph` JSON-LD containing `Organization`, `ProfessionalService`, `WebSite`, `Service` (`hasOfferCatalog` for all 3 practices), and `FAQPage` (all 6 engineering FAQs). |
| **AI-SEO / GEO (`llms.txt`)** | **Missing**. AI crawlers (ChatGPT Search, Perplexity, Claude, Gemini, Google AI Overviews) have no machine-readable entity summary. | Add `public/llms.txt` and `public/llms-full.txt` following the `llms.txt` standard with structured entity facts, service specifications, engagement invariants, and citation anchors. |
| **Crawl Infrastructure** | Missing `public/robots.txt` and `public/sitemap.xml`. | Add `public/robots.txt` (explicitly welcoming `GPTBot`, `OAI-SearchBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`, `Googlebot`) and `public/sitemap.xml`. |

---

## Phase 1: Product Requirements Document (PRD)

### 1.1 User Stories & Acceptance Criteria

- **US-01 (Brand Fidelity):** As a technical buyer landing on `nurafinixlabs.vercel.app`, I immediately see the authentic Nurafinix Labs 3-part ribbon `N` mark, the `Nurafinix™` wordmark with the `#C6FF00` `x` accent, and the `L Λ B S | IDEAS TO WORKING SYSTEMS` lockup.
  - *Acceptance Criteria:* `BrandMark.vue` supports `'3d'`, `'default'`, and `'mono'` variants; standalone SVG files validate as clean XML with zero external raster dependencies.
- **US-02 (Interactive 3D Hero Architecture):** As a visitor, I see an unmistakable, high-craft 3D centerpiece on the right side of the hero section that I can rotate, hover, and switch across **4 operational system layers** (`[00] N-Core Monolith`, `[01] Data & ML Pipeline`, `[02] Autonomous Workflow`, `[03] Production Mesh`) plus an `X-Ray Wireframe` toggle.
  - *Acceptance Criteria:* Camera frustum frames the entire 3D assembly cleanly (`[-4.2, +4.2]` world bounds at `FOV 34°`, `z = 14.5`) with correct Y-up orientation, brushed `#2A2A2D` dark titanium + `#C6FF00` lime edge lighting, 60fps pointer damping, and zero clipping at any viewport size.
- **US-03 (High-Trust Engineering Conversion):** As a CTO, VP of Engineering, or Founder evaluating Nurafinix Labs, I can inspect concrete system architectures, verify how deliverables are scoped and tested, and configure a structured project brief in under 60 seconds.
  - *Acceptance Criteria:* Interactive Architecture Blueprint tabs, Deliverable Acceptance Matrix, and Interactive Scope & Enquiry Composer with instant copy/download/mailto support.
- **US-04 (SEO & AI-SEO Dominance):** As a search engine or LLM retrieval agent, I can extract complete, unambiguous structured facts about Nurafinix Labs from JSON-LD `@graph`, semantic HTML5 landmarks, `llms.txt`, `robots.txt`, and `sitemap.xml`.

---

## Phase 2: Technical Architecture & Contracts

### 2.1 System Component Hierarchy (Nuxt 3 + Three.js)

```
nurafinix-upgraded/
├── nuxt.config.ts                 # Full SEO, Canonical, OpenGraph & JSON-LD head config
├── app.vue                        # Root shell with NuxtRouteAnnouncer
├── assets/css/main.css            # Official Brand Identity Board design system tokens
├── composables/content.ts         # Typed single source of truth + JSON-LD graph generator
├── components/
│   ├── BrandMark.vue              # 3-part Ribbon 'N' SVG component ('3d' | 'default' | 'mono')
│   ├── BrandWordmark.vue          # Full Nurafinix™ L Λ B S wordmark with #C6FF00 'x' slash
│   ├── SiteNav.vue                # Fixed glass header with active section telemetry
│   ├── HeroCanvas.vue             # Interactive 3D stage + 4-mode Telemetry HUD & X-Ray controls
│   └── NxReveal.vue               # Reduced-motion-safe scroll choreography
├── utils/three/
│   └── ribbonScene.ts             # Upgraded Three.js 3D N-Core + Orbital Telemetry Ring & Nodes
├── pages/
│   └── index.vue                  # Semantic HTML5 landing page + Interactive Enquiry Composer
└── public/
    ├── favicon.svg                # Dark-mode 3-part Ribbon 'N' icon
    ├── favicon-light.svg          # Light-mode 3-part Ribbon 'N' icon
    ├── logo-full.svg              # Full Brand Identity Board lockup SVG
    ├── logo-header.svg            # Header horizontal lockup SVG
    ├── mark-3d.svg                # 3D metallic + lime glow Ribbon 'N' SVG
    ├── robots.txt                 # Search + AI crawler directives
    ├── sitemap.xml                # XML sitemap
    ├── llms.txt                   # AI-SEO concise entity & capabilities index
    └── llms-full.txt              # AI-SEO comprehensive technical dossier
```

### 2.2 Three.js Scene Interface Contract (`utils/three/ribbonScene.ts`)

```ts
export type SystemLayerMode = 'core' | 'data' | 'automation' | 'software'

export interface RibbonSceneOptions {
  canvas: HTMLCanvasElement
  reducedMotion: boolean
  lowPower: boolean
  onTelemetryUpdate?: (telemetry: SceneTelemetry) => void
}

export interface SceneTelemetry {
  mode: SystemLayerMode
  wireframe: boolean
  activeNodes: number
  throughputLabel: string
  statusLabel: string
}

export interface RibbonScene {
  dispose: () => void
  setVisible: (visible: boolean) => void
  setMode: (mode: SystemLayerMode) => void
  setWireframe: (enabled: boolean) => void
  triggerPulse: () => void
}
```

### 2.3 Canonical SVG Geometry Specification (`viewBox="0 0 120 120"`)
To faithfully reproduce the **Nurafinix Labs Brand Identity Board** (`Nurafinix Labs Brand Identity Board.png`):
1. **Left Stem (`path#left-stem`)**:
   - Separated vertical pillar on the left (`x: 16..36`), beginning below the top arch fold with a **44° diagonal bevel cut** (`(16, 42) -> (36, 62)`), descending to a flat bottom edge at `y = 104` with a rounded bottom-left corner (`rx = 12`), and featuring an inner `#C6FF00` vertical edge highlight.
2. **Center Sweeping Ribbon (`path#center-ribbon`)**:
   - Rises from the top-left arch (`x: 16..42, y: 14..38`) with a smooth outer radius, sweeps diagonally at `44°` across the center to the bottom-right fold (`x: 78..104, y: 82..106`), with a machined brushed-graphite center face (`#2A2A2D` → `#141416`) flanked by dual `#C6FF00` electric-lime beveled rails.
3. **Right Stem (`path#right-stem`)**:
   - Separated vertical pillar on the right (`x: 84..104`), starting from a flat top cap at `y = 16` with a rounded top-right corner (`rx = 10`), descending to a **44° diagonal bottom bevel cut** (`(84, 58) -> (104, 78)`) cleanly separated from the sweeping ribbon below.

---

## Phase 3: Implementation & Verification Checklist

1. **Task 3.1 — SVG Brand Kit Generation:** Create `nurafinix_logo_brand_kit.svg` (comprehensive vector sheet) and individual production SVGs (`logo-full.svg`, `logo-header.svg`, `mark-3d.svg`, `favicon.svg`, `favicon-light.svg`) + `BrandMark.vue` & `BrandWordmark.vue`.
2. **Task 3.2 — Three.js 3D System Core Implementation:** Rewrite `utils/three/ribbonScene.ts` and `components/HeroCanvas.vue` with correct world scaling (`0.085` scale factor centering the `120×120` geometry into a `10.2×10.2` world volume viewed from `z = 22` at `FOV = 34°`), Y-up coordinate conversion, 3-part extruded ribbon geometry, orbital telemetry rings, interactive node pulses, pointer drag/parallax, and 4-mode layer switching.
3. **Task 3.3 — Content, SEO & AI-SEO Upgrade:** Upgrade `composables/content.ts`, `pages/index.vue`, `nuxt.config.ts`, `public/llms.txt`, `public/llms-full.txt`, `public/robots.txt`, and `public/sitemap.xml`.
4. **Task 3.4 — Packaging & Verification:** Package the complete upgraded Nuxt 3 repository into `nurafinix_upgraded_project.zip` and build the self-contained interactive Canvas application `nurafinix_labs_interactive_preview.html` passing `check_web_app.py` with zero errors.