# kovetskiy/mark architecture

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

- Interactive diagram: https://gitdiagram.com/kovetskiy/mark
- Repository: https://github.com/kovetskiy/mark

## Overview

##### Project Type & Purpose
- Is a command-line tool written in Go that reads markdown files (with extended metadata), converts them to HTML, and then updates (or creates) corresponding pages in a Confluence instance using its REST API.
- Its purpose is to allow documentation maintained in Git repositories to be “synced” directly to Confluence without the manual overhead of using a WYSIWYG editor.

##### File Tree & Identify Components
- At the root level, you see key files like main.go, auth.go, a Dockerfile, Makefile, and configuration files. These indicate a CLI tool using Go, with support for containerized builds and CI via Docker and GitHub Actions.
- Several directories indicate logical separation of functionality:
- attachment: Contains code (and tests) related to handling file attachments uploaded to Confluence.
- confluence: Houses the confluence API integration – the interface that sends HTML content and pages to Confluence.
- markdown: Manages markdown processing and conversion logic.
- metadata: Parses and extracts HTML-ish metadata headers from the markdown files.
- parser: Deals with parsing specific markdown extensions such as Confluence identifiers and tags.
- renderer: Contains logic for converting markdown constructs (such as headings, blockquotes, code blocks, images, etc.) into HTML fragments.
- macro: Implements the processing and replacement of custom macros defined in the markdown.
- includes: Likely supports inserting Go templates or other include file functionality.
- page: Contains code managing Confluence page linkage, ancestry, or related page operations.
- stdlib and vfs: Provide helper functions and virtual file system utilities, respectively.
- Supporting files for CI/CD (docker-compose.yaml, Taskfile.yml, GitHub workflows, etc.) indicate an automated build and release process.

a. Break down the system into main logical components:
- CLI Frontend & Configuration: Represents main.go, auth.go, command-line flags configuration, and overall program initialization.
- Markdown Input Module:
– Metadata & File Parsing (metadata, parser directories) to extract Confluence-specific headers.
– Markdown Processing (markdown directory) that converts the base markdown content.
- Content Renderer Module:
– Renderer: Processes individual markdown elements into HTML (renderer directory).
– Macro & Template Handling: Processes macros (macro directory) and includes (includes) to extend markdown functionality.
- Attachment Handler: Manages attachments (attachment folder) ensuring that referenced files are properly located, uploaded, and embedded on the Confluence page.
- Confluence Integration Module:
– Confluence API Adapter (confluence directory) forms the connection, wraps the REST API calls to create/update pages.
– Page Managing Logic (page directory) that organizes parent-child relationships and manages title/ancestry.
- Utility & Support Modules:
– Standard Library Extensions (stdlib)
– Virtual File System (vfs)
- CI/CD & Build Components: Dockerfile, docker-compose.yaml, Makefile, and GitHub workflows; these illustrate the automated build, testing, and deployment processes.

b. Relationships & Data Flow:
- The markdown input module will first parse file metadata and then process markdown content.
- The attachment handler works concurrently where attachment paths from the metadata are checked, uploaded, and linked with the content.
- The Confluence integration module collects the final HTML output along with metadata (page titles, parent pages, etc.) and makes REST API calls to either create new pages or update existing ones.
- Optionally, include the CI/CD pipeline as an external component feeding into build and test automation.

c. Architectural Patterns and Design Principles:
- Modularization: The directory structure clearly indicates separation of concerns (parsing, rendering, API integration, attachment handling).
- Pipeline/Data Flow Pattern: Markdown input is passed through a series of processing stages (parsing, macro substitution, rendering) before being transmitted.
- Testability: Presence of corresponding _test.go files in many components indicates the design supports unit testing.

