# sara-sabr/itstrategy architecture

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

- Interactive diagram: https://gitdiagram.com/sara-sabr/itstrategy
- Repository: https://github.com/sara-sabr/itstrategy

## Overview

##### Project type and purpose
- This is a documentation‐driven, static web site repository built with Jekyll (Ruby/GitHub Pages) and supplemented with a few Node.js scripts for link-checking and content validation.
- Its purpose is to manage and publish “IT Strategy” content: markdown pages (multi-language), blog posts, presentations, data tables, and static assets.

##### File structure
- Top‐level directories of interest:
- `_layouts`, `_includes`, `_pages`, `_posts`: Jekyll templating and content structure
- `assets`: CSS, JS, images, fonts, downloadable files
- `_data`: YAML data for tables, internationalization
- Root scripts: `get-link-from-path.js`, `list-links.js`, `validate-broken-link.js`
- CI config: `.github/workflows/*`, plus `.markdown-link-check.json`, `.markdownlint.json`
- Jekyll config: `Gemfile`, `_config.yml`

##### README insights
- CI tests are in place (Node.js CI workflow, link checks)
- Content is authored in markdown and then published in a generated HTML site via GitHub Pages
- Multi-language support (English/French) via separate directories and YAML i18n files

##### Main components
a. Source Code Repository (GitHub)
- Branches, PRs, content & code lives here
b. Developer Workstation
- Jekyll + Ruby + Node.js environment for local preview
c. Continuous Integration (GitHub Actions)
- Linting: markdownlint, style checks
- Link checking: markdown-link-check & custom Node.js scripts
- Test suite: file‐based validations
d. Build Engine (Jekyll & Node.js scripts)
- Reads: `_config.yml`, `_data/*.yml`, `_includes`, `_layouts`
- Processes: `_pages`, `_posts`, `drawio` (via export), `presentations`, `wip-tec`
- Outputs static HTML/CSS/JS into a build folder (e.g., `/docs` or `_site`)
e. Static Assets
- `assets/css`, `assets/js`, `assets/images`, `assets/files` served alongside HTML
f. Deployment Target (GitHub Pages)
- Serves the static site over HTTPS
- Optionally backed by a CDN
g. Consumers
- Web browsers, translators (French/English), external stakeholders

##### Relationships & Interactions
- Developer pushes markdown/JS/Ruby code to GitHub → triggers CI workflows
- CI workflows run linters → custom Node.js link validators → Jekyll build → artifact deployment
- Artifacts (HTML + assets) are published to GitHub Pages → public website

##### Architectural patterns/design principles
- Static Site Generation (SSG) pattern: decoupling of content authoring and runtime server
- Convention over Configuration via Jekyll directory naming
- CI/CD pipeline enforcing quality gates before deployment
- Separation of concerns: content (`_pages`, `_posts`) vs. presentation (`_layouts`, `_includes`) vs. data (`_data`) vs. assets

##### Technologies & frameworks
- Ruby/Jekyll for SSG
- GitHub Actions for CI/CD
- Node.js scripts (`list-links.js`, `validate-broken-link.js`)
- Markdown, YAML, SCSS, vanilla JavaScript

##### Elements
- Developer → GitHub → CI → Build → Deploy → Browser
- Content sources (green)
- Build tools & scripts (orange)
- Templates & config (blue)
- External services (purple)
- Output/hosting (grey)

