# abdelmalek123-ennani/free-programming-books architecture

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

- Interactive diagram: https://gitdiagram.com/abdelmalek123-ennani/free-programming-books
- Repository: https://github.com/abdelmalek123-ennani/free-programming-books

## Overview

##### Project type and purpose
- This is an open-source, static content site (built with Jekyll) that aggregates and publishes “free programming books” and related learning resources in many languages.
- It’s essentially a curated content repository with a build pipeline that generates a static website and deploys it to GitHub Pages.

##### File structure
- Top-level directories:
- books, casts, courses, more – the Markdown content for each category.
- docs – contributor docs and Code of Conduct.
- scripts – helper tooling (e.g., rtl_ltr_linter.py).
- .github – CI workflows and custom GitHub Actions.
- _config.yml, _includes – Jekyll config and layout snippets.
- Key config/build files:
- _config.yml – site configuration for Jekyll.
- .github/workflows/*.yml – CI steps: link checks, linting, stale PR management.
- scripts/rtl_ltr_linter.py – checks for RTL/LTR consistency in translated files.

##### Relevant README insights
- Mentions a separate “dynamic search site” (hosted at /free-programming-books-search/) but that code lives elsewhere.
- Emphasizes the static site for browseable content.
- Points to contribution workflows (docs/CONTRIBUTING.md, HOWTO.md, CODE_OF_CONDUCT.md).

##### Main components & their relationships
a. Components
1. Developer Workstation – clones/forks the repo, writes/edits Markdown or code.
2. GitHub Repo – stores all Markdown content, Jekyll templates, scripts, CI configs.
3. Continuous Integration (GitHub Actions) – runs:
- Awesomebot link checks, broken-URL detector
- RTL/LTR linter (scripts/rtl_ltr_linter.py)
- Spell/format/lint (fpb-lint)
- Stale-PR and issue management
4. Static Site Generator (Jekyll) – processes Markdown + templates → HTML/CSS/JS.
5. Deployment (GitHub Pages) – hosts the generated static site at ebookfoundation.github.io/free-programming-books/.
6. End-User Browser – fetches static assets, displays the site.
b. Data flow & interactions
- Developer pushes changes → GitHub Repo → triggers CI workflows → on success, Jekyll build runs → artifacts deployed to GitHub Pages → users retrieve the site in their browsers.
- Scripts (rtl_ltr_linter, link checkers) run as part of CI, but do not alter production; they block merges on errors.

##### Architectural patterns & design principles
- Static site generation (SSG) for ultimate simplicity, performance, and low maintenance.
- GitOps/CI→CD: the entire process from content change to deployment is automated via GitHub Actions.
- Separation of concerns:
- Content (books/, courses/, etc.)
- Presentation (Jekyll templates, includes)
- Tooling (CI configs, scripts)

##### Detailed elements to capture
- .github/workflows (link‐checker, lint, stale PR…)
- scripts/rtl_ltr_linter.py as part of CI
- _config.yml & _includes used by Jekyll
- content directories (books/, casts/, courses/, more/) feeding into Jekyll
- deployment to GitHub Pages
- user browsing experience

## Diagram (Mermaid)

```mermaid
flowchart TD
    Dev["Developer Workstation"]:::dev
    GitHubRepo["GitHub Repo"]:::repo

    subgraph "Content Repository"
        books["books/"]:::repo
        casts["casts/"]:::repo
        courses["courses/"]:::repo
        more["more/"]:::repo
    end

    subgraph "Contributor Documentation"
        doc1["docs/CONTRIBUTING.md"]:::repo
        doc2["docs/HOWTO.md"]:::repo
        doc3["docs/CODE_OF_CONDUCT.md"]:::repo
        docsall["docs/"]:::repo
    end

    subgraph "Config/Templates"
        cfg["_config.yml"]:::repo
        inc["_includes/"]:::repo
    end

    subgraph "CI Tooling"
        wf[".github/workflows/"]:::tool
        c1["check-urls.yml"]:::tool
        c2["fpb-lint.yml"]:::tool
        c3["rtl-ltr-linter.yml"]:::tool
        c4["stale.yml"]:::tool
        c5["detect-conflicting-prs.yml"]:::tool
        c6["comment-pr.yml"]:::tool
        c7["issues-pinner.yml"]:::tool
        action["awesomebot-gh-summary-action/action.yml"]:::tool
        scriptsub["scripts/rtl_ltr_linter.py"]:::tool
        scriptscfg["scripts/rtl_ltr_linter_config.yml"]:::tool
    end

    subgraph "Repository Root & Meta"
        README["README.md"]:::repo
        LIC["LICENSE"]:::repo
        GI[".gitignore"]:::repo
        EC[".editorconfig"]:::repo
        DBF[".github/dependabot.yml"]:::repo
    end

    CI["CI Workflows"]:::tool
    Jekyll["Jekyll Build"]:::tool
    Artifacts[(Build Artifacts)]:::storage
    Pages(("GitHub Pages")):::hosting
    Browser["End-User Browser"]:::user

    Dev -->|"git push"| GitHubRepo
    GitHubRepo -->|"trigger"| CI
    CI -->|"run build"| Jekyll
    Jekyll -->|"generate"| Artifacts
    Artifacts -->|"deploy"| Pages
    Pages -->|"HTTP GET"| Browser

    GitHubRepo --> books
    GitHubRepo --> casts
    GitHubRepo --> courses
    GitHubRepo --> more
    GitHubRepo --> doc1
    GitHubRepo --> doc2
    GitHubRepo --> doc3
    GitHubRepo --> docsall
    GitHubRepo --> cfg
    GitHubRepo --> inc
    GitHubRepo --> wf
    GitHubRepo --> action
    GitHubRepo --> scriptsub
    GitHubRepo --> scriptscfg
    GitHubRepo --> README
    GitHubRepo --> LIC
    GitHubRepo --> GI
    GitHubRepo --> EC
    GitHubRepo --> DBF

    wf --> c1
    wf --> c2
    wf --> c3
    wf --> c4
    wf --> c5
    wf --> c6
    wf --> c7

    CI --> wf
    CI --> action
    CI --> scriptsub

    click books "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/books/"
    click casts "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/casts/"
    click courses "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/courses/"
    click more "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/more/"
    click doc1 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/docs/CONTRIBUTING.md"
    click doc2 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/docs/HOWTO.md"
    click doc3 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/docs/CODE_OF_CONDUCT.md"
    click docsall "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/docs/"
    click cfg "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/_config.yml"
    click inc "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/_includes/"
    click wf "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/.github/workflows/"
    click c1 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/check-urls.yml"
    click c2 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/fpb-lint.yml"
    click c3 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/rtl-ltr-linter.yml"
    click c4 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/stale.yml"
    click c5 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/detect-conflicting-prs.yml"
    click c6 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/comment-pr.yml"
    click c7 "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/workflows/issues-pinner.yml"
    click action "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/actions/awesomebot-gh-summary-action/action.yml"
    click scriptsub "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/scripts/rtl_ltr_linter.py"
    click scriptscfg "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/scripts/rtl_ltr_linter_config.yml"
    click README "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/README.md"
    click LIC "https://github.com/abdelmalek123-ennani/free-programming-books/tree/main/LICENSE"
    click GI "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.gitignore"
    click EC "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.editorconfig"
    click DBF "https://github.com/abdelmalek123-ennani/free-programming-books/blob/main/.github/dependabot.yml"

    classDef repo fill:#bbf,stroke:#000
    classDef tool fill:#fea,stroke:#000
    classDef storage fill:#bfb,stroke:#000
    classDef hosting fill:#dcb,stroke:#000
    classDef dev fill:#ffd,stroke:#000
    classDef user fill:#ddd,stroke:#000
```
