# harrischen/ddia architecture

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

- Interactive diagram: https://gitdiagram.com/harrischen/ddia
- Repository: https://github.com/harrischen/ddia

## Overview

This project is a static content repository that publishes a translated technical book (“设计数据密集型应用 – 中文翻译”) based on Martin Kleppmann’s work. The book’s content is maintained in Markdown files (organized by chapters, parts, and additional sections such as glossary and colophon), along with assets like images and HTML. There is also a dedicated “zh-tw” directory for the Traditional Chinese version of the content. In addition, the repository contains build and auxiliary components such as a Makefile and Python scripts (located in the “bin” directory with Pipfile definitions) that likely support content conversion or other automation tasks related to the static site generation with Gitbook and the Typora editor.

##### Main Architectural Components
- Content Repository – Represented by the collection of Markdown files (e.g., ch1.md to ch12.md, part-i.md, part-ii.md, part-iii.md, preface.md, etc.) that contain the actual book chapters, glossary, and related sections.
- Localization/Translation – A parallel structure (the “zh-tw” directory) is used for the Traditional Chinese version of the book. This indicates a localization component that mirrors the main content structure.
- Build & Automation – The Makefile, along with scripts in the “bin” directory (translate.py and zh-tw.py, plus Pipfile/Pipfile.lock), show that there is an automated process to build the website. These components handle tasks such as content conversion, static site generation, and possibly deploying to GitHub Pages.
- Presentation Layer – The index.html and the integration with Gitbook, Typora, and GitHub Pages (as highlighted in the README) form the front-end presentation of the book. This is how users finally interact with the content, via a web-based static site interface.

##### Relationships and Interactions
- The source Markdown files (both original content and localized versions) feed into the build system.
- The Makefile acts as the orchestrator which, when executed, triggers scripts (located in “bin”) and possibly Gitbook/TYPORA processes, converting the Markdown content into a static website format.
- The static website (HTML, CSS, and other assets) is then published on GitHub Pages for online viewing.
- The build system and translation scripts are dependent on Python packages (as indicated by Pipfile) so there is a dependency layer managing environment and libraries.

##### Architectural Patterns and Design Principles
- Layered Architecture – Separate layers for content (Markdown files), build/automation (Makefile & translation scripts), and presentation (static web pages).
- Separation of Localization – The project clearly separates content for Simplified and Traditional Chinese by having distinct directories.
- Automation & Reproducibility – Using Makefile and pipenv (Pipfile) helps automate the build and deployment process to ensure reproducible outputs, which is a best practice for content-heavy static sites.

##### Relevant Technologies and Utilities
- Gitbook – For structuring and rendering the book content.
- Typora – For editing Markdown content.
- GitHub Pages – For hosting and serving the final static website.
- Python – For the translation and conversion scripts integrated via the “bin” directory.
- Make – For automating the entire build and deployment process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Layer"
        A1("Markdown Files"):::content
        A2("Assets (img)"):::content
    end

    subgraph "Localization"
        L1("Traditional Chinese (zh-tw)"):::localization
    end
    
    subgraph "Build & Automation"
        B1("Makefile"):::automation
        B2("Bin Scripts"):::automation
        B3("Pipenv (Pipfile & Pipfile.lock)"):::automation
    end

    subgraph "External Tools"
        E1("Gitbook & Typora"):::external
    end

    subgraph "Presentation Layer"
        P1("Static Site (index.html, assets)"):::presentation
    end

    D1("GitHub Pages"):::deployment

    %% Data Flow
    A1 -->|"feed"| B1
    A2 -->|"assets"| B1
    L1 -->|"feed"| B1

    B1 -->|"orchestrates"| B2
    B1 -->|"orchestrates"| B3
    B1 -->|"triggers"| P1
    B1 -->|"uses"| E1

    P1 -->|"publishes"| D1

    %% Click Events
    click A1 "https://github.com/harrischen/ddia/blob/master/ch1.md"
    click A2 "https://github.com/harrischen/ddia/tree/master/img"
    click L1 "https://github.com/harrischen/ddia/tree/master/zh-tw"
    click B1 "https://github.com/harrischen/ddia/tree/master/Makefile"
    click B2 "https://github.com/harrischen/ddia/tree/master/bin"
    click B3 "https://github.com/harrischen/ddia/tree/master/Pipfile"
    click P1 "https://github.com/harrischen/ddia/blob/master/index.html"

    %% Styles
    classDef content fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef localization fill:#aed6f1,stroke:#1f618d,stroke-width:2px;
    classDef automation fill:#d5f5e3,stroke:#239b56,stroke-width:2px;
    classDef external fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef presentation fill:#d6eaf8,stroke:#2874a6,stroke-width:2px;
    classDef deployment fill:#f9ebea,stroke:#c0392b,stroke-width:2px;
```
