HartOMat/plan.md

Plan: P12 — Codebase Hygiene Sprint (CLAUDE.md + Type Safety + Stale References)

Date: 2026-03-13 | Branch: refactor/v2

Context

All 10 roadmap priorities are complete. A codebase scan reveals three categories of debt:

1. CLAUDE.md is dangerously stale: References 11 services (4 deleted), worker-thumbnail (now render-worker), blender-renderer/threejs-renderer/flamenco (all removed), wrong roles (admin instead of global_admin/tenant_admin), deleted STL endpoints, and wrong task locations. Since CLAUDE.md is the AI instruction file, every future conversation gets wrong context.

2. Frontend type safety: 4 unnecessary (rp as any).cancelled casts in OrderDetail.tsx (the type already has cancelled), plus 4 (item as any).cad_parsed_objects/cad_part_materials casts (need 2 fields added to OrderItem interface).

3. Stale service references: worker-thumbnail in the /scale endpoint's ALLOWED_SERVICES, hardcoded http://localhost:8080 Flamenco link in OrderDetail.tsx, and obsolete PLAN.md + PLAN_REFACTOR.md files in the repo root.

Parallelization: All 4 tracks are independent and can run in parallel.

Affected Files

File	Change
CLAUDE.md	Full rewrite — update services, queues, roles, endpoints, structure
frontend/src/pages/OrderDetail.tsx	Remove (rp as any) casts (4 sites), remove (item as any) casts (4 sites), remove Flamenco hardcoded link
frontend/src/api/orders.ts	Add cad_parsed_objects and cad_part_materials to OrderItem interface
backend/app/api/routers/worker.py	Remove worker-thumbnail from ALLOWED_SERVICES
PLAN.md	Delete (superseded by ROADMAP.md)
PLAN_REFACTOR.md	Delete (superseded by ROADMAP.md)

Tasks (in order)

Track A — CLAUDE.md Rewrite

[x] Task 1: Update CLAUDE.md to match current architecture — DONE

• File: CLAUDE.md
• What: Full rewrite of the project instructions file:
  • Ziel: Remove "Flamenco" reference
  • Tech Stack: Remove Flamenco, Three.js (Playwright), cadquery (STEP→STL). Add: MinIO (S3-compatible storage), OCC (cadquery/OCP for STEP parsing), GMSH (tessellation), usd-core (USD export)
  • Services table: 8 services (postgres, redis, minio, backend, worker, render-worker, beat, frontend). Remove blender-renderer, threejs-renderer, worker-thumbnail, flamenco-manager, flamenco-worker
  • Logs section: docker compose logs -f render-worker (not worker-thumbnail or blender-renderer). Rebuild: docker compose up -d --build backend worker render-worker beat
  • Credentials: Remove Flamenco Manager line
  • Project structure: Remove blender-renderer/, threejs-renderer/, flamenco/. Add render-worker/scripts/. Update tasks/ description to mention it's a compatibility shim, active tasks in domains/pipeline/tasks/. Add domains/ directory
  • Celery queues: asset_pipeline queue on render-worker (not worker-thumbnail). Remove "blender-renderer only 1 request" note — now it's "render-worker concurrency=1 because Blender is single-threaded". Add thumbnail_rendering if it's different from asset_pipeline — CHECK: docker-compose says asset_pipeline
  • Roles: Add global_admin, tenant_admin. Update table to 4 roles
  • API endpoints: Remove generate-stl/{quality}, generate-missing-stls. Add generate-usd-master, generate-gltf-geometry, scene-manifest
  • Bekannte Eigenheiten: Remove Flamenco GPU note
  • Pipeline section: Update to mention OCC/GMSH tessellation, USD export
• Acceptance gate: grep -c "blender-renderer\|threejs-renderer\|flamenco\|worker-thumbnail\|11 Services" CLAUDE.md returns 0
• Dependencies: none
• Risk: None. Documentation only.

Track B — Frontend Type Safety

[x] Task 2: Fix as any casts in OrderDetail.tsx and OrderItem type — DONE

• Files: frontend/src/api/orders.ts, frontend/src/pages/OrderDetail.tsx
• What:
  1. Add to OrderItem interface in orders.ts:

     cad_parsed_objects: string[] | null
     cad_part_materials: Array<{ part_name: string; material_name: string; [key: string]: unknown }>
     

  2. Remove (rp as any).cancelled → just rp.cancelled (4 sites in OrderDetail.tsx — the type already has cancelled: number)
  3. Remove (item as any).cad_parsed_objects → item.cad_parsed_objects (2 sites)
  4. Remove (item as any).cad_part_materials → item.cad_part_materials (1 site)
  5. For (item as any)[c.key] dynamic access: replace with (item as Record<string, unknown>)[c.key] (narrower cast)
• Acceptance gate: grep -c "as any" frontend/src/pages/OrderDetail.tsx decreases by at least 8. Run docker compose exec frontend npx tsc --noEmit — no new errors
• Dependencies: none
• Risk: Low. Type-only changes, no behavioral change. Must run tsc check.

Track C — Stale Backend Reference

[x] Task 3: Remove worker-thumbnail from scale endpoint — DONE

• File: backend/app/api/routers/worker.py
• What:
  1. Remove "worker-thumbnail" from ALLOWED_SERVICES set (line 424)
  2. Update the ScaleRequest docstring/comment (line 367) to list only "render-worker" | "worker"
  3. Update the endpoint docstring (line 414) to remove worker-thumbnail
• Acceptance gate: grep "worker-thumbnail" backend/app/api/routers/worker.py returns 0 matches
• Dependencies: none
• Risk: None. worker-thumbnail service doesn't exist in docker-compose.

Track D — Delete Obsolete Files + Flamenco Link

[x] Task 4: Delete PLAN.md, PLAN_REFACTOR.md, and remove Flamenco hardcoded link — DONE

• Files: PLAN.md, PLAN_REFACTOR.md, frontend/src/pages/OrderDetail.tsx
• What:
  1. Delete PLAN.md (superseded by ROADMAP.md — noted in the Archive section)
  2. Delete PLAN_REFACTOR.md (superseded by ROADMAP.md)
  3. In OrderDetail.tsx (~line 942–950): Remove the localhost:8080 Flamenco link block. Replace with just the job ID text (since render_backend_used === 'flamenco' only applies to historical data, show the ID as plain text instead of a broken link)
• Acceptance gate: ls PLAN.md PLAN_REFACTOR.md 2>&1 | grep "No such file" succeeds. grep "localhost:8080" frontend/src/pages/OrderDetail.tsx returns 0 matches
• Dependencies: none
• Risk: Low. PLAN files are archived references. Flamenco link is non-functional (service removed).

Migration Check

No. No database changes.

Order Recommendation

Fully parallel — all 4 tracks independent:

• Agent 1: Task 1 (CLAUDE.md rewrite) — largest, highest impact
• Agent 2: Task 2 (frontend type safety)
• Agent 3: Task 3 (worker.py cleanup)
• Agent 4: Task 4 (file deletion + Flamenco link)

Risks / Open Questions

1. CLAUDE.md as AI instructions: This file is loaded into every AI conversation as project context. Getting it wrong means every future session starts with bad information. The rewrite must be verified against the actual docker-compose.yml and codebase.

2. OrderItem cad_part_materials type: Backend returns list[dict] — need to check what keys the dicts actually contain. The frontend uses part_name and material_name based on grep of CadPartMaterials component.

3. require_admin_or_pm rename: 71 occurrences across 13 files could be renamed to require_pm_or_above for consistency. Deferred — it's high churn, low impact (the alias works correctly), and can be a separate micro-task later.