# offa/android-foss architecture

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

- Interactive diagram: https://gitdiagram.com/offa/android-foss
- Repository: https://github.com/offa/android-foss

## Overview

##### Project type and purpose
- Type: A **static website / documentation site** (curated list of Free & Open Source Android apps)
- Purpose: Authors maintain a Markdown list (README.md) plus tutorials; CI checks, sorting scripts keep content tidy; output is a single `index.html` deployed to GitHub Pages.

##### Main components
a. Content layer
– README.md (the master list)
– tutorials/Install-Rooted-OTA.md
– supporting files (CONTRIBUTING.md, LICENSE, .markdownlint.json)
b. Scripts & tooling
– check.sh & check_manually.sh (shell scripts for content validation)
– ensure_sorted.py (Python script to enforce alphabetical order)
c. CI/CD pipelines (.github/workflows)
– ci.yml (runs lint, sorting checks, link tests)
– codeql.yml (security scanning)
d. Build output
– index.html (generated or hand-edited static site entry point)
e. Hosting & delivery
– GitHub Pages (serves `index.html`)
– End user web browser (visitors)

##### Relationships and data flow
1. Developer pushes commits to GitHub repo
2. GitHub Actions triggers:
- ci.yml → runs markdown lint → runs ensure_sorted.py → runs link checks
- codeql.yml → performs code-scanning
3. On success, build step (if any) generates/updates `index.html`
4. Deploy to GitHub Pages branch or `gh-pages` →
5. End users fetch `index.html` via browser
6. Optional: tutorials are also exposed via links from `index.html`

##### Architectural patterns & principles
– **Static-site generation**: no dynamic server components
– **CI-driven validation**: automated content quality and security checks
– **Single-source content**: Markdown as source of truth, HTML as artifact
– **Separation of concerns**: content vs tooling vs hosting

##### Technology & frameworks
– Markdown (content format)
– Python (ensure_sorted.py)
– Bash (check.sh)
– GitHub Actions (CI/CD)
– GitHub Pages (hosting)
– markdownlint (style enforcement via .markdownlint.json)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Source Content"
        direction TB
        README["README.md"]:::content
        Tutorials["tutorials/Install-Rooted-OTA.md"]:::content
        Contrib["CONTRIBUTING.md"]:::content
        License["LICENSE"]:::content
        MarkdownLint[".markdownlint.json"]:::content
    end

    subgraph "Validation & Sorting"
        direction TB
        SH1["check.sh"]:::tool
        SH2["check_manually.sh"]:::tool
        PY["ensure_sorted.py"]:::tool
    end

    subgraph "CI/CD Pipelines"
        direction TB
        CI[".github/workflows/ci.yml"]:::tool
        CodeQL[".github/workflows/codeql.yml"]:::tool
    end

    Build["Build Step\nGenerate index.html"]:::tool

    Index[("index.html")]:::artifact

    subgraph "Hosting & Delivery"
        direction TB
        Pages["GitHub Pages"]:::external
        Browser[/"End User Browser"/]:::external
    end

    Developer([Developer]):::external

    %% Relationships
    Developer --> CI
    Developer --> CodeQL
    CI --> SH1
    CI --> SH2
    CI --> PY
    CI --> Build
    CodeQL --> Build

    README --> SH1
    Tutorials --> SH1
    Contrib --> SH1
    License --> SH1
    MarkdownLint --> SH1

    SH1 --> CI
    SH2 --> CI
    PY --> CI

    README --> Build
    Tutorials --> Build
    Contrib --> Build
    License --> Build
    MarkdownLint --> Build

    Build --> Index
    Index --> Pages
    Pages --> Browser

    %% Click Events
    click README "https://github.com/offa/android-foss/blob/master/README.md"
    click Tutorials "https://github.com/offa/android-foss/blob/master/tutorials/Install-Rooted-OTA.md"
    click Contrib "https://github.com/offa/android-foss/blob/master/CONTRIBUTING.md"
    click License "https://github.com/offa/android-foss/tree/master/LICENSE"
    click MarkdownLint "https://github.com/offa/android-foss/blob/master/.markdownlint.json"
    click SH1 "https://github.com/offa/android-foss/blob/master/check.sh"
    click SH2 "https://github.com/offa/android-foss/blob/master/check_manually.sh"
    click PY "https://github.com/offa/android-foss/blob/master/ensure_sorted.py"
    click CI "https://github.com/offa/android-foss/blob/master/.github/workflows/ci.yml"
    click CodeQL "https://github.com/offa/android-foss/blob/master/.github/workflows/codeql.yml"
    click Index "https://github.com/offa/android-foss/blob/master/index.html"

    %% Styles
    classDef content fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef tool fill:#90EE90,stroke:#333,stroke-width:1px
    classDef artifact fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
