Architecture overview
ORIX Docs is a thin SwiftUI + AppKit application on top of Packages/ORIXDocsKit, a Swift package whose targets do not import SwiftUI.
Every engine can be built, tested and benchmarked from the command line without launching the app.
Targets
| Target | Depends on | Responsibility |
|---|---|---|
DocModel |
Foundation | The document model (value types, Codable, Sendable), styles and inheritance, numbering and cross-reference resolution, editing operations, track changes. |
DocContainer |
DocModel | Defensive ZIP reader/writer, shared import/export types (DocFormat, FormatWarning, ImportResult, ExportResult). |
DocDOCX |
DocModel, DocContainer | WordprocessingML import and export. |
DocFormats |
DocModel, DocContainer | Native .orixdoc container, Markdown, HTML, RTF, plain text, PDF text import. |
DocMath |
DocModel, SwiftMath | LaTeX math parsing and typesetting to Core Graphics. |
DocReferences |
DocModel | BibTeX / BibLaTeX, RIS and CSL-JSON parsing; citation and bibliography formatting. |
DocLayout |
DocModel, DocMath | Core Text line layout, pagination, page rendering, PDF publishing. |
DocReview |
DocModel | Document comparison (diff) and comparison reports. |
DocAudit |
DocModel | Document quality auditor and research checks. |
DocTemplates |
DocModel | The template library. |
DocAutomation |
all of the above | Workflows, batch processing, the orixdocs command-line tool. |
The document model in one page
- A
DocumentModelis a value. Undo is a stack of values; arrays are copy-on-write, so a snapshot shares storage with its successor. bodyis 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.- Sections are Word-like:
DocumentModel.pageSetupdescribes the first section, and each.sectionBreakblock carries thePageSetupof the section it starts. Headers and footers live inPageSetup. - A
Paragraphis a list ofRuns. A run is text with optional (inheritable)CharProps, an optional character style, an optional trackedRevision, an optionalFormatRevisionand the ids of the comments anchored on it. - Inline objects (image, shape, equation, note reference, citation, cross-reference, field, bookmark) are runs whose text is U+FFFC and whose
inlineholds the payload. A forced line break is U+2028 in the text; a tab is\t. - Every text offset is a UTF-16 code unit offset, always aligned on a composed character boundary (
String.composedBoundary…). Never index paragraph text with SwiftCharactercounts or scalar counts. - Formatting is resolved as: document defaults → paragraph style chain (
basedOn) → character style chain → direct properties.StyleSheet.paraProps/charPropsreturn fully resolved values. Built-in style ids equal Word's (Normal,Heading1,Title,Caption,FootnoteText…), seeStyleID. - Lists:
Paragraph.listreferences aListDefinitioninDocumentModel.listsplus a level. Labels are computed, never stored in the text. - Captions are ordinary paragraphs of style
Captionthat contain a.field(.sequence("Figure"))inline. Display equations are paragraphs holding one.equationinline withdisplay == true. - Footnotes and endnotes: a
.note(NoteRef)inline in the text, content inDocumentModel.notes[id]. - Citations: a
.citation(Citation)inline referencingBibEntry.keys ofDocumentModel.bibliography. Their displayed text and the bibliography are produced by aCitationFormattingimplementation (DocReferences), never stored. 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.- Tables:
Table.columnWidthsis the grid; aTableCellcoverscolSpangrid columns; vertical merges usevMerge(restart/continue) exactly like WordprocessingML. Cells hold paragraphs only (no nested tables). - Images are stored once in
DocumentModel.assets(not part of the JSON encoding) and referenced by id fromImageObject. - Tracked changes: an inserted run carries
Revision(kind: .insertion); deleted text stays in the paragraph withRevision(kind: .deletion);Paragraph.markRevisiontracks the paragraph mark.Paragraph.visibleTextis the text with all changes accepted.
Conventions
- Swift 6 language mode, strict concurrency. Model types are
Sendablevalues. - No network access anywhere in the package. No third-party dependency except SwiftMath (math typesetting).
- Importers treat input as hostile and report everything they cannot carry over as
FormatWarnings; they never drop content silently. - Every source file starts with the ORIX file header (project, file path, description, author, contact).
- Tests use Swift Testing (
import Testing).