# gomutex/godocx architecture

> Architecture diagram of the GitHub repository gomutex/godocx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gomutex/godocx
- Repository: https://github.com/gomutex/godocx

## Overview

#### Purpose and public entry points
Godocx is a pure-Go library (Go 1.18+) for creating, modifying, reading, and writing DOCX/Office Open XML documents. Consumers primarily use the root package’s document lifecycle APIs, then fluent document-content APIs. Key entry points: `document.go`, `docx/document.go`, `docx/writer.go`.

#### Document lifecycle and façade
The root package exposes document construction/opening and delegates implementation to the `docx` package. The `docx.Document` model owns document state and operations such as adding content and saving. This is the main API boundary between application code and OOXML internals.
Paths: `document.go`, `docx/document.go`, `docx/doc.go`.

#### High-level Word document composition
`docx` provides authoring primitives for body content: paragraphs/runs, headings, tables, hyperlinks, pictures, numbering, styles, and document properties. These components mutate the in-memory document model rather than directly emitting files.
Paths: `docx/paragraph.go`, `docx/run.go`, `docx/table.go`.

#### OOXML WordprocessingML model
The `wml` layer represents the XML vocabulary behind Word documents. `wml/ctypes` contains composite XML structures for paragraphs, runs, tables, sections, headers/footers, and formatting; `wml/stypes` supplies XML simple/enumerated types. This layer is the schema-shaped boundary used by higher-level `docx` composition.
Paths: `wml/ctypes/para.go`, `wml/ctypes/table.go`, `wml/stypes/doc.go`.

#### DrawingML and embedded graphics
Drawing support is modeled separately through `dml`, including inline/anchored drawings, position/wrapping, graphic frames, and picture/blip structures. The document picture API connects user-level image insertion to these DrawingML representations and document relationships.
Paths: `docx/pic.go`, `dml/drawing.go`, `dml/dmlpic/pic.go`.

#### Package parts, relationships, and serialization
DOCX is handled as a ZIP-based Open Packaging Convention container. The `packager` layer manages ZIP creation/extraction, package URIs, and `.rels` relationship parts. `docx` defines package parts such as document XML, content types, styles, numbering, core properties, and relationships, then writes them into the archive.
Paths: `packager/zip.go`, `packager/rels.go`, `docx/rels.go`.

#### Primary flows and boundaries
For creation: caller → root/document façade → `docx` content APIs → WML/DML object graph → writer/package-part assembly → `packager` ZIP output (`.docx`). For reading: DOCX ZIP → package unpacking/relationship resolution → XML-backed `docx` model exposed to callers. The material external format is Microsoft DOCX/OOXML; there are no service, database, or web-runtime dependencies indicated. Default document scaffolding is sourced from `templates/default.docx`.
Paths: `docx/writer.go`, `packager/unpack.go`, `templates/default.docx`.

