# doconce/doconce architecture

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

- Interactive diagram: https://gitdiagram.com/doconce/doconce
- Repository: https://github.com/doconce/doconce

## Overview

##### Main Components
- Command-Line Interface (CLI) & Entry Points – The “bin” folder and setup.py indicate that users run DocOnce through command-line commands.
- Core Library Modules – The “lib/doconce” directory houses the conversion routines (modules like doconce.py, html.py, latex.py, slides.py, sphinx.py, etc.) as well as shared utilities (common.py, globals.py, etc.).
- Preprocessing and Templating Engine – DocOnce preprocesses the input text using tools like Mako and other preprocessing directives before conversion. This is a logical component in the conversion pipeline.
- Output Formatting Modules – Individual modules for each output format (HTML, LaTeX, slides, etc.) model the modular “factory” or “strategy” patterns.
- Bundled Assets & Themes – The “bundled” directory contains a large set of themes, CSS styles, JS scripts, LaTeX style files, and even Sphinx themes. These serve as static resource libraries that the conversion modules use to generate the final output.
- Configuration and Dependency Management – Files like requirements.txt, setup.py, Dockerfile, and CI/CD workflows in .github/workflows indicate mechanisms for building, testing, and deploying the tool.
- Testing and Documentation – The “test” directory (as well as the rich documentation in the README) signals an overlay of automated testing and documentation generation (via Sphinx and other tools).

- Within the Conversion Engine, illustrate a pipeline:
○ First, the Preprocessor (invoking Mako and any custom preprocessing) cleans and prepares the input.
○ Then, a format-specific “converter” module processes the preprocessed data into an intermediate representation.
○ Last, a Renderer leverages Bundled Assets (themes, styles, templates) to produce final output files.
- External dependencies (e.g., Python libraries installed via pip/conda and CI/CD systems) to indicate that they are used for building, testing, and package management.
- A “Tests” component that interacts with the core modules, ensuring correctness.

##### Important Architectural Patterns and Technologies
- Modularity & Plug-In Architecture – Each output format (HTML, LaTeX, slides, etc.) is handled by a separate module, promoting ease of extension.
- Layered Conversion Pipeline – Separation of concerns is evident with preprocessing, conversion, and rendering layers. This resembles the factory or pipeline design pattern, enabling clear data flow.
- Asset Bundling – The extensive “bundled” directory is used as a resource library that can be updated independently.
- CI/CD & Deployment – The presence of Dockerfile, GitHub workflows, and dependency files emphasizes continuous integration and deployment practices.
- Use of Standard Python Packaging – setup.py and requirements.txt indicate how the project is installed and maintained.

##### Final Assembly
- Drill down into each layer to show the various modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        A("User CLI Command"):::external
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        B("CLI Entry Point"):::coreProcessing
        C("Core Conversion Engine"):::coreProcessing
        D("Preprocessing & Templating"):::coreProcessing
        E("Output Formatting Modules"):::coreProcessing
        F("Renderer"):::coreProcessing
    end

    %% Assets & Configuration Layer
    subgraph "Assets & Configuration"
        G("Bundled Assets & Themes"):::assets
        subgraph "Configuration & Dependency Management"
            H1("setup.py"):::external
            H2("requirements.txt"):::external
            H3("Dockerfile"):::external
            H4(".github/workflows"):::external
        end
        subgraph "Testing & Documentation"
            I1("test"):::external
            I2("doc"):::external
        end
    end

    %% Data Flow
    A -->|"invokes"| B
    B -->|"calls"| C
    C -->|"preprocess"| D
    D -->|"converts"| E
    E -->|"renders"| F
    F -->|"uses"| G

    %% Configuration Dependencies (dotted arrows)
    H1 -.->|"configures"| B
    H2 -.->|"provides_dependencies"| B
    H3 -.->|"deployment"| B
    H4 -.->|"CI/CD"| B

    %% Testing & Documentation Dependencies
    I1 -.->|"tests"| C
    I2 -.->|"documents"| C

    %% Click Events
    click B "https://github.com/doconce/doconce/tree/main/bin/doconce"
    click C "https://github.com/doconce/doconce/tree/main/lib/doconce"
    click D "https://github.com/doconce/doconce/tree/main/lib/doconce"
    click E "https://github.com/doconce/doconce/blob/main/lib/doconce/html.py"
    click G "https://github.com/doconce/doconce/tree/main/bundled"
    click H1 "https://github.com/doconce/doconce/blob/main/setup.py"
    click H2 "https://github.com/doconce/doconce/blob/main/requirements.txt"
    click H3 "https://github.com/doconce/doconce/tree/main/Dockerfile"
    click H4 "https://github.com/doconce/doconce/tree/main/.github/workflows"
    click I1 "https://github.com/doconce/doconce/tree/main/test"
    click I2 "https://github.com/doconce/doconce/tree/main/doc"

    %% Styling
    classDef coreProcessing fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef assets fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef external fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px;
```
