# premai-io/state-of-open-source-ai architecture

> Architecture diagram of the GitHub repository premai-io/state-of-open-source-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/premai-io/state-of-open-source-ai
- Repository: https://github.com/premai-io/state-of-open-source-ai

## Overview

##### Main Components
a. **Content Sources**
- Markdown files (`.md`): index.md, sdk.md, models.md, etc.
- Bibliography/References (`references.bib`, references.md).
b. **Build Logic (Python Layer)**
- badges.py, bibliography.py, committers.py: generate badges, bibliography, committers list, etc.
c. **Theme & Templates**
- prem_theme/ (Python package for theme)
- `_templates/page.html`
- `_config.yml` & `_toc.yml` (configuration for SSG)
d. **Static Assets**
- `_static/` (CSS, JS files)
- assets/ (additional images, if any)
e. **Static-Site Generator**
- MkDocs or a Jekyll-style SSG invoked via a build script (not explicitly named)
f. **Continuous Integration & Deployment**
- GitHub workflows (`.github/workflows/pages.yml`)
- GitHub Pages (serving the `gh-pages` branch)
g. **Developer Environment**
- `.devcontainer.json`, `.vscode/` and `.idea/` (VS Code/IDE configs)

##### Relationships & Data Flow
1. **Authored Content → Python Build Scripts**
- Raw `.md` and `.bib` files feed into badges.py, bibliography.py, committers.py to produce enriched markdown or JSON.
2. **Enriched Markdown + SSG Config + Theme & Templates**
- The SSG reads `_config.yml`, `_toc.yml`, the prem_theme package, templates, static assets, and the processed markdown to render HTML.
3. **HTML Output → GitHub Pages Deployment**
- A GitHub Action (`pages.yml`) triggers on `push` to main, runs the build pipeline (install Python deps from requirements.txt, run scripts, run SSG), and publishes the generated site to GitHub Pages.
4. **End-User**
- Browsers fetch static assets and HTML from the GitHub Pages CDN under the custom CNAME.

##### Architectural Patterns & Design Principles
- **Separation of Concerns**:
- Content (Markdown) vs. Presentation (Templates/CSS) vs. Logic (Python scripts) vs. Deployment (CI).
- **Infrastructure as Code**:
- `.devcontainer.json`, `.github/workflows` encode environment & deployment.
- **Modular Theme**:
- `prem_theme` Python package can be reused or swapped.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        DevContainer[".devcontainer.json"]:::dev
        VSCode[".vscode/"]:::dev
        IDEA[".idea/"]:::dev
    end

    %% Git Repository
    subgraph "Git Repository"
        direction TB
        ContentSources["Markdown Files (.md)"]:::repo
        BibSources["Bibliography (references.bib, references.md)"]:::repo
        BuildLogic["Python Build Scripts"]:::python
        ThemeTemplates["Theme & Templates"]:::ssg
        StaticAssets["Static Assets (_static/, assets/)"]:::assets
        ConfigFiles["Config & Dependencies"]:::repo
    end

    %% CI/CD Pipeline
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        Workflow["pages.yml"]:::ci
        ActionTrigger["GitHub Action"]:::ci
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        InstallDeps["pip install -r requirements.txt"]:::build
        RunScripts["Run badges.py, bibliography.py, committers.py"]:::build
        RunSSG["SSG Compile (_config.yml, _toc.yml, templates, theme)"]:::build
    end

    %% Hosting
    subgraph "Hosting"
        direction TB
        PagesHost["GitHub Pages (gh-pages)"]:::hosting
        CNAMERecord["CNAME"]:::hosting
    end

    %% End-User
    subgraph "End-User"
        direction TB
        Browser["Browser"]:::user
    end

    %% Flows
    DevContainer -->|uses| VSCode
    VSCode -->|edits| ContentSources
    IDEA -->|edits| ContentSources
    ContentSources -->|includes| BibSources
    ContentSources -->|trigger push| Workflow
    BibSources -->|trigger push| Workflow
    BuildLogic -.->|in repo| Workflow
    ThemeTemplates -.->|in repo| Workflow
    StaticAssets -.->|in repo| Workflow
    ConfigFiles -.->|in repo| Workflow

    Workflow -->|on push to main| ActionTrigger
    ActionTrigger -->|runs| InstallDeps
    InstallDeps -->|install| RunScripts
    RunScripts -->|produce enriched markdown| RunSSG
    RunSSG -->|generate HTML + assets| PagesHost
    CNAMERecord -.-> PagesHost
    PagesHost -->|serves| Browser

    %% Click Events
    click DevContainer "https://github.com/premai-io/state-of-open-source-ai/blob/main/.devcontainer.json"
    click VSCode "https://github.com/premai-io/state-of-open-source-ai/tree/main/.vscode/"
    click IDEA "https://github.com/premai-io/state-of-open-source-ai/tree/main/.idea/"
    click ContentSources "https://github.com/premai-io/state-of-open-source-ai/blob/main/."
    click BibSources "https://github.com/premai-io/state-of-open-source-ai/blob/main/references.bib"
    click BuildLogic "https://github.com/premai-io/state-of-open-source-ai/blob/main/badges.py"
    click BuildLogic "https://github.com/premai-io/state-of-open-source-ai/blob/main/bibliography.py"
    click BuildLogic "https://github.com/premai-io/state-of-open-source-ai/blob/main/committers.py"
    click ThemeTemplates "https://github.com/premai-io/state-of-open-source-ai/tree/main/prem_theme/"
    click ThemeTemplates "https://github.com/premai-io/state-of-open-source-ai/blob/main/_templates/page.html"
    click ThemeTemplates "https://github.com/premai-io/state-of-open-source-ai/blob/main/_config.yml"
    click ThemeTemplates "https://github.com/premai-io/state-of-open-source-ai/blob/main/_toc.yml"
    click StaticAssets "https://github.com/premai-io/state-of-open-source-ai/tree/main/_static/"
    click StaticAssets "https://github.com/premai-io/state-of-open-source-ai/tree/main/assets/"
    click InstallDeps "https://github.com/premai-io/state-of-open-source-ai/blob/main/requirements.txt"
    click Workflow "https://github.com/premai-io/state-of-open-source-ai/blob/main/.github/workflows/pages.yml"
    click CNAMERecord "https://github.com/premai-io/state-of-open-source-ai/tree/main/CNAME"

    %% Styles
    classDef dev fill:#e3f2fd,stroke:#90caf9,color:#0d47a1
    classDef repo fill:#f1f8e9,stroke:#aed581,color:#33691e
    classDef python fill:#e8f5e9,stroke:#66bb6a,color:#1b5e20
    classDef ssg fill:#e3f2fd,stroke:#42a5f5,color:#0d47a1
    classDef assets fill:#fff3e0,stroke:#ffb74d,color:#e65100
    classDef ci fill:#fff8e1,stroke:#ffe082,color:#ff6f00
    classDef build fill:#f3e5f5,stroke:#ba68c8,color:#4a148c
    classDef hosting fill:#ede7f6,stroke:#9575cd,color:#311b92
    classDef user fill:#e0f7fa,stroke:#4dd0e1,color:#006064
```
