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`:
     ```typescript
     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.