# ading2210/linuxpdf architecture

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

- Interactive diagram: https://gitdiagram.com/ading2210/linuxpdf
- Repository: https://github.com/ading2210/linuxpdf

## Overview

##### Project Type & Purpose
- This is a hybrid system that combines low-level C emulation (from TinyEMU) compiled to asm.js with a PDF file as the delivery format.
- Its core purpose is to simulate a Linux environment within a PDF by leveraging embedded Javascript in modern browsers.
- The project includes both build/integration scripts (build.sh, Python virtual environment, requirements.txt) and runtime assets (emulator code under “tinyemu”, HTML/JS in “web”, and supporting scripts).

##### Analysis of the File Structure
- Top-Level Components:
- .github/ (CI/CD workflows like deploy.yaml)
- Build/integration scripts (build.sh, embed_files.py, gen_pdf.py, etc.)
- The “tinyemu” directory contains all the C source code and related files for the RISC-V emulator; this is the core emulation engine.
- “web” directory has the static HTML/CSS files that likely support a demo or a test harness.
- Miscellaneous files like LICENSE, README.md, and project configuration files.
- Notice the multiple Makefiles in tinyemu (for JS and PDFjs targets) that indicate different build scripts for various output targets.
- The build chain includes integration with an old version of Emscripten (v1.39.20) to compile the C code to asm.js, which is the crucial runtime transformation.

##### Key Components
a. Build System and Toolchain:
- Python Virtual Environment & Dependencies (requirements.txt)
- Build script (build.sh) which downloads and uses Emscripten.
- The compilation process that takes the TinyEMU C source files and converts them into asm.js.
- Optional branches for 32-bit vs 64-bit builds (as mentioned in the README).
b. Core Emulator (TinyEMU):
- “tinyemu” module as the heart of the system.
- Split this into logical components: the CPU cores (RISC-V, x86), memory management (iomem), filesystem modules, network emulation (fs_net, slirp), and peripheral implementations (IDE, VGA, etc.).
- That these modules are compiled down to asm.js.
c. PDF/Javascript Environment:
- PDF file embedding: Show the PDF that integrates the compiled TinyEMU emulator.
- Browser’s PDF Engine: Explain that the browser (Chromium/Firefox) executes the Javascript contained in the PDF.
- Limited JS API set available in PDF viewers due to security restrictions.
d. User Interface:
- Output components: ASCII display where each text field corresponds to screen rows.
e. Runtime Flow:
- Data flow: User input (via browser UI elements) → Javascript in the PDF → Callbacks to the emulated emulator code → Emulated Linux kernel “boot” and response → ASCII screen updates back rendered within the PDF.
f. Deployment/Delivery:
- A web server (as per build instructions using python’s http.server) serves the generated PDF.
- CI/CD integration through GitHub Actions (via the .github/workflows directory).

