HartOMat/ROADMAP.md

Schaeffler Automat — Master Roadmap

Consolidated: 2026-03-11 Branch: refactor/v2 Sources merged: PLAN.md (Phases A–F), PLAN_REFACTOR.md (Phases 1–8), plan.md (GMSH), docs/rfcs/0001, visual-audit-report.md

---

✅ What Is Done

Area	Detail
Phase A	Flamenco removed, blender-renderer → render-worker Celery container, threejs-renderer removed, MinIO added
Phase B	Domain-driven project structure, Tenant model + RLS migrations 035/036, Tenant management UI
Phase C	WorkflowDefinition model, standard workflows seeded, React Flow Workflow Editor
Phase D	OCC mesh attributes extraction, Blender integration
Phase E	MediaAsset catalog (model + API + frontend)
Sharp Edges V02	GCPnts curve sampling → 17,129 segment pairs in GLB extras → Blender KD-tree marks sharp+seam
Tessellation presets	Draft/Standard/Fine preset buttons in Admin UI, default deflections updated
Media cache-bust	?v={file_size_bytes} in download URLs + Cache-Control: no-cache headers
GPU activation order	Fix: _activate_gpu() called before AND after open_mainfile to survive engine reset
Material system	Aliases-first lookup, get_material_library_path() via AssetLibrary

---

🗺 Open Work — Prioritized

Priority 1 — Tessellation Quality (Blocking visual quality)

Goal: Eliminate fan triangles and faceting on cylindrical surfaces (rings, bearings). Plan: plan.md (6 tasks, GMSH Frontal-Delaunay as BRepMesh replacement)

Task	File	What
T1	render-worker/Dockerfile	pip install gmsh>=4.15.0
T2	export_step_to_gltf.py	--tessellation_engine occ|gmsh CLI arg
T3	export_step_to_gltf.py	_tessellate_with_gmsh(): BREP → GMSH → Poly_Triangulation write-back
T4	admin.py	tessellation_engine setting in SETTINGS_DEFAULTS + SettingsOut
T5	export_glb.py	Read setting, pass --tessellation_engine to CLI
T6	Admin.tsx	Dropdown: OCC vs. GMSH with description

Risk: GMSH Surface-Tag ↔ OCC Face mapping must be verified experimentally. Status: Not started. /implement to begin.

---

Priority 2 — Dead Code Deletion (Quick wins, no risk)

Goal: Remove code that is provably dead and confuses future readers.

Item	Location	Why Dead
Pillow overlay block	blender_render.py lines 798–851	transparent_bg=True always, else: branch never runs
STL workflow	admin.py, cad.py, multiple tasks	Pipeline is GLB-only; stl_quality, VALID_STL_QUALITIES, stl_size_bytes all orphaned
render_order_line_task in step_tasks	step_tasks.py lines 705–1050	Duplicates rendering/tasks.render_order_line_still_task
blender-renderer/ directory	repo root	Removed from docker-compose.yml already
threejs-renderer/ directory	repo root	Migration 033 removed it from services
flamenco/ directory	repo root	Migration 032 removed Flamenco
renderproblems_tmp/ directory	repo root	Temp debugging screenshots, not code

Estimated effort per agent: 1 session Can run in parallel with Priority 3.

---

Priority 3 — Celery Task Decomposition (Maintainability, parallel-safe)

Goal: Split step_tasks.py (1,170 lines, 8+ pipeline steps) into focused modules.

Target structure:

backend/app/tasks/
├── step_tasks.py          → keep only: process_step_file (thin dispatch)
├── pipeline/
│   ├── extract.py         → extract_cad_metadata (OCC parsing, 0.1s)
│   ├── thumbnail.py       → render_step_thumbnail (Blender call)
│   ├── stills.py          → render_order_line_still_task (Cycles still renders)
│   └── turntable.py       → render_order_line_turntable_task

Also: split render-worker/scripts/blender_render.py (853 lines) into sub-modules:

render-worker/scripts/
├── blender_render.py          → entry point only (~80 lines)
├── _blender_gpu.py            → GPU probe + activation
├── _blender_import.py         → GLB import, rotation, smooth shading
├── _blender_materials.py      → material library application + fallback
├── _blender_camera.py         → auto camera from bbox, clip planes
└── _blender_scene.py          → scene setup (Mode A vs Mode B)

Estimated effort: 2 sessions Depends on: Priority 2 (delete duplicate task first)

---

Priority 4 — Render Job Tracking (Correctness bug)

Goal: Fix the broken render job cancellation (synthetic render-{line_id} ID never matches real Celery task ID → revoke() is a no-op).

What to build:

• RenderJobDocument Pydantic schema stored in order_lines.render_job_doc (JSONB)
• Fields: celery_task_id, state FSM, steps[] with timing, gpu_info
• Migration: alembic revision — add render_job_doc JSONB to order_lines
• Update render tasks to write real self.request.id into the document
• Fix orders.py cancel endpoint to read celery_task_id from the document

Files:

• New: backend/app/domains/rendering/job_document.py
• New migration 06x_render_job_document.py
• Modified: render_order_line.py, render_thumbnail.py, orders.py

Estimated effort: 1 session Depends on: Priority 3 (need clean task structure first)

---

Priority 5 — Structured Logging (Observability)

Goal: Replace inconsistent logger.info(f"...") / emit() / log_task_event() mix with a PipelineLogger that writes to Python logging + Redis SSE + DB.

