# btbytes/pandaku architecture

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

- Interactive diagram: https://gitdiagram.com/btbytes/pandaku
- Repository: https://github.com/btbytes/pandaku

## Overview

##### Project Type and Purpose
- This is a single‐purpose, containerized microservice (“pandaku”) that exposes Pandoc as an HTTP API.
- It runs inside Docker and is deployed to Fly.io as a stateless service. Clients send JSON payloads (text + target format) and receive converted documents in the response.

##### File Structure Analysis
- Dockerfile – defines the container image with Pandoc server.
- Makefile – contains build, test, or deployment shortcuts (e.g., build Docker image, push to registry).
- fly.toml – Fly.io configuration (app name, ports, regions, environment variables).
- README.md – high-level overview, usage example.
- img/ – example illustration only, not part of runtime.

##### README Insights
- Confirms the HTTP POST interface, JSON input schema, and raw binary output.
- No databases or persistent storage; purely stateless.
- Deployed via Docker → Fly.io global edge.

##### Main Components
a. Client Application
- Python script (or any HTTP client) that issues POST to the service endpoint.
b. Internet / Load Balancer
- Fly.io’s global edge network or any HTTP load balancer in front of your container.
c. Containerized Pandoc Service
- Docker container running the Pandoc‐Server binary.
- Internally listens on a port (e.g., 8080).
d. Auxiliary Build & Deployment Infrastructure
- Makefile tasks (local build).
- Docker registry (optional).
- Fly.io control plane (deployment via flyctl using fly.toml).

##### Component Relationships and Data Flow
1) Client → HTTP(S) request → Fly.io edge / Load Balancer
2) Load Balancer → routes request → Docker container’s Pandoc server
3) Pandoc server → processes JSON, invokes Pandoc binary → returns converted bytes
4) Docker container → HTTP response → Fly.io edge → back to Client

##### Important Architectural Patterns & Principles
- Stateless microservice: no in-container persistence.
- Containerization: isolates Pandoc environment, simplifies dependencies.
- Infrastructure as Code: fly.toml defines runtime properties.
- CI/CD hook potential via Makefile or external pipelines.

##### Additional Details to Capture
- Port mapping: host 80/443 → container 8080.
- Mention Docker layering: base image → Pandoc installation → entrypoint.
- Fly.io regions or scaling configuration from fly.toml if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    %% Client and Runtime
    client["Client Application"]:::frontend
    lb["Fly.io Edge / Load Balancer"]:::runtime
    container["Docker Container\n(Pandoc-Server)"]:::runtime
    pandoc["Pandoc Binary"]:::runtime

    %% Stateless Note
    NoDB["No Persistent Storage"]:::infra

    %% Build Stage
    subgraph "Build Stage"
        make["Makefile"]:::infra
        dockerfile["Dockerfile"]:::infra
        registry["Docker Registry"]:::infra
        make --> dockerfile
        dockerfile -->|build image| registry
    end

    %% Deployment Stage
    subgraph "Deployment Stage"
        flytoml["fly.toml"]:::infra
        control["Fly.io Control Plane"]:::infra
        flytoml --> control
        control -->|deploy container| registry
        control -->|routes traffic| lb
    end

    %% Documentation
    readme["README.md"]:::infra

    %% Data Flow
    client -->|POST / → JSON| lb
    lb -->|routes request| container
    container -->|invoke| pandoc
    pandoc -->|converted bytes| container
    container -->|200 OK → docx bytes| lb
    lb --> client

    %% Stateless annotation
    container -.-> NoDB

    %% Click Events
    click dockerfile "https://github.com/btbytes/pandaku/tree/main/Dockerfile"
    click make "https://github.com/btbytes/pandaku/tree/main/Makefile"
    click flytoml "https://github.com/btbytes/pandaku/blob/main/fly.toml"
    click readme "https://github.com/btbytes/pandaku/blob/main/README.md"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef infra fill:#90EE90,stroke:#000,stroke-width:1px
    classDef runtime fill:#FFA500,stroke:#000,stroke-width:1px
```