##### Final Elements
- Build process: Code in “tinyemu” → Emscripten → asm.js files → included in PDF.
- Runtime flow: Browser loads PDF → Executes embedded JS → Invokes emulator → Processes user input and generates ASCII output.
- Deployment flow: Build artifacts → “out/“ directory → served via a web server.
- Build components (rectangles)

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Build System & Toolchain
    subgraph "Build System & Toolchain"
        BUILD_SH["build.sh"]
        REQ_TXT["requirements.txt"]
        EMBED_FILES["embed_files.py"]
        GEN_PDF["gen_pdf.py"]
        BUILD_PROC["Build Process"]
        EMSCRIPTEN["Emscripten v1.39.20"]
        
        BUILD_SH --> BUILD_PROC
        REQ_TXT --> BUILD_PROC
        EMBED_FILES --> BUILD_PROC
        GEN_PDF --> BUILD_PROC
        BUILD_PROC --> EMSCRIPTEN
    end

    %% TinyEMU Emulator
    subgraph "TinyEMU Emulator"
        TINYEMU_SRC["TinyEMU Emulator (C Source)"]
        
        %% Build Config for TinyEMU
        subgraph "Build Config"
            MAKEFILE["Makefile"]
            MAKEFILE_JS["Makefile.js"]
            MAKEFILE_PDFJS["Makefile.pdfjs"]
        end
        TINYEMU_SRC --> MAKEFILE
        TINYEMU_SRC --> MAKEFILE_JS
        TINYEMU_SRC --> MAKEFILE_PDFJS

        %% Internal Modules
        subgraph "Emulator Modules"
            CPU["CPU Cores (RISC-V/x86)"]
            MEMORY["Memory Management (iomem)"]
            FILESYS["Filesystem"]
            NETWORK["Network Emulation (fs_net,slirp)"]
            PERIPH["Peripherals (IDE,VGA)"]
        end
        TINYEMU_SRC --> CPU
        TINYEMU_SRC --> MEMORY
        TINYEMU_SRC --> FILESYS
        TINYEMU_SRC --> NETWORK
        TINYEMU_SRC --> PERIPH
    end

    %% Compilation to asm.js
    EMSCRIPTEN --> COMPILED["Compiled asm.js Emulator"]

    %% PDF/JS Execution Environment
    subgraph "PDF/JS Execution Environment"
        PDF_FILE["PDF File (with Embedded JS)"]
        PDFlinux["pdflinux.js"]
        FILE_TEMPLATE["file_template.js"]
        
        COMPILED --> PDF_FILE
        PDFlinux --> PDF_FILE
        FILE_TEMPLATE --> PDF_FILE
    end

    %% Runtime Interaction
    subgraph "Runtime Interaction"
        BROWSER["Browser PDF Viewer"]
        PDF_JS["PDF's Embedded JS"]
        USER_INPUT["User Input (Keyboard&Text Fields)"]
        ASCII_DISPLAY["ASCII Display"]
        
        PDF_FILE --> BROWSER
        BROWSER --> PDF_JS
        USER_INPUT --> PDF_JS
        PDF_JS --> COMPILED
        COMPILED --> ASCII_DISPLAY
    end

    %% Deployment / CI-CD Integration
    subgraph "Deployment/CI-CD"
        WEB_SERVER["Web Server (http.server)"]
        CI_CD["CI/CD (GitHub Actions)"]
        WEB_UI["Web UI (Demo)"]
        
        PDF_FILE -->|"DeployPDF"| WEB_SERVER
        CI_CD -->|"CI/CD_Pipeline"| WEB_SERVER
        WEB_SERVER --> WEB_UI
    end

    %% Styles
    classDef build fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef emulator fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef runtime fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef deployment fill:#F5CBA7,stroke:#B03A2E,stroke-width:2px;

    class BUILD_SH,REQ_TXT,EMBED_FILES,GEN_PDF,BUILD_PROC,EMSCRIPTEN build;
    class TINYEMU_SRC,MAKEFILE,MAKEFILE_JS,MAKEFILE_PDFJS,CPU,MEMORY,FILESYS,NETWORK,PERIPH emulator;
    class COMPILED,PDF_FILE,PDFlinux,FILE_TEMPLATE,BROWSER,PDF_JS,USER_INPUT,ASCII_DISPLAY runtime;
    class WEB_SERVER,CI_CD,WEB_UI deployment;

    %% Click Events
    click BUILD_SH "https://github.com/ading2210/linuxpdf/blob/main/build.sh"
    click REQ_TXT "https://github.com/ading2210/linuxpdf/blob/main/requirements.txt"
    click EMBED_FILES "https://github.com/ading2210/linuxpdf/blob/main/embed_files.py"
    click GEN_PDF "https://github.com/ading2210/linuxpdf/blob/main/gen_pdf.py"
    click TINYEMU_SRC "https://github.com/ading2210/linuxpdf/tree/main/tinyemu"
    click MAKEFILE "https://github.com/ading2210/linuxpdf/tree/main/tinyemu/Makefile"
    click MAKEFILE_JS "https://github.com/ading2210/linuxpdf/blob/main/tinyemu/Makefile.js"
    click MAKEFILE_PDFJS "https://github.com/ading2210/linuxpdf/blob/main/tinyemu/Makefile.pdfjs"
    click PDFlinux "https://github.com/ading2210/linuxpdf/blob/main/pdflinux.js"
    click FILE_TEMPLATE "https://github.com/ading2210/linuxpdf/blob/main/file_template.js"
    click WEB_UI "https://github.com/ading2210/linuxpdf/blob/main/web/index.html"
    click CI_CD "https://github.com/ading2210/linuxpdf/blob/main/.github/workflows/deploy.yaml"
```
