Flux Onboarding Handbook
For new engineers joining Flux development. This is the index. Every chapter stands on its own; the recommended path is below.
Philosophy. First six months: read, navigate, understand, ask. Productive code commits come after mental scaffolding is in place. These chapters teach the scaffolding.
Language. All chapters in English. Quoting code, paths, and FTex notes verbatim.
At a glance
| Ch | Title | What you get | Length |
|---|---|---|---|
00 |
link:ac:Flux Onboarding 00 - Welcome and Repo Map[Welcome & Repo Map] |
What Flux is, repo layout, modules, flavors, build caveats, code conventions |
~270 lines |
01 |
link:ac:Flux Onboarding 01 - Architecture and System Context[Architecture & System Context] |
Five layers, M/V/Glob, Sheaf, Hub, Lux, persistence, threading, undo, errors |
~290 lines |
02 |
link:ac:Flux Onboarding 02 - Subsystem Bend (Press Brake)[Subsystem: Bend (Press Brake)] |
Canonical subsystem walk-through. Template for future per-subsystem chapters. |
~330 lines |
02.1 |
link:ac:Flux Onboarding 02.1 - Subsystem BCell (Bend Cell Automation)[Subsystem: BCell (Bend Cell Automation)] |
Robot-cell automation layered on top of Bend. Pickup / regrip / deposit, grippers, routing. |
~290 lines |
03 |
link:ac:Flux Onboarding 03 - API Maps[API Maps] |
Central interfaces, abstract classes, callers/callees, stability legend |
~270 lines |
04 |
link:ac:Flux Onboarding 04 - Data Model Catalog[Data Model Catalog] |
Five layers of data (Geo → Drawing → 3D → Tech → Part), persistence, migration |
~250 lines |
05 |
link:ac:Flux Onboarding 05 - Design Patterns[Design Patterns — A Reader’s Guide] |
Patterns Flux actually uses, with file references and pitfalls |
~210 lines |
06 |
link:ac:Flux Onboarding 06 - Tests and Golden Paths[Tests & Golden Paths] |
Flit framework, golden-file pattern, debug tips for read-only debugging |
~180 lines |
07 |
link:ac:Flux Onboarding 07 - Guided Code Tours[Guided Code Tours] |
Eight 10—20 min walks, each with named stops and a self-check |
~190 lines |
08 |
link:ac:Flux Onboarding 08 - CAM Glossary[CAM Glossary with Code Mapping] |
Alphabetized lookup of every term you’ll meet |
~270 lines |
09 |
link:ac:Flux Onboarding 09 - Find and Explain Exercises[Find & Explain Exercises] |
12 read-only exercises with rubrics and a 6-month calendar |
~210 lines |
Total: ~2500 lines (≈ 60 printed pages).
Recommended reading paths
Path A — "I’m starting Monday" (5 days, ~10 hours)
| Day | Read |
|---|---|
1 |
Chapter 00 in full + skim 08 (glossary). |
2 |
Chapter 01 in full + tour A and tour D from chapter 07. |
3 |
Chapter 02 in full (Bend). |
4 |
Chapter 06 (tests) + tour C (rendering) + tour E (persistence). |
5 |
Chapter 09 — exercise 1 and exercise 2. |
By Friday you have a vocabulary, a mental model, an understanding of one subsystem, and a sense of how tests work. That’s the right foundation.
Path B — "Tell me where to find X" (lookup mode)
You’re triaging a question or a stack trace and need a fast lookup.
| Need | Go to |
|---|---|
What does this term mean? |
Chapter 08 (Glossary) |
Where is this class defined? |
Chapter 08 cross-find table |
What is the public surface of subsystem X? |
Chapter 03 (API Maps) |
How does data flow through the system? |
Chapter 04 (Data Model) |
What pattern is this code? |
Chapter 05 (Patterns) |
How do tests work? |
Chapter 06 |
Walk me through this flow |
Chapter 07 (the relevant tour) |
Path C — "Six-month curriculum"
Use the calendar in chapter 09 §"A learning calendar". One exercise per week, paced to internalize the content.
| Month | Focus |
|---|---|
1 |
Navigate. Vocabulary. Mental model. |
2 |
Data flow. Control flow. |
3 |
Real bugs. Dual systems. |
4 |
Tests. Persistence. |
5 |
UI flows. Full traces. |
6 |
Synthesis. Teach a 30-minute tech talk. |
What this handbook is not
-
Not a replacement for
Notes\Dev\…andNotes\Tech\…. Those are the source of truth for low-level facts. This handbook orients you so you can read those notes effectively. -
Not a build guide. Build is in
Notes\Dev\1002.BuildingFlux.ftx(with the caveats in chapter 00 §8). On day 1, ask your buddy. -
Not a feature spec. Specs live in design tickets and PR descriptions.
-
Not API reference docs. Doxygen-style reference does not exist for Flux. Read code; chapter 03 gives orientation.
Conventions used in these chapters
-
File paths are absolute against the repo root (
X:\…) or relative underSrc\/Notes\/Doc\/Test\. -
Code excerpts are quoted verbatim from the current tree. If you spot drift, file an issue.
-
Cross-references link by chapter (e.g. "see chapter 02 §7.5"). When section numbers move, update them.
-
Stability badges in chapter 03: 🟢 stable, 🟡 internal, 🔴 in-flight.
-
Single-line callouts (
> ⚠️ ...) flag pitfalls and intentional rough edges.
How to keep this handbook honest
These docs degrade fastest at three specific seams. Watch them:
-
The §8 of chapter 00 ("1002 says vs. today"). Refresh whenever the build toolchain changes.
-
Stability ratings in chapter 03. Move ratings between green/yellow/red as code matures or refactors.
-
Real-bug exercises in chapter 09 (especially exercise 5). Replace with newer fixes once a year.
A small ritual: each new joiner files one issue or PR against this handbook reflecting one inaccuracy or one lesson learned. That’s how documentation stays alive.
Companion resources inside the repo
-
Notes\Dev\— developer notes (FTex). Most important: 1001, 1002, 1003, 1005, 1009, 1011, 1013. -
Notes\Tech\— technical notes (FTex). Most useful: 2007 (Curl), 2013 (Flavors), 2015 (Message IDs). -
Doc\Img\— domain-specific image galleries. OpenDoc\Img\Bend\,Doc\Img\BCell\,Doc\Img\Fold\,Doc\Img\Laser\to recognize machine vocabulary visually. -
Help\— end-user manual (FTex). Sometimes the clearest definition of a feature lives here.
Where to ask
-
Onboarding buddy. Your first day, ask for one. Use them.
-
Issues / PR comments. Public, searchable, durable.
-
Chat (Slack / Teams). Fast but volatile — for high-value answers, repost to the issue tracker.
Contributing to this handbook
The chapters are markdown — edit them like any other source file.
-
Keep prose tight; one idea per paragraph.
-
Don’t repeat content that already lives in
Notes\orHelp\— link to it. -
Verify every code path you cite — paths and line numbers drift fast.
-
File-scoped ownership: chapter 00 has the broadest reach, so changes there get extra review. Per-subsystem chapters belong to the subsystem owner.
-
All chapters are in English, regardless of contributor language. The codebase is global.
Maintenance ledger
| Chapter | Last full audit | Notes |
|---|---|---|
00 Welcome |
2026-05-04 |
Postprocessor section corrected (no longer Hex). |
01 Architecture |
2026-05-04 |
Diagram and HX entry corrected. |
02 Bend |
2026-05-04 |
NC generation section corrected. |
02.1 BCell |
2026-05-04 |
Output-stage NC reference corrected. |
03 API Maps |
2026-05-04 |
§10.2 (post-processor) and §11.3 (HXReader = HoopsReader) corrected. |
04 Data Model |
2026-05-04 |
§9.4 IO table corrected. |
05 Design Patterns |
2026-05-04 |
|
06 Tests |
2026-05-04 |
|
07 Tours |
2026-05-04 |
|
08 Glossary |
2026-05-04 |
Hex / PDL / NC code entries corrected; Post writer entry added. |
09 Exercises |
2026-05-04 |
Next audit target: when major refactors land in Src\Core\Bend\Ops\, or when the dual crash engines converge.
Welcome aboard. Read carefully. Ask early.