# continuous-architecture/toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/continuous-architecture/toolkit
- Repository: https://github.com/continuous-architecture/toolkit

## Overview

##### Project Type & Purpose
- This is an open-source documentation toolkit and static website project (“Continuous Architecture Toolkit”).
- It packages:
- A Jekyll-based landing site (`landing/`) with Asciidoctor-generated content and Tailwind CSS.
- A reusable style library (`stylesheet-factory/`) for building custom stylesheets (Sass → CSS).
- Supporting assets (presentations, meta-models, Miro files) under `Assets/`, `meta-model/`, `miro/`.
- Continuous Integration/Deployment via GitHub Actions pushes static site builds to an S3 bucket.

##### File Structure Analysis
- Top-level directories:
- `.github/` → CI workflows (`adoc-build-push_s3.yml`, `jekyll-build-push-S3-v2.yml`).
- `landing/` → Jekyll site source (Ruby, Markdown/Asciidoc content, Tailwind CSS config).
- `stylesheet-factory/` → Sass code, build scripts, Node/Ruby tooling to compile themes.
- `governance/`, `img/`, root README, LICENSE, etc.
- Key build tools/config:
- `Gemfile` → Jekyll + Asciidoctor gems
- `package.json`/`postcss.config.js`/`tailwind.config.js` → Node, PostCSS, Tailwind
- Sass entrypoints in `stylesheet-factory/sass/`

##### README Insights
- Local dev requires Ruby, NodeJS/NVM, Yarn, Bundler.
- Build steps:
- `bundle install`, `npm install`, `yarn add tailwindcss`
- `JEKYLL_ENV=production jekyll build | serve`
- Hosting on S3 via GitHub Actions.

