Canonical map of the PhotoTux engineering handbook: all numbered specifications 00–32, appendices, dependency relationships, and reading orders. Every file listed here exists and is linked. Normative keywords follow Requirement Keywords. Terms follow the Glossary.
PhotoTux is a Linux-native, local-first professional raster editor. Commands mutate; the document owns truth; history stores transactions; rendering reads immutable snapshots. Cloud, accounts, AI/generative features, and proprietary vendor workflows are out of scope (00 — Introduction).
- docs/README.md — purpose, reading order, conventions, directory map
All status values are Present.
- File: 00-Introduction.md
- Role: Product boundary, principles, personas, quality targets, container/context views, ownership, trust, failure philosophy, foundation invariants.
- Depends on: — (charter root)
- Primary consumers: all documents
- File: 01-Information-Architecture.md
- Role: Mental model, hierarchy, actions, selection/focus/context/active target, menus, progressive disclosure and the inspector disclosure/badge registry, a11y semantics at IA level.
- Depends on: 00
- File: 02-Application-Lifecycle.md
- Role: Startup, session, windows/documents lifetime, save coordination, recovery, device/surface loss, shutdown.
- Depends on: 00, 01
- File: 03-Workspace-System.md
- Role: Workspaces, views, presets, multi-view documents, restore reconciliation.
- Depends on: 01, 02
- File: 04-Docking-System.md
- Role: Split/stack layout topology, docking geometry, display changes.
- Depends on: 03
- File: 05-Panel-System.md
- Role: Panel descriptors, follow/pin targets, virtualization, contributions, panel-local view actions.
- Depends on: 01, 03, 04, 08
- File: 06-Toolbar-System.md
- Role: Tool presentation, placement, toolbar customization.
- Depends on: 01, 03, 08
- File: 07-Context-Menus.md
- Role: Context targets, completeness vs menus/actions, selection preservation.
- Depends on: 01, 08
- File: 08-Command-System.md
- Role: Mutation spine, validation, scheduling, transactions, jobs, cancellation, typed results.
- Depends on: 00, 10, 20
- File: 09-Shortcut-System.md
- Role: Bindings, conflicts, IME yield, customization, a11y alternatives.
- Depends on: 01, 08
- File: 10-Document-Model.md
- Role: Authoritative graph, identity, versions, snapshots/deltas, dirty/save identity.
- Depends on: 00, 08
- File: 11-Layer-System.md
- Role: Layer tree, kinds, blend/opacity, groups, compositing inputs.
- Depends on: 10, 08, 16
- File: 12-Selection-System.md
- Role: Object and pixel selection, operations, persistence.
- Depends on: 01, 10, 08
- File: 13-Mask-System.md
- Role: Mask attachment, edit surfaces, apply/disable semantics.
- Depends on: 10, 11, 12, 08
- File: 14-Brush-Engine.md
- Role: Input sampling, dabs, dynamics, stroke transactions, latency path.
- Depends on: 08, 10, 12, 13, 17, 30
- File: 15-Filter-Engine.md
- Role: Filter descriptors, CPU/wgpu paths, previews, destructive vs adjustment.
- Depends on: 08, 10, 16, 17, 30
- File: 16-Color-Management.md
- Role: Profiles, assign vs convert, proofing, precision, Linux color integration.
- Depends on: 10, 08, 17
- File: 17-Rendering-Engine.md
- Role: Render graph, tiles, dirty regions, frame scheduling, GPU/CPU, device loss.
- Depends on: 10, 11, 13, 16, 30
- File: 18-Text-Engine.md
- Role: Text objects, shaping, rasterize boundaries, editability.
- Depends on: 10, 11, 08, 16
- File: 19-Shape-Engine.md
- Role: Vector-like shapes, paths, rasterize boundaries.
- Depends on: 10, 11, 08, 16
- File: 20-History-Undo.md
- Role: Transactions, coalescing, checkpoints, budgets, undo/redo.
- Depends on: 08, 10
- File: 21-Clipboard.md
- Role: Internal/external transfer, MIME validation, paste commands.
- Depends on: 08, 10, 22
- File: 22-Import-Export.md
- Role: Codecs, untrusted input, progress/cancel, loss disclosure.
- Depends on: 08, 10, 16, 27
- File: 23-Plugin-SDK.md
- Role: Manifests, capabilities, contributions, isolation, unavailable extensions.
- Depends on: 08, 01, 22, 29, 30
- File: 24-Preferences.md
- Role: Preference schemas, migration, scopes.
- Depends on: 00, 02, 29
- File: 25-Themes.md
- Role: Tokens, contrast, scaling, motion preferences.
- Depends on: 01, 29
- File: 26-Dialogs.md
- Role: Modal/task dialogs, focus return, portals.
- Depends on: 01, 02, 29
- File: 27-File-Formats.md
- Role: Native container, chunks, integrity, migration, recovery bridge.
- Depends on: 10, 22, 20
- File: 28-UX-Guidelines.md
- Role: Interaction quality, disclosure, naming, feedback patterns.
- Depends on: 01, 29
- File: 29-Accessibility.md
- Role: Semantic tree, focus, keyboard, canvas a11y, AT-SPI, announcements.
- Depends on: 01, 08, 09, 25
- File: 30-Performance.md
- Role: Budgets, tiers, tracing, backpressure, regression gates.
- Depends on: 08, 14, 17, 22
- File: 31-Testing.md
- Role: Pyramid, fixtures, fuzz, GPU tolerances, a11y/perf gates, evidence.
- Depends on: all preceding contracts as applicable
- File: 32-Developer-Guide.md
- Role: Engineering workflow, handbook use, contribution practices.
- Depends on: 00, appendices, relevant subsystem docs
All status values are Present.
| Appendix | File | Role |
|---|---|---|
| Glossary | Glossary.md | Vendor-neutral vocabulary |
| Requirement Keywords | Requirement-Keywords.md | MUST/SHOULD/MAY interpretation |
| Cross-Reference Index | Cross-Reference-Index.md | This map |
| Subsystem Dependency Matrix | Subsystem-Dependency-Matrix.md | Allowed dependency edges |
| Command Taxonomy | Command-Taxonomy.md | Command scopes and families |
| Event Catalog | Event-Catalog.md | Semantic event families |
| Document Format Versioning | Document-Format-Versioning.md | Schema/feature/migration rules |
| Error Taxonomy | Error-Taxonomy.md | Typed failure categories |
| Thread Ownership Map | Thread-Ownership-Map.md | Role threads and ownership |
| Performance Budget Ledger | Performance-Budget-Ledger.md | Budget index and owners |
| Accessibility Checklist | Accessibility-Checklist.md | Conformance checklist |
| Interactive Stability Checklist | Interactive-Stability-Checklist.md | Living GUI / edge-case QA suite |
| Decision Register | Decision-Register.md | Architectural decisions |
| Codebase–Handbook Gap Analysis | Codebase-Handbook-Gap-Analysis.md | Live crates vs handbook |
| Alignment Roadmap | Alignment-Roadmap.md | Alignment complete (contracts) |
| Handbook Parity Roadmap | Handbook-Parity-Roadmap.md | Product phases to full handbook parity |
| Handbook Parity Checklist | Handbook-Parity-Checklist.md | Living product slice tracker |
| Implementation Checklist | Implementation-Checklist.md | Alignment history |
| Archived ADR → DR Map | Archived-ADR-to-DR-Map.md | Archived ADRs evidence only |
flowchart TB
Intro[00_Introduction] --> IA[01_InformationArchitecture]
Intro --> Commands[08_CommandSystem]
Intro --> Document[10_DocumentModel]
IA --> Life[02_ApplicationLifecycle]
Life --> Workspace[03_WorkspaceSystem]
Workspace --> Dock[04_DockingSystem]
Workspace --> Panels[05_PanelSystem]
IA --> Toolbars[06_ToolbarSystem]
IA --> ContextMenus[07_ContextMenus]
IA --> Shortcuts[09_ShortcutSystem]
Commands --> Document
Document --> Layers[11_LayerSystem]
Document --> Selection[12_SelectionSystem]
Document --> Masks[13_MaskSystem]
Document --> History[20_HistoryUndo]
Commands --> History
Commands --> Brush[14_BrushEngine]
Commands --> Filters[15_FilterEngine]
Document --> Color[16_ColorManagement]
Document --> Render[17_RenderingEngine]
Layers --> Render
Color --> Render
Document --> Text[18_TextEngine]
Document --> Shapes[19_ShapeEngine]
Commands --> Clipboard[21_Clipboard]
Commands --> ImportExport[22_ImportExport]
ImportExport --> Formats[27_FileFormats]
Document --> Formats
Commands --> Plugins[23_PluginSDK]
IA --> Prefs[24_Preferences]
IA --> Themes[25_Themes]
Life --> Dialogs[26_Dialogs]
IA --> UX[28_UXGuidelines]
IA --> A11y[29_Accessibility]
Render --> Perf[30_Performance]
Brush --> Perf
ImportExport --> Perf
Commands --> Testing[31_Testing]
Render --> Testing
A11y --> Testing
Intro --> DevGuide[32_DeveloperGuide]
Detailed edge rules: Subsystem Dependency Matrix.
- docs/README.md
- 00 — Introduction
- Requirement Keywords + Glossary
- 01 — Information Architecture
- 08 — Command System + Command Taxonomy
- 10 — Document Model
- 20 — History Undo
- 17 — Rendering Engine
- Decision Register
- Role-specific path below
00 → 10 → 11 → 12 → 13 → 08 → 20 → 27 → Document Format Versioning → Error Taxonomy → 31
00 → 10 → 11 → 13 → 16 → 17 → 30 → Performance Budget Ledger → Thread Ownership Map → 31
00 → 01 → 02 → 03 → 04 → 05 → 06 → 07 → 09 → 24 → 25 → 26 → 28 → 29 → Accessibility Checklist
00 → 01 → 08 → 10 → 12 → 13 → 14 → 17 → 30 → Event Catalog
00 → 10 → 16 → 22 → 27 → 21 → Document Format Versioning → Error Taxonomy → 31
00 → 01 → 08 → 23 → 15 → 22 → 05 → 29 → Command Taxonomy → Decision Register (DR-009)
00 → 01 → 08 → 09 → 29 → 25 → 07 → 26 → Accessibility Checklist → Event Catalog
- Existing documents MUST use relative Markdown links with exact filenames.
- Every numbered document SHOULD link to 00, direct predecessors, Glossary, Requirement Keywords, and this index where relevant.
- Renames MUST update this index, docs/README.md, and repository references atomically.
- Dependency changes MUST update Subsystem Dependency Matrix in the same change.
- High-cost decisions MUST appear in Decision Register.
- Cross references SHOULD state why the target matters, not only list neighbors.
- Competing industry terms SHOULD defer to the Glossary.
docs/
├── README.md
├── 00-Introduction.md … 32-Developer-Guide.md
└── Appendix/
├── Glossary.md
├── Requirement-Keywords.md
├── Cross-Reference-Index.md
├── Subsystem-Dependency-Matrix.md
├── Command-Taxonomy.md
├── Event-Catalog.md
├── Document-Format-Versioning.md
├── Error-Taxonomy.md
├── Thread-Ownership-Map.md
├── Performance-Budget-Ledger.md
├── Accessibility-Checklist.md
├── Interactive-Stability-Checklist.md
├── Decision-Register.md
├── Codebase-Handbook-Gap-Analysis.md
├── Alignment-Roadmap.md
└── Implementation-Checklist.md