# marciootavio/free-programming-books architecture

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

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

## Overview

##### Main Components
- Content Repository: At the core are the Markdown files organized in different directories (e.g., books, courses, casts, docs, more). This is the source of truth for the resource lists.
- Static Site Generator & Configuration: The presence of _config.yml indicates that the project uses a static site generator (probably Jekyll) to convert the Markdown files into a static website. This component is responsible for both the website that displays the resource list and any related pages (like guidelines, contributions, etc.).
- Dynamic Search Interface: The README describes a search service (accessible via https://ebookfoundation.github.io/free-programming-books-search/) which likely uses the content from the repository but transforms or indexes it to enable dynamic search functionality.
- GitHub Workflows and CI/CD: The .github directory contains workflows (for checking URLs, PR comments, linting, etc.) that automate tests, validations, and maybe deployment processes. These process automated contributions and quality checks.
- Community Contribution and External Services: The repository is maintained collaboratively with clear guidelines (in docs/CONTRIBUTING.md and docs/HOWTO.md) and uses GitHub issues/PRs to interact with external contributors.

##### Relationships and Interactions
- The Markdown files (in books, casts, courses, more) form the content layer that feeds both the static site generator and, indirectly, the dynamic search interface.
- External integrations (e.g., the badges that indicate forks, stars, issues, sponsorship) illustrate community interaction with the repository and should be represented as external data points.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project cleanly separates content storage (Markdown files), static content generation (site generator via _config.yml), dynamic functionality (search interface), and automated quality checks (GitHub workflows).
- Collaborative Open-Source Design: The use of extensive docs (CONTRIBUTING, CODE_OF_CONDUCT, HOWTO documents in multiple languages) demonstrates a focus on community contributions and multi-language support.
- Automation via CI/CD: GitHub workflows are set up to ensure quality and consistency of content before it becomes publicly available.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Repository (Markdown Files)"
        books["books directory"]:::content
        casts["casts directory"]:::content
        courses["courses directory"]:::content
        more["more directory"]:::content
        Repo["Content Aggregator"]:::content
        books --> Repo
        casts --> Repo
        courses --> Repo
        more --> Repo
    end

    ssg["Static Site Generator (Jekyll, _config.yml)"]:::ssg
    search["Dynamic Search Interface"]:::search
    workflows["GitHub CI/CD Workflows"]:::ci
    docs["Community Contribution Documentation (docs)"]:::docs

    %% Data Flow
    Repo -->|"builds"| ssg
    Repo -->|"feeds"| search
    docs -->|"triggers"| workflows
    workflows -->|"updates"| Repo
    workflows -->|"builds"| ssg

    %% Click Events
    click books "https://github.com/marciootavio/free-programming-books/tree/main/books"
    click casts "https://github.com/marciootavio/free-programming-books/tree/main/casts"
    click courses "https://github.com/marciootavio/free-programming-books/tree/main/courses"
    click more "https://github.com/marciootavio/free-programming-books/tree/main/more"
    click ssg "https://github.com/marciootavio/free-programming-books/blob/main/_config.yml"
    click workflows "https://github.com/marciootavio/free-programming-books/blob/main/.github"
    click docs "https://github.com/marciootavio/free-programming-books/tree/main/docs"

    %% Styles
    classDef content fill:#ffe0b3,stroke:#d35400,stroke-width:2px;
    classDef ssg fill:#d4efdf,stroke:#27ae60,stroke-width:2px;
    classDef search fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
    classDef ci fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef docs fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
```