Main entry points: [`docx/document.go`](https://github.com/gomutex/godocx/blob/main/docx/document.go) (Document model), [`docx/writer.go`](https://github.com/gomutex/godocx/blob/main/docx/writer.go) (Writer and parts), [`docx/paragraph.go`](https://github.com/gomutex/godocx/blob/main/docx/paragraph.go) (Content APIs), [`docx/pic.go`](https://github.com/gomutex/godocx/blob/main/docx/pic.go) (Picture API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_root_document["Root document façade<br/>Go API<br/>[document.go]"]
end

subgraph group_authoring["Document Authoring"]
  node_document_model["Document model<br/>docx<br/>[document.go]"]
  node_content_apis["Content APIs<br/>docx authoring<br/>[paragraph.go]"]
  node_picture_api["Picture API<br/>docx authoring<br/>[pic.go]"]
  node_writer["Writer and parts<br/>docx serialization<br/>[writer.go]"]
end

subgraph group_ooxml["OOXML Models"]
  node_wml_composites["WordprocessingML composites<br/>wml ctypes<br/>[para.go]"]
  node_wml_simple_types["WordprocessingML simple types<br/>wml stypes<br/>[doc.go]"]
  node_drawingml["DrawingML graphics<br/>dml<br/>[drawing.go]"]
end

subgraph group_package["DOCX Packaging"]
  node_relationships["Relationships<br/>package rels<br/>[rels.go]"]
  node_zip_packager["ZIP packager<br/>[zip.go]"]
  node_unpacker["DOCX unpacker<br/>packager<br/>[unpack.go]"]
  node_default_template["Default scaffold<br/>DOCX template<br/>[default.docx]"]
end

node_caller(("Library consumer"))
node_docx_file["DOCX / OOXML file<br/>external format"]

node_caller -->|"create or open"| node_root_document
node_root_document -->|"delegates"| node_document_model
node_document_model -->|"exposes"| node_content_apis
node_content_apis -->|"builds"| node_wml_composites
node_wml_composites -->|"uses"| node_wml_simple_types
node_content_apis -->|"inserts images through"| node_picture_api
node_picture_api -->|"builds"| node_drawingml
node_picture_api -->|"creates links"| node_relationships
node_document_model -->|"saves through"| node_writer
node_writer -->|"serializes"| node_wml_composites
node_writer -->|"writes"| node_relationships
node_writer -->|"packages parts"| node_zip_packager
node_default_template -.->|"initial scaffolding"| node_document_model
node_zip_packager -->|"writes"| node_docx_file
node_docx_file -->|"reads"| node_unpacker
node_unpacker -->|"reconstructs model"| node_document_model
node_unpacker -->|"resolves"| node_relationships

click node_root_document "https://github.com/gomutex/godocx/blob/main/document.go"
click node_document_model "https://github.com/gomutex/godocx/blob/main/docx/document.go"
click node_content_apis "https://github.com/gomutex/godocx/blob/main/docx/paragraph.go"
click node_picture_api "https://github.com/gomutex/godocx/blob/main/docx/pic.go"
click node_writer "https://github.com/gomutex/godocx/blob/main/docx/writer.go"
click node_wml_composites "https://github.com/gomutex/godocx/blob/main/wml/ctypes/para.go"
click node_wml_simple_types "https://github.com/gomutex/godocx/blob/main/wml/stypes/doc.go"
click node_drawingml "https://github.com/gomutex/godocx/blob/main/dml/drawing.go"
click node_relationships "https://github.com/gomutex/godocx/blob/main/docx/rels.go"
click node_zip_packager "https://github.com/gomutex/godocx/blob/main/packager/zip.go"
click node_unpacker "https://github.com/gomutex/godocx/blob/main/packager/unpack.go"
click node_default_template "https://github.com/gomutex/godocx/blob/main/templates/default.docx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_document toneBlue
class node_document_model,node_content_apis,node_picture_api,node_writer toneAmber
class node_wml_composites,node_wml_simple_types,node_drawingml toneMint
class node_relationships,node_zip_packager,node_unpacker,node_default_template toneRose
class node_caller,node_docx_file toneNeutral
```

## Components

### Public API

- [Root document façade](https://github.com/gomutex/godocx/blob/main/document.go): Go API · Construction and open lifecycle entry points. · `document.go`

### Document Authoring

- [Document model](https://github.com/gomutex/godocx/blob/main/docx/document.go): docx · Owns document state and save operations. · `docx/document.go`
- [Content APIs](https://github.com/gomutex/godocx/blob/main/docx/paragraph.go): docx authoring · Paragraphs, runs, and tables mutate the document model. · `docx/paragraph.go`
- [Picture API](https://github.com/gomutex/godocx/blob/main/docx/pic.go): docx authoring · Connects image insertion to drawings and relationships. · `docx/pic.go`
- [Writer and parts](https://github.com/gomutex/godocx/blob/main/docx/writer.go): docx serialization · Assembles document XML and package parts. · `docx/writer.go`

### OOXML Models

- [WordprocessingML composites](https://github.com/gomutex/godocx/blob/main/wml/ctypes/para.go): wml ctypes · Schema-shaped paragraphs, runs, tables, sections, and formatting. · `wml/ctypes/para.go`
- [WordprocessingML simple types](https://github.com/gomutex/godocx/blob/main/wml/stypes/doc.go): wml stypes · `wml/stypes/doc.go`
- [DrawingML graphics](https://github.com/gomutex/godocx/blob/main/dml/drawing.go): dml · Inline and anchored drawing structures. · `dml/drawing.go`

### DOCX Packaging

- [Relationships](https://github.com/gomutex/godocx/blob/main/docx/rels.go): package rels · Defines OOXML part relationships. · `docx/rels.go`
- [ZIP packager](https://github.com/gomutex/godocx/blob/main/packager/zip.go): packager · Creates DOCX ZIP containers and relationship parts. · `packager/zip.go`
- [DOCX unpacker](https://github.com/gomutex/godocx/blob/main/packager/unpack.go): packager · Extracts packages for reading. · `packager/unpack.go`
- [Default scaffold](https://github.com/gomutex/godocx/blob/main/templates/default.docx): DOCX template · `templates/default.docx`

### Other components

- **Library consumer**: application
- **DOCX / OOXML file**: external format

## Connections

- Library consumer → Root document façade: create or open
- Root document façade → Document model: delegates
- Document model → Content APIs: exposes
- Content APIs → WordprocessingML composites: builds
- WordprocessingML composites → WordprocessingML simple types: uses
- Content APIs → Picture API: inserts images through
- Picture API → DrawingML graphics: builds
- Picture API → Relationships: creates links
- Document model → Writer and parts: saves through
- Writer and parts → WordprocessingML composites: serializes
- Writer and parts → Relationships: writes
- Writer and parts → ZIP packager: packages parts
- Default scaffold → Document model: initial scaffolding
- ZIP packager → DOCX / OOXML file: writes
- DOCX / OOXML file → DOCX unpacker: reads
- DOCX unpacker → Document model: reconstructs model
- DOCX unpacker → Relationships: resolves