d. Technologies, Frameworks, or Libraries:
- Go Programming Language: The primary language plus dependency management (go.mod, go.sum).
- Docker & Docker Compose: Used for containerization and building the project.
- CI and Release Pipelines: GitHub Actions (workflows/ci.yml, goreleaser.yml) and Taskfile for build automation.
- Confluence REST API integration: All protocols and REST calls are built into the project through the "confluence" package.
- Markdown processing and templating libraries (standard in Go) extended with custom renderer/macro logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-Level Input
    UserInput("User Input"):::user

    %% CLI Frontend & Configuration
    CLIConfig("CLI & Config"):::cli

    %% Markdown Input Module – Metadata & File Parsing
    MetaParse("Metadata & Parsing"):::parsing

    %% Markdown Input Module – Markdown Processing
    MarkdownProcessing("Markdown Processing"):::mdproc

    %% Content Renderer Module
    subgraph "Content Renderer Module"
        RendererBasic("Basic Rendering"):::renderer
        RendererMacro("Macro & Template Handling"):::renderer
        RendererMermaid("Mermaid Diagram Plugin"):::renderer
    end

    %% Attachment Handler
    AttachmentHandler("Attachment Handler"):::attachment

    %% Confluence Integration Module
    subgraph "Confluence Integration Module"
        ConfAPI("Confluence API Adapter"):::confluence
        ConfPage("Page Management"):::confluence
    end

    %% Utility & Support Modules
    subgraph "Utility & Support Modules"
        StdLib("Standard Library Extensions"):::utility
        VFS("Virtual File System"):::utility
    end

    %% CI/CD & Build Components
    CICD("CI/CD Pipeline"):::cicd

    %% Data Flow
    UserInput --> CLIConfig
    CLIConfig --> MetaParse
    MetaParse --> MarkdownProcessing
    MarkdownProcessing --> RendererBasic
    MarkdownProcessing --> RendererMacro
    MarkdownProcessing --> RendererMermaid
    MetaParse --> AttachmentHandler
    RendererBasic --> ConfAPI
    RendererMacro --> ConfAPI
    RendererMermaid --> ConfAPI
    AttachmentHandler --> ConfAPI
    ConfAPI --> ConfPage

    %% Utility Support (dashed helper arrows)
    StdLib --- MarkdownProcessing
    VFS --- MarkdownProcessing
    StdLib --- ConfAPI
    VFS --- ConfAPI

    %% CI/CD triggers build (dashed arrow)
    CICD --- CLIConfig

    %% Click Events
    click CLIConfig "https://github.com/kovetskiy/mark/blob/master/main.go"
    click CLIConfig "https://github.com/kovetskiy/mark/blob/master/auth.go"
    click MetaParse "https://github.com/kovetskiy/mark/blob/master/metadata/metadata.go"
    click MetaParse "https://github.com/kovetskiy/mark/blob/master/parser/confluenceids.go"
    click MetaParse "https://github.com/kovetskiy/mark/blob/master/parser/confluencetags.go"
    click MarkdownProcessing "https://github.com/kovetskiy/mark/blob/master/markdown/markdown.go"
    click RendererBasic "https://github.com/kovetskiy/mark/blob/master/renderer/heading.go"
    click RendererMacro "https://github.com/kovetskiy/mark/blob/master/macro/macro.go"
    click RendererMacro "https://github.com/kovetskiy/mark/blob/master/includes/templates.go"
    click RendererMermaid "https://github.com/kovetskiy/mark/blob/master/mermaid/mermaid.go"
    click AttachmentHandler "https://github.com/kovetskiy/mark/blob/master/attachment/attachment.go"
    click ConfAPI "https://github.com/kovetskiy/mark/blob/master/confluence/api.go"
    click ConfPage "https://github.com/kovetskiy/mark/blob/master/page/page.go"
    click ConfPage "https://github.com/kovetskiy/mark/blob/master/page/ancestry.go"
    click ConfPage "https://github.com/kovetskiy/mark/blob/master/page/link.go"
    click StdLib "https://github.com/kovetskiy/mark/blob/master/stdlib/stdlib.go"
    click VFS "https://github.com/kovetskiy/mark/blob/master/vfs/vfs.go"
    click CICD "https://github.com/kovetskiy/mark/tree/master/Dockerfile"
    click CICD "https://github.com/kovetskiy/mark/blob/master/docker-compose.yaml"
    click CICD "https://github.com/kovetskiy/mark/tree/master/Makefile"
    click CICD "https://github.com/kovetskiy/mark/blob/master/Taskfile.yml"
    click CICD "https://github.com/kovetskiy/mark/blob/master/.github/workflows/ci.yml"
    click CICD "https://github.com/kovetskiy/mark/blob/master/.github/workflows/goreleaser.yml"

    %% Styles
    classDef user fill:#b3cde0,stroke:#03396c,stroke-width:2px;
    classDef cli fill:#f4a582,stroke:#d95f02,stroke-width:2px;
    classDef parsing fill:#92c5de,stroke:#0571b0,stroke-width:2px;
    classDef mdproc fill:#d5f4e6,stroke:#2a9d8f,stroke-width:2px;
    classDef renderer fill:#f6e8c3,stroke:#c99400,stroke-width:2px;
    classDef attachment fill:#fdd49e,stroke:#f768a1,stroke-width:2px;
    classDef confluence fill:#c7e9c0,stroke:#31a354,stroke-width:2px;
    classDef utility fill:#decbe4,stroke:#6a51a3,stroke-width:2px;
    classDef cicd fill:#f1eef6,stroke:#54278f,stroke-width:2px;

    class UserInput user;
    class CLIConfig cli;
    class MetaParse parsing;
    class MarkdownProcessing mdproc;
    class RendererBasic,RendererMacro,RendererMermaid renderer;
    class AttachmentHandler attachment;
    class ConfAPI,ConfPage confluence;
    class StdLib,VFS utility;
    class CICD cicd;
```
