# 18f/development-guide architecture

> Architecture diagram of the GitHub repository 18f/development-guide, 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/18f/development-guide
- Repository: https://github.com/18f/development-guide

## Overview

##### Main Components
- Content & Data Sources:
- _pages: Markdown files for individual content pages (e.g., about.md, apis.md, etc.).
- _data: YAML files for site constants and configuration (e.g., favicons, navigation, theme, etc.).
- Templating & Layout:
- _includes: HTML partials and components (for headers, footers, tag styles, etc.) that Jekyll uses to generate the final pages.
- _config.yml: Global configuration settings for Jekyll.
- Styling & Assets:
- _sass: SASS/SCSS files for styling.
- assets: JavaScript, CSS, and image assets.
- Build & Dependency Management:
- Dockerfile and docker-compose.yml: Container configurations for local development and build processes.
- Gemfile and Ruby-related version files (.ruby-version, .bundler-version): Manage Ruby dependencies.
- Package.json & package-lock.json: Manage JavaScript dependencies.
- Continuous Integration & Deployment:
- .circleci and .github directories: Configuration files for CircleCI and GitHub Actions workflows.
- Rakefile: Contains build and test tasks (for link checking, etc.) used in the CI pipeline.
- Documentation & Contribution:
- README.md, CONTRIBUTING.md, and doc/ directory: Guidelines on contributing and reference material related to best practices.

##### Relationships and Interactions
- Local Content Processing Flow:
- Markdown files in _pages are processed by Jekyll.
- The templates in _includes combine with the data in _data and settings from _config.yml to generate HTML pages.
- SASS files in _sass compile into CSS, which together with JS from assets create a cohesive frontend.
- Build and Deployment Workflow:
- Docker containers (as specified by Dockerfile and docker-compose.yml) provide an isolated environment for running Jekyll.
- CI/CD pipelines (CircleCI and GitHub Actions) are configured to build, test, and deploy the generated static site.
- Automated Rake tasks are used within the Docker container to test internal links and validate site integrity.
- Version Control and Collaboration:
- GitHub structure (with .github workflows and CONTRIBUTING.md) supports open collaboration, code reviews, and automated checks.

##### Architectural Patterns and Design Principles
- Static Site Generation: The project follows a standard static site architecture using Jekyll with clear separation between content (markdown), layout (templates), and styling.
- Containerized Development: The use of Docker ensures consistent development and build environments.
- CI/CD Integration: Automated workflows ensure site quality through link checking and testing.
- Modular Design: Splitting templates, Sass, and content into distinct directories makes the system extensible and maintainable.

##### Final Checklist
- Clear, legible labels for each directory component (Content, Templates, Assets, Build Environment, CI/CD).
- Annotations that include key technologies: Jekyll, Docker, Ruby, Node.js, CircleCI, and GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Layer"
        ContentMarkdown["Markdown Content (_pages)"]:::content
        DataFiles["Data Files (_data)"]:::content
    end

    subgraph "Presentation Layer"
        Templates["HTML Templates (_includes)"]:::presentation
        ConfigFile["Global Config (_config.yml)"]:::presentation
    end

    subgraph "Style & Assets Layer"
        Sass["Sass Stylesheets (_sass)"]:::assets
        Assets["Assets (assets)"]:::assets
    end

    subgraph "Build & Deployment Environment"
        Docker["Docker Configurations (Dockerfile, docker-compose.yml)"]:::build
        RubyDeps["Ruby Dependencies (Gemfile, Gemfile.lock, .ruby-version, .bundler-version)"]:::build
        JSDeps["JS Dependencies (package.json, package-lock.json)"]:::build
        CICD["CI/CD Pipelines (.circleci, .github)"]:::build
        Rakefile["Build Tasks (Rakefile)"]:::build
    end

    subgraph "Collaboration & Documentation"
        Documentation["Documentation (README.md, doc)"]:::collab
        Contrib["Contribution Guidelines (CONTRIBUTING.md)"]:::collab
    end

    GeneratedSite["Generated Site (HTML output)"]:::output

    %% Relationships: Content processing flow
    ContentMarkdown -->|"Jekyll_process"| Templates
    DataFiles -->|"Jekyll_process"| Templates
    ConfigFile -->|"Apply_Config"| Templates
    Templates -->|"Generate_HTML"| GeneratedSite
    Sass -->|"Compile_CSS"| GeneratedSite
    Assets -->|"Provide_JS/Assets"| GeneratedSite

    %% Build & Deployment interactions
    RubyDeps -->|"Support_Env"| Docker
    JSDeps -->|"Support_Env"| Docker
    Docker -->|"Run_Jekyll"| Templates
    CICD -->|"Deploy"| GeneratedSite
    Rakefile -->|"Test_Site"| GeneratedSite

    %% Collaboration influence
    Documentation -->|"Guide_CI"| CICD
    Contrib -->|"Guide_CI"| CICD
    Documentation -->|"Display_Info"| GeneratedSite

    %% Styling for layers
    classDef content fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef presentation fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef assets fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef build fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef collab fill:#F5EEF8,stroke:#9B59B6,stroke-width:2px;
    classDef output fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click events for Content & Data Sources
    click ContentMarkdown "https://github.com/18f/development-guide/tree/main/_pages"
    click DataFiles "https://github.com/18f/development-guide/tree/main/_data"

    %% Click events for Templating & Layout
    click Templates "https://github.com/18f/development-guide/tree/main/_includes"
    click ConfigFile "https://github.com/18f/development-guide/blob/main/_config.yml"

    %% Click events for Styling & Assets
    click Sass "https://github.com/18f/development-guide/tree/main/_sass"
    click Assets "https://github.com/18f/development-guide/tree/main/assets"

    %% Click events for Build & Dependency Management
    click Docker "https://github.com/18f/development-guide/tree/main/Dockerfile"
    click Docker "https://github.com/18f/development-guide/blob/main/docker-compose.yml"
    click RubyDeps "https://github.com/18f/development-guide/tree/main/Gemfile"
    click RubyDeps "https://github.com/18f/development-guide/blob/main/.ruby-version"
    click RubyDeps "https://github.com/18f/development-guide/blob/main/.bundler-version"
    click JSDeps "https://github.com/18f/development-guide/blob/main/package.json"
    click JSDeps "https://github.com/18f/development-guide/blob/main/package-lock.json"

    %% Click events for CI/CD and Build Tasks
    click CICD "https://github.com/18f/development-guide/blob/main/.circleci"
    click CICD "https://github.com/18f/development-guide/blob/main/.github"
    click Rakefile "https://github.com/18f/development-guide/tree/main/Rakefile"

    %% Click events for Documentation & Contribution
    click Documentation "https://github.com/18f/development-guide/blob/main/README.md"
    click Documentation "https://github.com/18f/development-guide/tree/main/doc"
    click Contrib "https://github.com/18f/development-guide/blob/main/CONTRIBUTING.md"
```
