Repository Public
1<!--2ORIX Docs3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture overview89ORIX Docs is a thin SwiftUI + AppKit application on top of `Packages/ORIXDocsKit`, a Swift package whose targets do not import SwiftUI.10Every engine can be built, tested and benchmarked from the command line without launching the app.1112## Targets1314| Target | Depends on | Responsibility |15|---|---|---|16| `DocModel` | Foundation | The document model (value types, `Codable`, `Sendable`), styles and inheritance, numbering and cross-reference resolution, editing operations, track changes. |17| `DocContainer` | DocModel | Defensive ZIP reader/writer, shared import/export types (`DocFormat`, `FormatWarning`, `ImportResult`, `ExportResult`). |18| `DocDOCX` | DocModel, DocContainer | WordprocessingML import and export. |19| `DocFormats` | DocModel, DocContainer | Native `.orixdoc` container, Markdown, HTML, RTF, plain text, PDF text import. |20| `DocMath` | DocModel, SwiftMath | LaTeX math parsing and typesetting to Core Graphics. |21| `DocReferences` | DocModel | BibTeX / BibLaTeX, RIS and CSL-JSON parsing; citation and bibliography formatting. |22| `DocLayout` | DocModel, DocMath | Core Text line layout, pagination, page rendering, PDF publishing. |23| `DocReview` | DocModel | Document comparison (diff) and comparison reports. |24| `DocAudit` | DocModel | Document quality auditor and research checks. |25| `DocTemplates` | DocModel | The template library. |26| `DocAutomation` | all of the above | Workflows, batch processing, the `orixdocs` command-line tool. |2728## The document model in one page2930* A `DocumentModel` is a value. Undo is a stack of values; arrays are copy-on-write, so a snapshot shares storage with its successor.31* `body` is a flat `[Block]`. A block is a paragraph, a table, a page/column break, a section break, a generated list (contents, figures, tables) or the generated bibliography.32* Sections are Word-like: `DocumentModel.pageSetup` describes the first section, and each `.sectionBreak` block carries the `PageSetup` of the section it starts. Headers and footers live in `PageSetup`.33* A `Paragraph` is a list of `Run`s. A run is text with optional (inheritable) `CharProps`, an optional character style, an optional tracked `Revision`, an optional `FormatRevision` and the ids of the comments anchored on it.34* Inline objects (image, shape, equation, note reference, citation, cross-reference, field, bookmark) are runs whose text is U+FFFC and whose `inline` holds the payload. A forced line break is U+2028 in the text; a tab is `\t`.35* **Every text offset is a UTF-16 code unit offset**, always aligned on a composed character boundary (`String.composedBoundary…`). Never index paragraph text with Swift `Character` counts or scalar counts.36* Formatting is resolved as: document defaults → paragraph style chain (`basedOn`) → character style chain → direct properties. `StyleSheet.paraProps` / `charProps` return fully resolved values. Built-in style ids equal Word's (`Normal`, `Heading1`, `Title`, `Caption`, `FootnoteText` …), see `StyleID`.37* Lists: `Paragraph.list` references a `ListDefinition` in `DocumentModel.lists` plus a level. Labels are computed, never stored in the text.38* Captions are ordinary paragraphs of style `Caption` that contain a `.field(.sequence("Figure"))` inline. Display equations are paragraphs holding one `.equation` inline with `display == true`.39* Footnotes and endnotes: a `.note(NoteRef)` inline in the text, content in `DocumentModel.notes[id]`.40* Citations: a `.citation(Citation)` inline referencing `BibEntry.key`s of `DocumentModel.bibliography`. Their displayed text and the bibliography are produced by a `CitationFormatting` implementation (DocReferences), never stored.41* `Numbering(document)` computes list labels, heading numbers, sequence values, note numbers, citation order, the outline and cross-reference targets in one pass. Anything that shows a number reads it there.42* Tables: `Table.columnWidths` is the grid; a `TableCell` covers `colSpan` grid columns; vertical merges use `vMerge` (`restart` / `continue`) exactly like WordprocessingML. Cells hold paragraphs only (no nested tables).43* Images are stored once in `DocumentModel.assets` (not part of the JSON encoding) and referenced by id from `ImageObject`.44* Tracked changes: an inserted run carries `Revision(kind: .insertion)`; deleted text stays in the paragraph with `Revision(kind: .deletion)`; `Paragraph.markRevision` tracks the paragraph mark. `Paragraph.visibleText` is the text with all changes accepted.4546## Conventions4748* Swift 6 language mode, strict concurrency. Model types are `Sendable` values.49* No network access anywhere in the package. No third-party dependency except SwiftMath (math typesetting).50* Importers treat input as hostile and report everything they cannot carry over as `FormatWarning`s; they never drop content silently.51* Every source file starts with the ORIX file header (project, file path, description, author, contact).52* Tests use Swift Testing (`import Testing`).53