# usgpo/innovation architecture

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

- Interactive diagram: https://gitdiagram.com/usgpo/innovation
- Repository: https://github.com/usgpo/innovation

## Overview

##### Project type and purpose
- This is a Jekyll-based, GitHub Pages–hosted static website (“Innovation Hub”) that aggregates and presents legislative-branch technology activities, events, resources, and reports in markdown, PDF, and image formats.
- Its purpose is purely content delivery—no dynamic backend—focusing on collaboration, data standardization, and transparency.

##### File structure
- Top-level:
- Gemfile/Gemfile.lock, _config.yml → Ruby/Jekyll dependencies & configuration
- _data → YAML data (header, footer)
- _includes → reusable HTML snippets (e.g., hero component)
- _layouts → page templates (e.g., home.html)
- _pages, index.md → standalone markdown pages
- _events → event-specific markdown and PDFs
- assets → CSS (SCSS) and images
- resources, resources/reports → PDFs, PPTs, other assets
- All content and templates feed into Jekyll’s build engine, which compiles markdown + layouts + includes + data into a /_site folder of static HTML/CSS/JS.

##### README for additional insights
- Confirms iterative, non-partisan development via GitHub/GitHub Pages.
- No mention of external APIs or databases—purely static site.

a. Main components:
1. Developer Workstation
- Source files: markdown, YAML, SCSS, HTML snippets, PDFs
- Gemfile/Ruby environment with Jekyll & plugins
2. Version Control & CI (GitHub repo)
- Push → triggers build in GitHub Pages (or custom Actions)
3. Jekyll Build Engine
- Reads _config.yml, _data, _includes, _layouts, content directories, assets
- Compiles markdown → HTML, SCSS → CSS, inlines includes, injects data
- Produces static site in /_site
4. Hosting Layer (GitHub Pages + CDN)
- Serves /_site contents over HTTPS
5. End Users (Browsers)
- Request pages, CSS, images, PDFs

b. Relationships & data flows:
- Developer → Git push → GitHub repo
- GitHub Pages build (Jekyll) reads source → outputs /_site
- /_site served via GitHub Pages/CDN → Browser requests
- Browser displays static HTML, pulls CSS, images, PDFs

c. Architectural patterns & design principles:
- Static Site Generation (SSG)
- Separation of concerns: content (_pages, _events), presentation (layouts, includes), data (_data), assets (assets/css, assets/img)
- Convention over configuration (Jekyll)
- Asset pipeline: SCSS preprocessing bundled into Jekyll

d. Key technologies/frameworks:
- Ruby + Jekyll
- SCSS (via Jekyll’s Sass plugin)
- Git/GitHub/GitHub Pages
- Markdown, YAML

##### Summary of essential elements
- Role of Gemfile/Ruby environment.
- Build steps (markdown → HTML, SCSS → CSS).
- Keep it concise but comprehensive: no backend services, no databases—just SSG pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Workstation (Source Files)
    subgraph "Developer Workstation" 
        direction TB
        DEV["Developer Workstation"]:::source
        DF1["Gemfile & Gemfile.lock"]:::source
        DF2["README.md, LICENSE.md, CONTRIBUTING.md"]:::source
        DF3["_pages, _events, resources/reports content"]:::source
        DF4["assets/css/main.scss"]:::source
        DF5["assets/img/*"]:::source
    end

    %% Version Control & CI
    subgraph "GitHub Repository" 
        direction TB
        GIT["GitHub Repo"]:::source
        GR1[".gitignore"]:::source
        GR2["CODEOWNERS"]:::source
        GR3["CONTRIBUTING.md"]:::source
    end

    %% Jekyll Build Engine
    subgraph "Jekyll Build Engine" 
        direction TB
        BEEngine["Build Engine (Jekyll)"]:::build
        BE1["_config.yml"]:::build
        BE2["_data/"]:::build
        BE3["_includes/"]:::build
        BE4["_layouts/"]:::build
        BE5["_pages/"]:::build
        BE6["_events/"]:::build
        BE7["assets/css/main.scss"]:::build
        BE8["assets/img/"]:::build
        BE9["index.md"]:::build
    end

    %% Hosting Layer
    HC["GitHub Pages + CDN"]:::hosting

    %% End Users
    BR["End User Browser"]:::client

    %% Connections
    DEV -->|git push| GIT
    GIT -->|trigger build| BEEngine
    BEEngine -->|deploy site| HC
    BR -->|HTTP GET| HC
    HC -->|serves static site| BR

    %% Click Events
    click DF1 "https://github.com/usgpo/innovation/tree/master//Gemfile"
    click DF2 "https://github.com/usgpo/innovation/blob/master//README.md"
    click DF3 "https://github.com/usgpo/innovation/tree/master//_pages"
    click DF4 "https://github.com/usgpo/innovation/blob/master//assets/css/main.scss"
    click DF5 "https://github.com/usgpo/innovation/tree/master//assets/img"
    click GR1 "https://github.com/usgpo/innovation/blob/master//.gitignore"
    click GR2 "https://github.com/usgpo/innovation/tree/master//CODEOWNERS"
    click GR3 "https://github.com/usgpo/innovation/blob/master//CONTRIBUTING.md"
    click BE1 "https://github.com/usgpo/innovation/blob/master//_config.yml"
    click BE2 "https://github.com/usgpo/innovation/tree/master//_data"
    click BE3 "https://github.com/usgpo/innovation/tree/master//_includes"
    click BE4 "https://github.com/usgpo/innovation/tree/master//_layouts"
    click BE5 "https://github.com/usgpo/innovation/tree/master//_pages"
    click BE6 "https://github.com/usgpo/innovation/tree/master//_events"
    click BE7 "https://github.com/usgpo/innovation/blob/master//assets/css/main.scss"
    click BE8 "https://github.com/usgpo/innovation/tree/master//assets/img"
    click BE9 "https://github.com/usgpo/innovation/blob/master//index.md"

    %% Styles
    classDef source fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef build fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef hosting fill:#D4F1BE,stroke:#2E8B57,color:#2E8B57;
    classDef client fill:#E5D0FF,stroke:#6A5ACD,color:#6A5ACD;
```