##### Final checklist
- How `_data` feeds into templates in the build process
- CI stages in sequential order (lint → link-check → build → deploy)
- Clearly distinguish between local preview (developer workstation) and CI environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Repo
    Dev["Developer Workstation"]:::external
    GitHub["Source Code Repository (GitHub)"]:::external

    %% Content Sources Layer
    subgraph "Content Sources" 
        direction TB
        Pages["_pages/"]:::content
        Posts["_posts/"]:::content
        Data["_data/"]:::content
        Drawio["drawio/"]:::content
        Coggle["coggle/"]:::content
        Presentations["presentations/"]:::content
        WIP["wip-tec/"]:::content
    end

    %% Templates & Configuration Layer
    subgraph "Templates & Configuration"
        direction TB
        Layouts["_layouts/"]:::templates
        Includes["_includes/"]:::templates
        ConfigYml["_config.yml"]:::templates
        Gemfile["Gemfile"]:::templates
    end

    %% Build Engine & Scripts Layer
    subgraph "Build Engine & Scripts"
        direction TB
        Jekyll["Jekyll Engine"]:::build
        Scripts["Node.js Scripts"]:::build
        PackageJson["package.json"]:::build
        PackageLock["package-lock.json"]:::build
    end

    %% CI Pipeline Layer
    subgraph "Continuous Integration (GitHub Actions)"
        direction TB
        WorkflowPages[".github/workflows/github-pages.yml"]:::ci
        WorkflowLink[".github/workflows/link-check.yml"]:::ci
        WorkflowNode[".github/workflows/node.js.yml"]:::ci
        MDLinkCheck[".markdown-link-check.json"]:::ci
        MarkdownLint[".markdownlint.json"]:::ci
    end

    %% Output Layer
    subgraph "Output (Static Site)"
        direction TB
        Site["_site/ or docs/"]:::output
        Export["output/"]:::output
    end

    %% Deployment & Consumers
    Deploy["GitHub Pages (with CDN)"]:::external
    Browser["Web Browsers / Translators"]:::external

    %% Connections
    Dev -->|push| GitHub
    GitHub -->|trigger CI| WorkflowPages
    WorkflowPages --> WorkflowLink --> WorkflowNode --> MDLinkCheck --> MarkdownLint
    MarkdownLint -->|run build| Jekyll
    WorkflowNode -->|run scripts| Scripts
    Jekyll -->|reads| Pages & Posts & Data & Drawio & Coggle & Presentations & WIP
    Jekyll -->|uses| Layouts & Includes & ConfigYml & Gemfile
    Scripts -->|validate links| Pages & Posts
    PackageJson & PackageLock --> Scripts
    Jekyll -->|outputs| Site
    Scripts -->|exports reports| Export
    Site -->|deploy| Deploy
    Deploy -->|serve| Browser

    Dev -->|local preview| Jekyll

    %% Click Events - Content Sources
    click Pages "https://github.com/sara-sabr/itstrategy/tree/main/_pages/"
    click Posts "https://github.com/sara-sabr/itstrategy/tree/main/_posts/"
    click Data "https://github.com/sara-sabr/itstrategy/tree/main/_data/"
    click Drawio "https://github.com/sara-sabr/itstrategy/tree/main/drawio/"
    click Coggle "https://github.com/sara-sabr/itstrategy/tree/main/coggle/"
    click Presentations "https://github.com/sara-sabr/itstrategy/tree/main/presentations/"
    click WIP "https://github.com/sara-sabr/itstrategy/tree/main/wip-tec/"

    %% Click Events - Templates & Configuration
    click Layouts "https://github.com/sara-sabr/itstrategy/tree/main/_layouts/"
    click Includes "https://github.com/sara-sabr/itstrategy/tree/main/_includes/"
    click ConfigYml "https://github.com/sara-sabr/itstrategy/blob/main/_config.yml"
    click Gemfile "https://github.com/sara-sabr/itstrategy/tree/main/Gemfile"

    %% Click Events - Build Engine & Scripts
    click Jekyll "https://github.com/sara-sabr/itstrategy/tree/main/Gemfile"
    click Scripts "https://github.com/sara-sabr/itstrategy/blob/main/get-link-from-path.js"
    click PackageJson "https://github.com/sara-sabr/itstrategy/blob/main/package.json"
    click PackageLock "https://github.com/sara-sabr/itstrategy/blob/main/package-lock.json"

    %% Click Events - CI Pipeline
    click WorkflowPages "https://github.com/sara-sabr/itstrategy/blob/main/.github/workflows/github-pages.yml"
    click WorkflowLink "https://github.com/sara-sabr/itstrategy/blob/main/.github/workflows/link-check.yml"
    click WorkflowNode "https://github.com/sara-sabr/itstrategy/blob/main/.github/workflows/node.js.yml"
    click MDLinkCheck "https://github.com/sara-sabr/itstrategy/blob/main/.markdown-link-check.json"
    click MarkdownLint "https://github.com/sara-sabr/itstrategy/blob/main/.markdownlint.json"

    %% Styles
    classDef content fill:#e0f2e9,stroke:#009a66,color:#005946
    classDef templates fill:#e8f0fd,stroke:#3367d6,color:#1a237e
    classDef build fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef ci fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
    classDef output fill:#eceff1,stroke:#607d8b,color:#263238
    classDef external fill:#f5f5f5,stroke:#757575,color:#212121,stroke-dasharray: 5 5
```
