How btbytes/pandaku works
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.