# doorstop-dev/doorstop architecture

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

- Interactive diagram: https://gitdiagram.com/doorstop-dev/doorstop
- Repository: https://github.com/doorstop-dev/doorstop

## Overview

Doorstop manages textual requirements and other linkable items stored as YAML files in version control. The principal workflow is to create documents and items, link items across a document tree, validate traceability, and publish reports. CLI commands orchestrate core operations; a GUI and server provide additional interfaces. The graph reflects README statements and SOURCE INDEX references, but many implementation details—especially tree behavior and server routing—were not excerpted, so uncertain connections are omitted.

Main entry points: [`doorstop/cli/commands.py`](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/cli/commands.py) (CLI commands), [`doorstop/core/item.py`](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/item.py) (Requirement items), [`doorstop/core/publisher.py`](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publisher.py) (Publish orchestration), [`doorstop/core/document.py`](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/document.py) (Documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI entry point<br/>[main.py]"]
  node_commands["CLI commands<br/>[commands.py]"]
  node_gui["Desktop GUI<br/>[application.py]"]
  node_gui_main["GUI entry point<br/>[main.py]"]
  node_server["HTTP server<br/>[main.py]"]
end

subgraph group_model["Requirements model"]
  node_tree["Document tree<br/>[tree.py]"]
  node_document["Documents<br/>[document.py]"]
  node_item["Requirement items<br/>[item.py]"]
  node_yaml_files[("YAML item files")]
  node_types["UIDs and levels<br/>[types.py]"]
end

subgraph group_operations["Document operations"]
  node_builder["Tree builder<br/>[builder.py]"]
  node_importer["Import and create<br/>[importer.py]"]
  node_editor["Item editor<br/>[editor.py]"]
  node_exporter["Export documents<br/>[exporter.py]"]
end

subgraph group_output["Validation and publishing"]
  node_validator["Item validation<br/>[item_validator.py]"]
  node_reference_finder["Reference finder"]
  node_yaml_validator["YAML validation<br/>[yaml_validator.py]"]
  node_publisher["Publish orchestration<br/>[publisher.py]"]
  node_publisher_base["Publisher base<br/>[base.py]"]
  node_html["HTML publisher<br/>[html.py]"]
  node_markdown["Markdown publisher<br/>[markdown.py]"]
  node_latex["LaTeX publisher<br/>[latex.py]"]
  node_text["Text publisher<br/>[text.py]"]
  node_template["Publish templates<br/>[template.py]"]
end

subgraph group_integration["External integration"]
  node_vcs["Version control<br/>[__init__.py]"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_user -.->|"opens GUI"| node_gui_main
node_cli -->|"dispatches to"| node_commands
node_commands -->|"builds tree"| node_builder
node_builder -->|"constructs"| node_tree
node_builder -->|"uses"| node_vcs
node_tree -.->|"contains"| node_document
node_document -->|"manages"| node_item
node_item -->|"reads and writes"| node_yaml_files
node_item -->|"uses identifiers"| node_types
node_commands -->|"creates and imports"| node_importer
node_importer -->|"updates documents"| node_document
node_importer -->|"creates items"| node_item
node_commands -->|"opens editor"| node_editor
node_commands -->|"exports data"| node_exporter
node_commands -->|"publishes reports"| node_publisher
node_publisher -->|"selects format"| node_html
node_publisher -->|"selects format"| node_latex
node_publisher -->|"selects format"| node_markdown
node_publisher -->|"selects format"| node_text
node_html -->|"extends"| node_publisher_base
node_markdown -->|"extends"| node_publisher_base
node_latex -->|"extends"| node_publisher_base
node_publisher_base -->|"uses templates"| node_template
node_item -->|"validates YAML"| node_yaml_validator
node_item -->|"finds references"| node_reference_finder
node_document -->|"validates items"| node_validator
node_gui_main -->|"starts interface"| node_gui
node_gui -->|"loads project tree"| node_builder
node_server -->|"serves published HTML"| node_html

click node_cli "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/cli/main.py"
click node_commands "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/cli/commands.py"
click node_gui "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/gui/application.py"
click node_gui_main "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/gui/main.py"
click node_server "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/server/main.py"
click node_tree "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tree.py"
click node_document "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/document.py"
click node_item "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/item.py"
click node_types "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/types.py"
click node_builder "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/builder.py"
click node_importer "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/importer.py"
click node_editor "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/editor.py"
click node_exporter "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/exporter.py"
click node_validator "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/validators/item_validator.py"
click node_reference_finder "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/reference_finder.py"
click node_yaml_validator "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/yaml_validator.py"
click node_publisher "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publisher.py"
click node_publisher_base "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/base.py"
click node_html "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/html.py"
click node_markdown "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/markdown.py"
click node_latex "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/latex.py"
click node_text "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/text.py"
click node_template "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/template.py"
click node_vcs "https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/vcs/__init__.py"

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_cli,node_commands,node_gui,node_gui_main,node_server,node_user toneBlue
class node_tree,node_document,node_item,node_yaml_files,node_types toneAmber
class node_builder,node_importer,node_editor,node_exporter toneMint
class node_validator,node_reference_finder,node_yaml_validator,node_publisher,node_publisher_base,node_html,node_markdown,node_latex,node_text,node_template toneRose
class node_vcs toneIndigo
```

## Components

### User interfaces

- [CLI entry point](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/cli/main.py): `doorstop/cli/main.py`
- [CLI commands](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/cli/commands.py): `doorstop/cli/commands.py`
- [Desktop GUI](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/gui/application.py): `doorstop/gui/application.py`
- [GUI entry point](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/gui/main.py): `doorstop/gui/main.py`
- [HTTP server](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/server/main.py): `doorstop/server/main.py`

### Requirements model

- [Document tree](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tree.py): `doorstop/core/tree.py`
- [Documents](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/document.py): `doorstop/core/document.py`
- [Requirement items](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/item.py): `doorstop/core/item.py`
- **YAML item files**
- [UIDs and levels](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/types.py): `doorstop/core/types.py`

### Document operations

- [Tree builder](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/builder.py): `doorstop/core/builder.py`
- [Import and create](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/importer.py): `doorstop/core/importer.py`
- [Item editor](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/editor.py): `doorstop/core/editor.py`
- [Export documents](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/exporter.py): `doorstop/core/exporter.py`

### Validation and publishing

- [Item validation](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/validators/item_validator.py): `doorstop/core/validators/item_validator.py`
- [Reference finder](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/reference_finder.py): `doorstop/core/reference_finder.py`
- [YAML validation](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/yaml_validator.py): `doorstop/core/yaml_validator.py`
- [Publish orchestration](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publisher.py): `doorstop/core/publisher.py`
- [Publisher base](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/base.py): `doorstop/core/publishers/base.py`
- [HTML publisher](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/html.py): `doorstop/core/publishers/html.py`
- [Markdown publisher](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/markdown.py): `doorstop/core/publishers/markdown.py`
- [LaTeX publisher](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/latex.py): `doorstop/core/publishers/latex.py`
- [Text publisher](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/publishers/text.py): `doorstop/core/publishers/text.py`
- [Publish templates](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/template.py): `doorstop/core/template.py`

### External integration

- [Version control](https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/vcs/__init__.py): `doorstop/core/vcs/__init__.py`

### Other components

- **User**

## Connections

- User → CLI entry point: runs commands (evidence: `README.md`)
- User → GUI entry point: opens GUI
- CLI entry point → CLI commands: dispatches to (evidence: `doorstop/cli/main.py`)
- CLI commands → Tree builder: builds tree (evidence: `doorstop/cli/commands.py`)
- Tree builder → Document tree: constructs (evidence: `doorstop/core/builder.py`)
- Tree builder → Version control: uses (evidence: `doorstop/core/builder.py`)
- Document tree → Documents: contains
- Documents → Requirement items: manages (evidence: `doorstop/core/document.py`)
- Requirement items → YAML item files: reads and writes (evidence: `doorstop/core/item.py`)
- Requirement items → UIDs and levels: uses identifiers (evidence: `doorstop/core/item.py`)
- CLI commands → Import and create: creates and imports (evidence: `doorstop/cli/commands.py`)
- Import and create → Documents: updates documents (evidence: `doorstop/core/importer.py`)
- Import and create → Requirement items: creates items (evidence: `doorstop/core/importer.py`)
- CLI commands → Item editor: opens editor (evidence: `doorstop/cli/commands.py`)
- CLI commands → Export documents: exports data (evidence: `doorstop/cli/commands.py`)
- CLI commands → Publish orchestration: publishes reports (evidence: `doorstop/cli/commands.py`)
- Publish orchestration → HTML publisher: selects format (evidence: `doorstop/core/publisher.py`)
- Publish orchestration → LaTeX publisher: selects format (evidence: `doorstop/core/publisher.py`)
- Publish orchestration → Markdown publisher: selects format (evidence: `doorstop/core/publisher.py`)
- Publish orchestration → Text publisher: selects format (evidence: `doorstop/core/publisher.py`)
- HTML publisher → Publisher base: extends (evidence: `doorstop/core/publishers/html.py`)
- Markdown publisher → Publisher base: extends (evidence: `doorstop/core/publishers/markdown.py`)
- LaTeX publisher → Publisher base: extends (evidence: `doorstop/core/publishers/latex.py`)
- Publisher base → Publish templates: uses templates (evidence: `doorstop/core/publishers/base.py`)
- Requirement items → YAML validation: validates YAML (evidence: `doorstop/core/item.py`)
- Requirement items → Reference finder: finds references (evidence: `doorstop/core/item.py`)
- Documents → Item validation: validates items (evidence: `doorstop/core/document.py`)
- GUI entry point → Desktop GUI: starts interface (evidence: `doorstop/gui/main.py`)
- Desktop GUI → Tree builder: loads project tree (evidence: `doorstop/gui/application.py`)
- HTTP server → HTML publisher: serves published HTML (evidence: `doorstop/server/main.py`)
