# urbaninstitute/nccs architecture

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

- Interactive diagram: https://gitdiagram.com/urbaninstitute/nccs
- Repository: https://github.com/urbaninstitute/nccs

## Overview

##### Main components
- Repository & Source Files – This includes all the site content: the Jekyll configuration (_config.yml), Rakefile commands, Gemfile (Ruby gems), the SCSS and JS assets under public, and static webpages like index.html.
- Content Collections – Separate folders are used for different types of content (e.g., _stories for Quarto-supported content, catalogs for data-driven pages, and resources/datasets). In addition, custom data and people lists reside in _data.
- Quarto Integration – The _quarto.yml file and the .qmd files inside _stories that are rendered through Quarto (typically in RStudio).
- Templating Components – Jekyll uses _layouts, _includes (with various partials for nav, footer, and specialised components), and even hidden pages.
- Build/Development Tools – The Rakefile contains commands (like “rake dev” and “rake build”) to help spin up local Jekyll servers; the Ruby environment (managed via bundler) is specified through the Gemfile.
- Deployment – Github Pages is used for deploying the site. The build process (triggered upon commit to the main branch) takes care of generating the final static assets.
- Assets & Static Files – SCSS files (with separate component styles) and JavaScript modules (with ESM) that are processed by Jekyll’s supported mechanisms.

##### Relationships and interactions
- The source repository (code, content, configuration) is the origin point. When a developer triggers a render (via RStudio for Quarto or using the rake tasks), the Quarto tool takes the .qmd files and generates Markdown.
- Next, Jekyll takes the Markdown from both Quarto and native .md files together with Liquid templates defined in _layouts and _includes. This processing includes the SCSS styles, JavaScript modules, and any static assets.
- The output is then a full set of HTML/CSS/JS files – the static website that is pushed live via Github Pages.
- The rake commands serve as shortcuts to build and run the site locally before the final commit.
- Data files (in _data and _datasets) support the dynamic insertion of content in various pages (like author information and datasets details).

##### Important architectural patterns and design principles
- The project emphasizes simplicity by avoiding a complex build system (no Webpack/Vite or additional node-based tools). Instead, it relies on Jekyll’s native support for SCSS and the browser’s ability to handle native ESM modules.
- There is a clear separation of concerns: content (in various collections and data files), templating (using Jekyll’s Liquid, layouts, and includes), and static asset processing.

##### Relevant technologies
- Jekyll (for static site generation and Liquid templating)
- Quarto (for authoring rich, dynamic content through .qmd files)
- SCSS/CSS and ESM JavaScript (for styling and interactive client-side features)
- Ruby (bundler, Gemfile, and rake tasks for build orchestration)
- Github Pages (for deployment)

- Use clear labels for each major component:
- “Repository Source (Code, Content, Config)”
- “Quarto Rendering Engine” (input: .qmd files & _quarto.yml; output: Markdown)
- “Jekyll Build System” (input: Markdown, Liquid templates, SCSS, JS)
- “Static Assets (HTML, CSS, JS)”
- “Deployment (Github Pages)”
- “Rake Commands / Ruby Environment” (shortcut for build & development)
- From repository to Quarto for content processing.
- From repository (layouts, includes, SCSS, JS) to Jekyll.
- From Jekyll to the generated static website.
- A different style for configuration/build scripts (Rakefile, Gemfile, _config.yml).
- Another style for static assets (SCSS, JavaScript, images).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository and Components
    R["Repository Source (Code, Content, Config)"]:::repo
    subgraph "Content Collections"
        S["Stories (_stories)"]:::content
        D["Data (_data)"]:::content
        DS["Datasets (_datasets)"]:::content
        C["Catalogs"]:::content
        RSC["Resources (_resources)"]:::content
    end
    subgraph "Templating Components"
        L["Layouts (_layouts)"]:::template
        I["Includes (_includes)"]:::template
    end
    subgraph "Assets & Static Files"
        SC["SCSS (public/scss)"]:::assets
        JS["JavaScript (public/js)"]:::assets
        F["Fonts (public/fonts)"]:::assets
        IMG["Images (public/img)"]:::assets
    end
    subgraph "Build/Development Tools"
        RF["Rakefile"]:::build
        GF["Gemfile"]:::build
        GLF["Gemfile.lock"]:::build
        RD["R Directory (R/)"]:::build
    end

    %% Main Build Pipeline
    R --> Q["Quarto Rendering Engine"]:::quarto
    Q --> J["Jekyll Build System"]:::jekyll
    J --> O["Static Site Output (HTML, CSS, JS)"]:::output
    O --> DEP["Deployment (Github Pages)"]:::deploy

    %% Integration Flow from Source Components to Build System
    S --> Q
    L --> J
    I --> J
    SC --> J
    JS --> J
    F --> J
    IMG --> J

    %% Build Tools trigger build process (dashed arrow)
    RF --- J
    GF --- J
    GLF --- J
    RD --- J

    %% Click Events
    click R "https://github.com/urbaninstitute/nccs/tree/main/Root"
    click S "https://github.com/urbaninstitute/nccs/tree/main/_stories"
    click D "https://github.com/urbaninstitute/nccs/tree/main/_data"
    click DS "https://github.com/urbaninstitute/nccs/tree/main/_datasets"
    click C "https://github.com/urbaninstitute/nccs/tree/main/catalogs"
    click RSC "https://github.com/urbaninstitute/nccs/tree/main/_resources"
    click Q "https://github.com/urbaninstitute/nccs/blob/main/_quarto.yml"
    click L "https://github.com/urbaninstitute/nccs/tree/main/_layouts"
    click I "https://github.com/urbaninstitute/nccs/tree/main/_includes"
    click RF "https://github.com/urbaninstitute/nccs/tree/main/Rakefile"
    click GF "https://github.com/urbaninstitute/nccs/tree/main/Gemfile"
    click GLF "https://github.com/urbaninstitute/nccs/blob/main/Gemfile.lock"
    click RD "https://github.com/urbaninstitute/nccs/tree/main/R/"

    %% Styles
    classDef repo fill:#f6d365,stroke:#d38312,stroke-width:2px;
    classDef content fill:#cdeac0,stroke:#77bfa3,stroke-width:2px;
    classDef template fill:#ffadad,stroke:#ff6363,stroke-width:2px;
    classDef assets fill:#c9c0bb,stroke:#8b8589,stroke-width:2px;
    classDef build fill:#d3c0eb,stroke:#a690d3,stroke-width:2px;
    classDef quarto fill:#a2d2ff,stroke:#07689f,stroke-width:2px;
    classDef jekyll fill:#ffc8dd,stroke:#ffafcc,stroke-width:2px;
    classDef output fill:#e0fbfc,stroke:#c1f2f2,stroke-width:2px;
    classDef deploy fill:#caffbf,stroke:#9bf6ff,stroke-width:2px;
```
