# johnxnguyen/down architecture

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

- Interactive diagram: https://gitdiagram.com/johnxnguyen/down
- Repository: https://github.com/johnxnguyen/down

## Overview

##### Project type and purpose
- This is an open-source Swift library (`Down`) that provides blazing-fast CommonMark Markdown parsing and rendering.
- It embeds the C commonmark library (`cmark`) for parsing, exposes a Swift API (`Down`, `DownView`, renderable protocols), and supports multiple output formats (HTML, XML, LaTeX, groff, CommonMark, NSAttributedString, AST).

##### File structure
- Top-level packaging and CI: `.github/`, `docker/`, `Travis`, `swiftlint`, `Package.swift`, `podspec`.
- Example/demo apps: `Down-Example/`, `Down-Example/macOS Demo/`.
- Core Swift library: `Sources/Down/…` (AST, Styling, Visitors, Renderers, Views, Extensions, Enums).
- Embedded C library: `Sources/cmark/…`.
- Tests: `Tests/DownTests/…` covering AST, styling, binding, view rendering.
- Supporting files: artifact bundling (`Resources`, `Supporting Files/Configurations`).

##### README for additional insights
- Describes layers: parsing (via `Down` struct + `cmark`), rendering (various `Down*Renderable` protocols), view (`DownView`).
- Mentions configurable options, performance goals, supported platforms, packaging targets.

##### Main components and their interactions
a. Input layer
- Client code or `DownView` → invokes `Down(markdownString:)` or `DownView(..., markdownString:)`.
b. Parsing layer
- Swift wrapper (`Down` struct, renderable protocols) calls into the embedded C library (`cmark.c`) via a bridging header.
- `cmark` parses Markdown to a C data structure (AST).
c. AST layer
- AST nodes (`Sources/Down/AST/Nodes`) represent the document tree.
- Visitors (`Sources/Down/AST/Visitors`) walk the tree, producing intermediate structures (e.g., attributed string fragments).
d. Styling layer
- Stylers (`Sources/Down/AST/Styling/Stylers`) and layout managers generate styled text (e.g., attributes for paragraphs, code blocks) or handle debug layout.
e. Rendering layer
- Renderers (`Sources/Down/Renderers`) transform AST or styled text into output formats: HTML, XML, LaTeX, groff, CommonMark, NSAttributedString.
f. View layer
- `DownView` wraps a web view and loads pre-bundled HTML/CSS/JS resources to render Markdown content in a UI context.
g. Packaging & distribution
- Swift Package Manager (`Package.swift`), CocoaPods (`Down.podspec`), Carthage support.
h. Example & CI
- Demo apps show usage on iOS/macOS.
- CI definitions (`.github/workflows/swiftlint.yml`, `docker-compose.yml`, `Travis.yml`) ensure linting, building, testing, coverage.

