# y1jiong/md2img architecture

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

- Interactive diagram: https://gitdiagram.com/y1jiong/md2img
- Repository: https://github.com/y1jiong/md2img

## Overview

##### Project type and purpose
- md2img is a single-binary Go HTTP service (full-stack in the sense that it provides a REST API and does server-side rendering).
- It exposes three endpoints (`/markdown`, `/html`, `/url`) to convert input into an image (PNG or JPEG).

##### File structure
- Top-level: `main.go`, `internal/`, `util/`, `manifest/`, `Makefile`, `go.mod`
- `internal/cmd`: CLI commands (install, version)
- `internal/controller`: HTTP handlers for each endpoint
- `internal/service`:
- `browser`: invokes headless Chrome (via Chrome DevTools protocol) to render HTML and capture screenshots
- `manifest/deploy`: Dockerfile, configs, scripts for container image and local deployment

##### README for insights
- Confirms API routes, parameters (`width`, `mobile`, `html`), and that template customization is possible via `template.html`.
- Focus is on a stateless HTTP service packaged as a Docker image.

##### Main components
a. External HTTP Client (e.g., curl, another service)
b. API Gateway / HTTP Server (main.go + router)
c. Controller Layer (`internal/controller`)
- markdown.go
- html.go
- url.go
d. Service Layer (`internal/service`)
- Browser Service (headless Chrome wrapper)
f. Optional: CLI Commands (`internal/cmd/install.go`, `version.go`)
g. Deployment (Docker image, local.conf, Makefile)

##### Relationships and data flow
1. HTTP Client → (POST) → HTTP Server
2. HTTP Server → Controller → appropriate handler based on path
3. Handler → Service Layer:
- If `/markdown`: pass raw markdown → Markdown Service → HTML string
- If `/html`: pass raw HTML → skip markdown conversion
- If `/url`: pass URL → Browser Service fetches HTML from remote resource
4. HTML string → Browser Service
5. Browser Service uses headless Chrome → renders page → captures screenshot → returns image bytes
6. Controller → writes image bytes in HTTP response

##### Architectural patterns and design principles
- Layered architecture (Controller → Service → External engine)
- Separation of concerns: parsing & templating vs. rendering/screenshot
- Stateless, request-driven design for high concurrency
- Single deployable unit (monolith) packaged in Docker for ease of distribution

##### Technologies & frameworks
- Go standard library (net/http)
- Chrome DevTools Protocol (for headless rendering)
- HTML templating (built-in Go templates)
- Docker (for containerization)

- Clear, concise component labels
- Blue for internal Go components
- Green for external/runtime (Chrome)
- Yellow for deployment/config (Docker, Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["HTTP Client (curl, service)"]:::external

    %% API Server
    APIServer["HTTP Server\n(main.go)"]:::internal
    click APIServer "https://github.com/y1jiong/md2img/blob/main/main.go"

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        MDController["markdown.go"]:::internal
        click MDController "https://github.com/y1jiong/md2img/blob/main/internal/controller/markdown.go"
        HTMLController["html.go"]:::internal
        click HTMLController "https://github.com/y1jiong/md2img/blob/main/internal/controller/html.go"
        URLController["url.go"]:::internal
        click URLController "https://github.com/y1jiong/md2img/blob/main/internal/controller/url.go"
        Common["common.go"]:::internal
        click Common "https://github.com/y1jiong/md2img/blob/main/internal/controller/common.go"
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        MarkdownService["Markdown Service"]:::internal
        click MarkdownService "https://github.com/y1jiong/md2img/blob/main/internal/service/markdown/markdown.go"
        BrowserService["Browser Service"]:::internal
        click BrowserService "https://github.com/y1jiong/md2img/blob/main/internal/service/browser/chrome.go"
    end

    %% Template Assets
    subgraph "Template Assets"
        direction TB
        TemplateHTML["template.html"]:::internal
        click TemplateHTML "https://github.com/y1jiong/md2img/blob/main/internal/service/markdown/template.html"
        MathJax["mathjax.html"]:::internal
        click MathJax "https://github.com/y1jiong/md2img/blob/main/internal/service/markdown/mathjax.html"
        Mermaid["mermaid.html"]:::internal
        click Mermaid "https://github.com/y1jiong/md2img/blob/main/internal/service/markdown/mermaid.html"
    end

    %% Browser Engine
    BrowserEngine["Headless Chrome\n(Chrome DevTools)"]:::external

    %% Deployment & Config
    subgraph "Deployment / Config"
        direction TB
        Dockerfile["Dockerfile"]:::config
        click Dockerfile "https://github.com/y1jiong/md2img/tree/main/manifest/deploy/Dockerfile"
        LocalConf["local.conf"]:::config
        click LocalConf "https://github.com/y1jiong/md2img/blob/main/manifest/deploy/local.conf"
        PackScript["pack-image.sh"]:::config
        click PackScript "https://github.com/y1jiong/md2img/blob/main/manifest/deploy/pack-image.sh"
        MakefileNode["Makefile"]:::config
        click MakefileNode "https://github.com/y1jiong/md2img/tree/main/Makefile"
    end

    %% Flow
    Client -->|POST /markdown, /html, /url| APIServer
    APIServer --> MDController
    APIServer --> HTMLController
    APIServer --> URLController

    MDController -->|raw MD| MarkdownService
    HTMLController -->|raw HTML| MarkdownService
    URLController -->|URL| BrowserService

    MarkdownService --> TemplateHTML
    MarkdownService --> MathJax
    MarkdownService --> Mermaid

    MarkdownService -->|HTML+Assets| BrowserService
    BrowserService -->|render & screenshot| BrowserEngine
    BrowserEngine -->|image bytes| BrowserService
    BrowserService -->|image bytes| MDController
    BrowserService -->|image bytes| HTMLController
    BrowserService -->|image bytes| URLController

    MDController -->|HTTP Response| Client
    HTMLController -->|HTTP Response| Client
    URLController -->|HTTP Response| Client

    APIServer --> Deployment & Config

    %% Styles
    classDef internal fill:#cbe1f1,stroke:#339,stroke-width:1px;
    classDef external fill:#d2f8d2,stroke:#2a8f2a,stroke-width:1px;
    classDef config fill:#fff3a3,stroke:#cca300,stroke-width:1px;
```