What to build:

• backend/app/core/pipeline_logger.py — PipelineLogger class
  • step_start(step, context) → [STEP_NAME] starting — context
  • step_done(step, duration_s, result) → [STEP_NAME] done in 0.34s
  • step_error(step, error, exc) → [STEP_NAME] ERROR: ...
• Optional new table: pipeline_events(task_id, step_name, level, message, duration_s, context JSONB)
• Migrate all task files to use PipelineLogger

Estimated effort: 1-2 sessions Can start immediately, but has broad blast radius (touches all task files).

---

Priority 6 — Tenant Isolation Completion (Security/correctness)

Goal: Make RLS actually work. Currently build_tenant_db_dep() yields db without calling set_tenant_context(), so all tenant isolation is silent no-op.

What to build:

• TenantContextMiddleware in backend/app/core/middleware.py
  • Extracts tenant_id from JWT, stores in request.state
  • After DB session acquired: SET LOCAL app.current_tenant_id = '...'
• Celery tasks: add set_tenant_context(db, tenant_id) call at start of each task (Celery bypasses HTTP middleware)
• Role hierarchy migration: admin → global_admin, add tenant_admin

Files:

• New: backend/app/core/middleware.py
• Migration: 06x_role_hierarchy.py
• Modified: backend/app/main.py (register middleware), utils/auth.py, all routers

Estimated effort: 2 sessions Depends on: Stable auth layer (Priority 3 dead code removal first)

---

Priority 7 — UV Unwrap Workflow (New feature, user-requested)

Goal: Produce UV-unwrapped geometry GLBs with clean seams for downstream texture authoring. Depends on: Priority 1 (GMSH tessellation must produce conforming seams first).

What to build:

• New Blender script _blender_uvunwrap.py called from export_gltf.py after sharp edge marking
• UV unwrap via bpy.ops.uv.unwrap(method='ANGLE_BASED', margin=0.001)
• Seams are already set by _apply_sharp_edges_from_occ() (edge.seam=True)
• UV coordinates embedded in the production GLB
• Admin toggle: uv_unwrap_enabled in system_settings

Estimated effort: 1 session Depends on: Priority 1 (GMSH) for clean seams

---

Priority 8 — UI/UX Polish (from visual-audit-report.md)

Top actionable items from the audit:

Item	Where	Fix
Tooltip system	All settings pages	Add title or tooltip component to every input
Empty state messages	MediaBrowser, ProductLibrary	"No assets yet — upload a STEP file"
Notification batching	NotificationCenter	Group per-render noise into job summaries
Mobile navigation	Layout.tsx	Hamburger menu for viewport < 768px
Kanban rejection flow	OrderDetail	Drag-to-reject with reason field

Estimated effort: 2 sessions Independent of all backend priorities.

---

Priority 9 — Phase F: Hash-based Conversion Caching (Performance)

Goal: Skip re-tessellation if STEP file hash hasn't changed. Cache geometry GLB by sha256(step_file).

What to build:

• cad_files.step_hash column (SHA256, nullable)
• Before GLB generation: compute hash, check if cached GLB exists for same hash
• If hit: copy cached GLB, skip OCC+GMSH, skip Blender
• Migration: 06x_step_hash_column.py

Estimated effort: 1 session Depends on: Priority 1 (GMSH) stable first

---

Priority 10 — USD Workflow RFC (Strategic, long-term)

Document: docs/rfcs/0001-step-to-usd-workflow.md Status: Proposed only — not planned for implementation yet.

Summary: Replace dual-GLB pipeline (geometry GLB → production GLB) with a single USD canonical scene. Three.js has no USD loader, so this requires either switching viewers or waiting for Three.js USD support.

Decision needed: Is the viewer constraint acceptable? Deferred until Priority 1–4 are complete.

---

Dependency Graph

Priority 1 (GMSH)
  └── Priority 7 (UV Unwrap)
  └── Priority 9 (Hash Cache)

Priority 2 (Dead Code)
  └── Priority 3 (Task Decomposition)
        └── Priority 4 (Render Job Tracking)
              └── Priority 6 (Tenant Isolation)

Priority 5 (Logging) — independent, can start anytime
Priority 8 (UI/UX)   — independent, can start anytime
Priority 10 (USD)    — deferred

---

What To Do Next

Option A — Fix visual quality first: → /implement on plan.md (Priority 1: GMSH tessellation)

Option B — Clean up dead code first (low risk, fast wins): → Start Priority 2 dead code deletion, then Priority 3 task decomposition

Option C — Parallel sprint (2 agents): → Agent 1: Priority 1 (GMSH) in worktree → Agent 2: Priority 2+3 (dead code + task split) in separate worktree

Option D — UI/UX sprint: → Priority 8 audit items, completely independent of backend

---

Archive

Old planning files are kept for reference but superseded by this document:

• PLAN.md — original Phase A–F plan (Phases A–E complete, Phase F = Priority 9 here)
• PLAN_REFACTOR.md — 1,173-line architectural plan (Phases 1–8 mapped to Priorities 2–8 above)
• plan.md — active GMSH implementation plan (Priority 1)
• docs/rfcs/0001-step-to-usd-workflow.md — USD RFC (Priority 10)
• review-report.md — latest code review results
• visual-audit-report.md — UX audit results