##### Architectural patterns and design principles
- Layered pipeline: input → parse → AST → transform via visitors → rendering.
- Visitor pattern for AST traversal and extensibility.
- Protocol-oriented design for pluggable renderers (`Down*Renderable`).
- Clear separation of concerns: parsing (C) vs Swift AST vs rendering vs UI.
- Modular resource bundles for web view (`DownView.bundle`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client & API Layer"
        DownAPI["Down.swift\n(Swift Wrapper API)"]:::swift
        DownHeader["Down.h\n(Bridging Header)"]:::swift
        DownViewUpdate["DownView.update(markdownString:)"]:::ui
        DownViewUpdate -->|invokes| DownAPI
        DownAPI -->|exposes C interface| DownHeader
        DownHeader -->|calls into| Parsing
    end

    subgraph "Parsing Layer"
        Parsing["C Parser (cmark)"]:::c
    end

    Parsing -->|parses Markdown to AST| ASTNodes

    subgraph "AST Layer"
        ASTNodes["AST Nodes"]:::swift
    end

    ASTNodes -->|visited by| ASTVisitors

    subgraph "Visitors & Styling"
        ASTVisitors["AST Visitors"]:::swift
        Stylers["Stylers & Configuration"]:::swift
        LayoutManagers["Layout Managers"]:::swift
        AttributeCollections["Attribute Collections"]:::swift
        CustomAttributes["Custom Attributes"]:::swift
        Helpers["Helpers & Extensions"]:::swift
        Options["Styling Options"]:::swift
        TextViews["Text Views"]:::swift
    end

    ASTVisitors -->|triggers| Stylers
    Stylers -->|apply layout| LayoutManagers
    LayoutManagers -->|use| AttributeCollections
    Stylers -->|use| CustomAttributes
    Stylers -->|use| Helpers
    Stylers -->|respect| Options
    Stylers -->|render debug| TextViews
    Stylers -->|passes styled data to| Renderers

    subgraph "Rendering Layer"
        Renderers["Renderers\n(HTML, XML, LaTeX, groff,\nCommonMark, NSAttributedString)"]:::swift
    end

    Renderers -->|produces output| ClientOutput

    subgraph "View Layer"
        DownView["DownView UI"]:::ui
        BundleHelper["BundleHelper.swift"]:::swift
        WebBundles["WebView Resource Bundles"]:::ui
    end

    ClientOutput -->|rendered content to| DownView
    DownView -->|loads resources from| WebBundles
    DownView -->|uses| BundleHelper

    subgraph "Example & Demo Applications"
        IOSDemo["Down-Example"]:::ui
        MacDemo["macOS Demo"]:::ui
    end

    IOSDemo -->|uses library| DownAPI
    MacDemo -->|uses library| DownAPI

    subgraph "Packaging & Distribution"
        SwiftPM["Package.swift"]:::pack
        Podspec["Down.podspec"]:::pack
        SwiftPMWorkspace[".swiftpm"]:::pack
    end

    subgraph "Continuous Integration & Tooling"
        GHActions[".github/workflows/swiftlint.yml"]:::ci
        Travis[".travis.yml"]:::ci
        DockerCompose["docker-compose.yml"]:::ci
        Dockerfile["Dockerfile"]:::ci
    end

    %% Click Events
    click Parsing "https://github.com/johnxnguyen/down/tree/master/Sources/cmark"
    click DownAPI "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Down.swift"
    click DownHeader "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Down.h"
    click ASTNodes "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Nodes"
    click ASTVisitors "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Visitors"
    click AttributeCollections "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Attribute Collections"
    click CustomAttributes "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Custom Attributes"
    click Helpers "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Helpers/Extensions"
    click LayoutManagers "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Layout Managers"
    click Stylers "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Stylers"
    click Options "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Options"
    click TextViews "https://github.com/johnxnguyen/down/tree/master/Sources/Down/AST/Styling/Text Views"
    click Renderers "https://github.com/johnxnguyen/down/tree/master/Sources/Down/Renderers"
    click DownView "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Views/DownView.swift"
    click BundleHelper "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Views/BundleHelper.swift"
    click WebBundles "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Resources/DownView.bundle"
    click WebBundles "https://github.com/johnxnguyen/down/blob/master/Sources/Down/Resources/DownView (macOS).bundle"
    click IOSDemo "https://github.com/johnxnguyen/down/tree/master/Down-Example/Down-Example"
    click MacDemo "https://github.com/johnxnguyen/down/tree/master/Down-Example/macOS Demo"
    click SwiftPM "https://github.com/johnxnguyen/down/blob/master/Package.swift"
    click Podspec "https://github.com/johnxnguyen/down/blob/master/Down.podspec"
    click SwiftPMWorkspace "https://github.com/johnxnguyen/down/blob/master/.swiftpm"
    click GHActions "https://github.com/johnxnguyen/down/blob/master/.github/workflows/swiftlint.yml"
    click Travis "https://github.com/johnxnguyen/down/blob/master/.travis.yml"
    click DockerCompose "https://github.com/johnxnguyen/down/blob/master/docker/docker-compose.yml"
    click Dockerfile "https://github.com/johnxnguyen/down/tree/master/docker/Dockerfile"

    %% Styles
    classDef c fill:#f8d7da,stroke:#d9534f,color:#000;
    classDef swift fill:#d1ecf1,stroke:#17a2b8,color:#000;
    classDef ui fill:#d4edda,stroke:#28a745,color:#000;
    classDef pack fill:#fefefe,stroke:#6c757d,color:#000;
    classDef ci fill:#f8f9fa,stroke:#6c757d,color:#000;
```
