# delfanbaum/asciidocr architecture

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

- Interactive diagram: https://gitdiagram.com/delfanbaum/asciidocr
- Repository: https://github.com/delfanbaum/asciidocr

## Overview

##### Main Components

a. Input Layer:
- File Input Handler (supports files and stdin)
- Resolution System (shown by nested-includes support in tests)

b. Processing Pipeline:
- Scanner Component (src/scanner)
- Tokenization (tokens.rs)
- Parser Component (src/parser.rs)
- Abstract Syntax Graph (src/graph)
- Blocks
- Inlines
- Lists
- Metadata
- Nodes

c. Backend Rendering Layer (src/backends):
- HTMLBook Backend
- DOCX Backend (experimental)
- JSON Backend (for testing/compatibility)

##### Key Relationships

- Input → Scanner → Parser → ASG → Backend Renderers → Output
- Template system's connection to the backends
- Relationship between the ASG components

##### Specific Implementation Details

**[Input] → [Scanner] → [Parser] → [ASG] → [Backend Selection] → [Renderers]**
- ↑                                           ↓
**[Include]                                 [Templates]**
**Resolution                                    ↓**
- [HTMLBook] [DOCX] [JSON]

##### Additional Elements

- A note about the experimental status of the DOCX backend
- Relationship with the testing infrastructure
- Where the CLI interface (src/bin/asciidocr) fits in

##### Important Architectural Patterns to Highlight

- Pipeline processing pattern
- Plugin-style backend system
- Template-based rendering
- Abstract Syntax Graph for intermediate representation

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Input
        FI[File Input Handler]:::input
        IR[Include Resolution]:::input
        FI --> IR
    end

    subgraph "Processing Pipeline"
        SC[Scanner]:::core
        TK[Tokenization]:::core
        PR[Parser]:::core
        
        subgraph "Abstract Syntax Graph"
            ASG[ASG Core]:::core
            BL[Blocks]:::core
            IL[Inlines]:::core
            LS[Lists]:::core
            MD[Metadata]:::core
            ND[Nodes]:::core
            
            ASG --> BL
            ASG --> IL
            ASG --> LS
            ASG --> MD
            ASG --> ND
        end
        
        SC --> TK
        TK --> PR
        PR --> ASG
    end

    subgraph "Backend Layer"
        BS[Backend Selection]:::backend
        
        subgraph "Templates"
            DT[DOCX Templates]:::template
            HT[HTMLBook Templates]:::template
        end
        
        subgraph "Renderers"
            HB[HTMLBook Backend]:::backend
            DX["DOCX Backend<br/>(Experimental)"]:::backend
            JS[JSON Backend]:::backend
        end
        
        BS --> HB
        BS --> DX
        BS --> JS
        
        DT --> DX
        HT --> HB
    end

    subgraph "Testing Infrastructure"
        TU[Test Utils]:::test
        BT[Block Tests]:::test
        DT2[Document Tests]:::test
        HT2[HTMLBook Tests]:::test
        DT3[DOCX Tests]:::test
    end

    IR --> SC
    ASG --> BS

    %% Click events for component mapping
    click SC "https://github.com/delfanbaum/asciidocr/blob/main/src/scanner/mod.rs"
    click TK "https://github.com/delfanbaum/asciidocr/blob/main/src/scanner/tokens.rs"
    click PR "https://github.com/delfanbaum/asciidocr/blob/main/src/parser.rs"
    click ASG "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/asg.rs"
    click BL "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/blocks.rs"
    click IL "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/inlines.rs"
    click LS "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/lists.rs"
    click MD "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/metadata.rs"
    click ND "https://github.com/delfanbaum/asciidocr/blob/main/src/graph/nodes.rs"
    click HB "https://github.com/delfanbaum/asciidocr/blob/main/src/backends/htmls.rs"
    click DX "https://github.com/delfanbaum/asciidocr/blob/main/src/backends/docx.rs"
    click BS "https://github.com/delfanbaum/asciidocr/blob/main/src/backends/mod.rs"
    click DT "https://github.com/delfanbaum/asciidocr/tree/main/templates/docx/"
    click HT "https://github.com/delfanbaum/asciidocr/tree/main/templates/htmlbook/"
    click TU "https://github.com/delfanbaum/asciidocr/blob/main/tests/common/mod.rs"
    click BT "https://github.com/delfanbaum/asciidocr/blob/main/tests/block_tests.rs"
    click DT2 "https://github.com/delfanbaum/asciidocr/blob/main/tests/document_tests.rs"
    click HT2 "https://github.com/delfanbaum/asciidocr/blob/main/tests/htmlbook_tests.rs"
    click DT3 "https://github.com/delfanbaum/asciidocr/blob/main/tests/docx_tests.rs"

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef input fill:#2ecc71,stroke:#27ae60,color:white
    classDef backend fill:#e67e22,stroke:#d35400,color:white
    classDef template fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef test fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Input Handling]:::input
        L3[Backend Components]:::backend
        L4[Templates]:::template
        L5[Testing]:::test
    end
```
