# zalwan/pdf-splitter architecture

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

- Interactive diagram: https://gitdiagram.com/zalwan/pdf-splitter
- Repository: https://github.com/zalwan/pdf-splitter

## Overview

##### Project type and purpose
- This is a monolithic, server-rendered web application (full-stack) written in Golang using the Gin framework.
- Its single business purpose is to accept a user-uploaded PDF, split it into single-page files (using pdfcpu), rename them per user input, bundle them into a ZIP, and present the ZIP for download.

##### File structure
- Top level:
- main.go        → application entry point; sets up the Gin router and handlers
- go.mod, go.sum → dependency management (Gin, pdfcpu, etc.)
- Dockerfile     → containerization setup
- .github/workflows/go.yml → CI pipeline (build/test)
- templates/     → HTML templates for the web UI
- Runtime (per README):
- uploads/       → storage for incoming PDF files
- temp_outputs/  → workspace for individual page files before zipping

##### README insights
- Confirms architecture is a single Gin HTTP server
- Lists core dependencies: pdfcpu for PDF operations; HTML templates for the view layer
- No external services or databases—only local file I/O and streaming response

##### Main components and their relationships
a. Browser (Client)
– Renders templates/index.html
– Submits multipart/form-data to `/split` endpoint
b. Gin Web Server (main.go)
– Routes:
- GET `/` → serve upload form
- POST `/split` → handler logic
– Invokes pdfcpu library to split PDF pages
– Renames pages based on user input
– Invokes ZIP compressor to bundle split files
– Serves the ZIP as an HTTP response
c. File Storage
– uploads/       (persistent or ephemeral storage for raw uploads)
– temp_outputs/  (transient directory for split page files)
d. PDF Processing Library
– pdfcpu (API calls inside handler)
e. ZIP Compressor
– Go’s archive/zip or custom packer within handler

##### Key architectural patterns and design principles
- Layered (Presentation → Business Logic → Storage)
- Single-responsibility handlers (one endpoint uploads, one splits)
- Temporary workspace for heavy I/O operations, cleaned up post-request
- Containerized build/deploy via Dockerfile + GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser (Client)" 
        Browser["Browser\n(renders templates)"]:::ui
    end

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        DockerSetup["Docker Setup\n(Dockerfile)"]:::infra

        subgraph "Gin Web Server" 
            direction TB
            Server["Gin Web Server\n(main.go)"]:::app
            Templates["HTML Templates\n(templates/)"]:::ui
            Dependencies["Dependency Management\n(go.mod, go.sum)"]:::infra
            PDFLib["pdfcpu\n(PDF Processing Library)"]:::lib
            ZIPMod["ZIP Compressor"]:::lib
            Uploads["uploads/"]:::storage
            TempOutputs["temp_outputs/"]:::storage
        end
    end

    %% CI Pipeline
    CI["GitHub Actions\n(CI Pipeline)"]:::infra

    %% Data Flows
    Browser -->|"GET /"| Server
    Browser -->|"POST /split"| Server
    Server -->|writes raw PDF| Uploads
    Server -->|writes split pages| TempOutputs
    Server -->|calls split API| PDFLib
    Server -->|calls archive/zip| ZIPMod
    Server -->|serves ZIP download| Browser
    Server -->|cleans temp files| TempOutputs
    Server -->|renders| Templates
    Server -->|uses dependencies| Dependencies
    CI -->|build/test| Server

    %% Click Events
    click Server "https://github.com/zalwan/pdf-splitter/blob/main/main.go"
    click Templates "https://github.com/zalwan/pdf-splitter/tree/main/templates/"
    click DockerSetup "https://github.com/zalwan/pdf-splitter/tree/main/Dockerfile"
    click CI "https://github.com/zalwan/pdf-splitter/blob/main/.github/workflows/go.yml"
    click Dependencies "https://github.com/zalwan/pdf-splitter/blob/main/go.mod"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px
    classDef lib fill:#98FB98,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