a. Main Components
- Developer Workstation
- GitHub Repository & Actions (CI/CD)
- Build Tools:
- Ruby + Jekyll + Asciidoctor
- NodeJS + PostCSS + Tailwind + Sass
- Style Library Service (`stylesheet-factory`)
- Static Assets (images, PPTX, meta-models)
- AWS S3 Bucket (static hosting) + optional CDN (CloudFront)
- End-User Browser
b. Relationships & Interactions
1. Developer edits content in `landing/` or `stylesheet-factory/`.
2. Local build: Asciidoctor processes `.adoc` → HTML fragments; Sass compiles SCSS → CSS; Jekyll stitches Markdown + HTML + CSS → static site.
3. Push to GitHub → triggers CI workflows:
- Workflow “adoc-build-push_s3” (builds Asciidoc site → S3)
- Workflow “jekyll-build-push-S3-v2” (builds Jekyll site → S3)
4. S3 serves static files (optionally fronted by CloudFront).
5. End user requests site → Browser downloads HTML/CSS/JS/assets.
c. Architectural Patterns & Principles
- Static Site Generation (SSG)
- CI/CD via GitOps (GitHub Actions → S3)
- Modular styling: central Sass library reused across docs
- Content-driven: separation of content (Asciidoc/Markdown) and presentation (Jekyll layouts + Tailwind)
d. Key Technologies/Frameworks
- Jekyll, Asciidoctor, Ruby/Bundler
- NodeJS, PostCSS, Tailwind CSS, Yarn
- Sass/SCSS compiler in `stylesheet-factory`
- GitHub Actions (YAML workflows)
- AWS S3 (static hosting), CloudFront (optional CDN)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Side
    subgraph "Developer Machine" 
        direction TB
        Dev[("Developer Workstation")]:::developer
        Landing["Landing Site Source"]:::frontend
        StylesheetFactory["Style Library Source"]:::frontend
        StaticAssets["Static Assets Sources"]:::frontend
        Governance["Governance Docs"]:::frontend
        Images["Project Images"]:::frontend
        Metadata["Project Metadata"]:::frontend
    end

    %% Local Build Tools
    subgraph "Local Build" 
        direction TB
        Asciidoctor["Asciidoctor Process"]:::build
        SassCompile["Sass Compile"]:::build
        JekyllBuild["Jekyll Build"]:::build
    end

    %% GitHub Repo
    Repo["GitHub Repository"]:::developer

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        AdocWorkflow["Asciidoc Build & Push"]:::ci
        JekyllWorkflow["Jekyll Build & Push"]:::ci
    end

    %% Cloud Hosting
    subgraph "Cloud Hosting" 
        direction TB
        S3["AWS S3 Bucket"]:::cloud
        CloudFront["CloudFront CDN (optional)"]:::cloud
    end

    Browser[("End-User Browser")]:::client

    %% Connections
    Dev -->|edits content| Landing
    Dev -->|edits styles| StylesheetFactory
    Dev -->|updates assets| StaticAssets
    Dev -->|updates docs| Governance
    Dev -->|updates images| Images
    Dev -->|updates metadata| Metadata

    Landing -->|run `jekyll build`| JekyllBuild
    Landing -->|run `bundle exec jekyll`| Asciidoctor
    StylesheetFactory -->|run `sass compile`| SassCompile

    JekyllBuild --> Repo
    SassCompile --> Repo
    Asciidoctor --> Repo
    StaticAssets --> Repo
    Governance --> Repo
    Images --> Repo
    Metadata --> Repo

    Repo -->|push triggers| AdocWorkflow
    Repo -->|push triggers| JekyllWorkflow

    AdocWorkflow -->|deploy static site| S3
    JekyllWorkflow -->|deploy static site| S3

    S3 -->|serve files| CloudFront
    CloudFront -->|deliver content| Browser

    %% Click Events - GitHub CI/CD Workflows
    click AdocWorkflow "https://github.com/continuous-architecture/toolkit/blob/master/.github/workflows/adoc-build-push_s3.yml"
    click JekyllWorkflow "https://github.com/continuous-architecture/toolkit/blob/master/.github/workflows/jekyll-build-push-S3-v2.yml"

    %% Click Events - Landing Site
    click LandingConfig "https://github.com/continuous-architecture/toolkit/blob/master/landing/_config.yml"
    click LandingGemfile "https://github.com/continuous-architecture/toolkit/tree/master/landing/Gemfile"
    click LandingLayouts "https://github.com/continuous-architecture/toolkit/tree/master/landing/_layouts/"
    click LandingIncludes "https://github.com/continuous-architecture/toolkit/tree/master/landing/_includes/"
    click LandingContent "https://github.com/continuous-architecture/toolkit/tree/master/landing/content/"
    click LandingDocs "https://github.com/continuous-architecture/toolkit/tree/master/landing/docs/"
    click LandingAssets "https://github.com/continuous-architecture/toolkit/tree/master/landing/assets/"
    click LandingPostcss "https://github.com/continuous-architecture/toolkit/blob/master/landing/postcss.config.js"
    click LandingTailwind "https://github.com/continuous-architecture/toolkit/blob/master/landing/tailwind.config.js"
    click LandingPkg "https://github.com/continuous-architecture/toolkit/blob/master/landing/package.json"
    click LandingReadme "https://github.com/continuous-architecture/toolkit/blob/master/landing/readme.md"

    %% Click Events - Style Library Service
    click SFReadme "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/README.adoc"
    click SFGemfile "https://github.com/continuous-architecture/toolkit/tree/master/stylesheet-factory/Gemfile"
    click SFPkg "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/package.json"
    click SFBuildScript "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/build-stylesheet.sh"
    click SFConfig "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/config.rb"
    click SFSass "https://github.com/continuous-architecture/toolkit/tree/master/stylesheet-factory/sass/"
    click SFStylesheets "https://github.com/continuous-architecture/toolkit/tree/master/stylesheet-factory/stylesheets/"
    click SFLib "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/lib/functions.rb"

    %% Click Events - Sass Entrypoints
    click SASS1 "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/sass/asciidoctor.scss"
    click SASS2 "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/sass/continuous-architecture.scss"
    click SASSSettings "https://github.com/continuous-architecture/toolkit/blob/master/stylesheet-factory/sass/settings/_settings.scss.dist"

    %% Click Events - Static Assets
    click Assets "https://github.com/continuous-architecture/toolkit/tree/master/Assets/"
    click MetaModel "https://github.com/continuous-architecture/toolkit/tree/master/meta-model/"
    click Miro "https://github.com/continuous-architecture/toolkit/tree/master/miro/"

    %% Click Events - Governance Docs
    click GovContrib "https://github.com/continuous-architecture/toolkit/blob/master/governance/contributing.md"
    click GovGov "https://github.com/continuous-architecture/toolkit/blob/master/governance/governance.md"
    click GovMaint "https://github.com/continuous-architecture/toolkit/blob/master/governance/maintainer-guide.md"

    %% Click Events - Images
    click ImgRoot "https://github.com/continuous-architecture/toolkit/tree/master/img/"
    click GovImg "https://github.com/continuous-architecture/toolkit/tree/master/governance/img/"
    click LandingImgs "https://github.com/continuous-architecture/toolkit/tree/master/landing/assets/imgs/"

    %% Click Events - Root Metadata
    click RootReadme "https://github.com/continuous-architecture/toolkit/blob/master/README.md"
    click License "https://github.com/continuous-architecture/toolkit/tree/master/LICENSE"
    click Changelog "https://github.com/continuous-architecture/toolkit/blob/master/Changelog.md"
    click Gitignore "https://github.com/continuous-architecture/toolkit/blob/master/.gitignore"
    click Contributors "https://github.com/continuous-architecture/toolkit/blob/master/contributors-email-address.txt"

    %% Styles
    classDef developer fill:#cfe2f3,stroke:#6fa8dc,stroke-width:1px
    classDef frontend fill:#c9daf8,stroke:#6d9eeb,stroke-width:1px
    classDef build fill:#f9cb9c,stroke:#e69138,stroke-width:1px
    classDef ci fill:#d9ead3,stroke:#93c47d,stroke-width:1px
    classDef cloud fill:#d9d9d9,stroke:#999999,stroke-width:1px
    classDef client fill:#f4cccc,stroke:#e06666,stroke-width:1px
```
