Overview

CTLShopFloor Documentation

Documentation set for the CTLShopFloor refurbishment-floor management system.

These docs are descriptive of the system as-is, not prescriptive of how it should be. Refactor recommendations live in their own document so they don’t pollute the architecture reference.

---

Reading order by audience

If you are new to the codebase

1. 01-system-overview.md — What this system is and what business problem it solves. ~5 min.
2. 03-glossary.md — Domain vocabulary. Skim once, refer back constantly. ~10 min.
3. 02-unit-flow.md — How a unit moves through the system. The single most important document. ~25 min.
4. 10-architecture.md — How the code is wired up at runtime. ~15 min.
5. From here, dip into other docs as needed.

If you are planning a refactor

1. 01-system-overview.md — Context.
2. 02-unit-flow.md — End-to-end behavior.
3. 13-workflow-engine.md — The dispatcher and route engine — the most refactor-sensitive piece.
4. 11-data-model.md — Entity clusters and the data-quality issues.
5. 20-refactor-findings.md — The running list of smells, severity-tagged, with suggested first-round targets.

If you are a business / operations stakeholder

1. 01-system-overview.md — What the system does, who uses it.
2. 02-unit-flow.md — Read sections §3 (happy path) and §7 (side branches). Skim the rest.
3. 03-glossary.md — Reference when terminology gets in the way.
4. 12-station-catalog.md §3 — Quick reference for what each station does.

If you are debugging a unit that’s “stuck”

1. 03-glossary.md §SKU variants and §Lifecycle phases — make sure you’re reading the right field.
2. 12-station-catalog.md §5 — table of which station writes which WorkTracking field.
3. 13-workflow-engine.md §10–11 — worked example and known edge cases.

---

Full document index

#	Title	Purpose
01	System Overview	One-page elevator pitch. Audience, business problem, lifecycle, tech stack, external systems.
02	Unit Flow	End-to-end narrative of how a unit moves through the system. Covers happy path, Triage decision tree, RMA flow, Repair Center with purchased + harvested parts.
03	Glossary	Domain vocabulary. Lifecycle phases, workflow entities, SKU variants, BOM, stations, pallets, RMA, parts, imaging/DPK, Triage, grading, integrations, acronyms.
10	Architecture	Project layout, repositories + unit-of-work, ServiceManager facade, three DbContexts, multi-tenant model, middleware pipeline, auth, DI registrations, cross-cutting concerns.
11	Data Model	13 entity clusters with focused Mermaid ERDs. Cross-cluster bridges. Data-quality findings (string-FKs, missing indexes, duplicates).
12	Station Catalog	Reference table of every station type: phase, owning service, inputs, writes, next station.
13	Workflow Engine	The route/scan dispatcher mechanics. How Route/RouteFlow/ProductionFlow/Station compose. Branch routing. Edge cases. Worked example.
14	Jobs & Integrations	Hangfire job inventory, external system integrations (Fishbowl, Mercado Libre, HP PCB, BitRaser, Channel Advisor, Partner ExternalAPI, Windows Test System), email pipelines, audit, blob storage.
20	Refactor Findings	Severity-tagged running list of every smell discovered during the documentation pass. Suggested first-round refactor targets. Open questions for operators.

---

Conventions used in this doc set

• ⚠️ Assumption — inferred from code without operational confirmation. Treat as load-bearing only after verifying.
• 🔧 Refactor finding — flagged for inclusion in 20-refactor-findings.md.
• Severity tags in refactor findings: 🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low.
• file_path:line_number citations reference the corresponding file/line in the repo (not always provided — primarily in the deeper docs).
• Mermaid diagrams are used for flows and ERDs. They render natively in GitHub and most Markdown viewers.

---

What this doc set does NOT contain (yet)

These were deliberately out of scope for the breadth-first pass and may be added in follow-up rounds:

• Per-controller / per-service deep dives. The catalog touches every station; deep behavior is documented only for Triage, RMA, and Repair Center (the user’s priorities). Others come in round 2.
• Full ~225-entity ERD. 11-data-model.md shows clustered ERDs only.
• Sequence diagrams for every flow. Only happy path and the major branches (Triage, RMA, Repair Center) are diagrammed.
• Code-quality metrics (cyclomatic complexity, churn analysis, test coverage). The refactor findings doc captures qualitative observations; quantitative tooling can be added later.
• Operator runbooks. “What to do when X breaks” documentation is a separate effort.
• Database schema migration history. EF migrations are the source of truth.

---

How to update this doc set

When the codebase changes, the docs need to follow. A few practical notes:

• 02-unit-flow.md has the highest update sensitivity — any change to Triage logic, branch routing, or the Repair Center workflow needs a corresponding edit.
• 20-refactor-findings.md is the only doc that should grow over time. Add new findings as they’re discovered; mark resolved ones rather than deleting (history is useful).
• 03-glossary.md should be updated whenever new domain terms appear in code or whenever existing ones get clarified by operators.
• 12-station-catalog.md should be updated when a new StationType is added or an existing one is reworked.
• 11-data-model.md should be updated when entity relationships change significantly (new clusters, new bridge entities). It’s OK to let small additions accumulate.

---

Provenance

Initial doc set produced in May 2026 from a breadth-first code reading of branch Development baseline. The user’s directive was: cover every major subsystem at moderate depth, flag uncertainties inline, and emphasize Triage / RMA / Repair Center as the priority deep-dives. Subsequent revisions and corrections by the team should be tracked in git history.