# tmfg/digitraffic architecture

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

- Interactive diagram: https://gitdiagram.com/tmfg/digitraffic
- Repository: https://github.com/tmfg/digitraffic

## Overview

##### Project type and purpose
- This is a static site generator project (Jekyll) that produces a documentation/marketing site (Digitraffic pages).
- Source content lives in Markdown (`pages/`, `_posts/`, `_applications`, `_developments`), templates in `_layouts`/`_includes`, styles in `_scss`, scripts under `src/js` and `src/ts`, and the build is orchestrated by Ruby (Bundler/Gems) plus Node (pnpm, tsconfig.json).
- It is containerized (Dockerfile, build/run scripts) to produce a web-server exposing the static site on ports 3000/3001.

##### File structure for architectural components
- Content layer: Markdown files (`pages`, `_posts`, `_applications`, `_developments`).
- Presentation layer: Jekyll templates (`_layouts`, `_includes`), SCSS (`_scss` → compiled CSS), and JavaScript/TypeScript (`src/js`, `src/ts` → bundled JS).
- Build toolchain:
–  Ruby Bundler & Gems (`Gemfile`, `bundle update`)
–  Node/PNPM (`package.json`, `pnpm build-and-install`, `pnpm format`)
–  TypeScript compiler (`tsconfig.json`)
–  SCSS compiler
- Containerization & CI: Dockerfile + entrypoint scripts, CI workflows under `.github/workflows`.

##### README for technical stack
- Uses Jekyll (Ruby + Liquid templates)
- Uses PNPM for JS/TS asset build
- Build and run in Docker
- Live-reload on port 3000, admin/status on 3001

##### Main components & interactions
a. Component list:
–  Developer workstation (Editor + CLI)
–  GitHub repo & CI
–  Build orchestrator (pnpm + Bundler)
–  Jekyll engine
–  Asset compilers (SCSS, TypeScript)
–  Docker image
–  Containerized web server
–  End user browser

b. Relationships:
–  Developer → Git repo → CI triggers Docker build → runs Bundler & pnpm → produces static `_site`
–  Docker container serves `_site` on HTTP ports
–  Browser fetches HTML/CSS/JS from container

c. Architectural patterns/design principles:
–  Static site generation (SSG)
–  Separation of content (Markdown) from presentation (templates + styles)
–  Asset pipeline (SCSS & TS → bundled CSS & JS)
–  Container-based reproducible build & deploy

d. Key technologies:
–  Jekyll (Ruby + Liquid)
–  Bundler/Gems
–  SCSS → CSS
–  TypeScript/JavaScript → bundle.js
–  PNPM (fast JS/TS builds)
–  Docker

##### Final advice
–  Don’t overcomplicate—break the system into logical build vs. runtime vs. content zones
–  Capture essential tools (Bundler, PNPM, Jekyll, Docker) and flows (content→build→deploy→serve)

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Developer Environment"
    DevEditor["Editor<br/>(Markdown/SCSS/TS)"]:::dev -->|"git push"| GitHubRepo["GitHub Repo"]:::ci
    GitHubRepo -->|"CI triggers"| CI["GitHub Actions"]:::ci
  end

  subgraph "Content Layer"
    Pages["pages/"]:::content
    Posts["_posts/"]:::content
    Apps["_applications/"]:::content
    Devs["_developments/"]:::content
    Pages --> Jekyll
    Posts --> Jekyll
    Apps --> Jekyll
    Devs --> Jekyll
  end

  subgraph "Presentation Layer"
    Layouts["_layouts/"]:::templates
    Includes["_includes/"]:::templates
    SCSSsrc["_scss/"]:::styles
    SCSSmain["_scss/bundle.scss"]:::styles
    JSsrc["src/js/"]:::scripts
    TSsrc["src/ts/"]:::scripts
    Layouts --> Jekyll
    Includes --> Jekyll
    SCSSsrc -->|"compile"| CSS["css/style.css"]:::styles
    SCSSmain -->|"compile"| CSS
    JSsrc -->|"bundle"| JSbundle["js/bundle.js"]:::scripts
    TSsrc -->|"compile & bundle"| JSbundle
  end

  subgraph "Build Toolchain"
    Gemfile["Gemfile"]:::build
    GemfileLock["Gemfile.lock"]:::build
    ConfigYml["_config.yml"]:::build
    ConfigDev["_config_dev.yml"]:::build
    PackageJson["package.json"]:::build
    PnpmLock["pnpm-lock.yaml"]:::build
    TSConfig["tsconfig.json"]:::build
    Gemfile & GemfileLock & ConfigYml & ConfigDev --> Bundler["Bundler & Gems"]:::build
    PackageJson & PnpmLock & TSConfig --> PNPM["PNPM & tsc"]:::build
    Bundler --> Jekyll
    PNPM --> SCSSsrc
    PNPM --> TSsrc
    PNPM --> JSbundle
  end

  subgraph "CI / Local Build"
    CI -->|"runs"| BuildScripts["build-and-run-in-docker.sh<br/>build-docker-image.sh<br/>run-in-docker.sh"]:::build
    BuildScripts --> DockerBuild["Docker Build"]:::container
    DockerBuild --> DockerImage["Docker Image"]:::container
    Bundler --> Jekyll
    PNPM --> Jekyll
    Jekyll --> Site["_site (static)"]:::content
  end

  subgraph "Runtime Container"
    DockerImage -->|"entrypoint"| Entrypoint["docker-entrypoint.sh"]:::container
    Entrypoint --> Container["Docker Container"]:::container
    Container -->|"serves HTTP"| Site
    Container -->|"ports 3000/3001"| Ports["3000 & 3001"]:::container
  end

  subgraph "End Users"
    Browser["User Browser"]:::user
    Browser -->|"HTTP GET"| Container
  end

  %% Click Events
  click Pages "https://github.com/tmfg/digitraffic/tree/master/pages/"
  click Posts "https://github.com/tmfg/digitraffic/tree/master/_posts/"
  click Apps "https://github.com/tmfg/digitraffic/tree/master/_applications/"
  click Devs "https://github.com/tmfg/digitraffic/tree/master/_developments/"
  click Layouts "https://github.com/tmfg/digitraffic/tree/master/_layouts/"
  click Includes "https://github.com/tmfg/digitraffic/tree/master/_includes/"
  click SCSSsrc "https://github.com/tmfg/digitraffic/tree/master/_scss/"
  click SCSSmain "https://github.com/tmfg/digitraffic/blob/master/_scss/bundle.scss"
  click JSsrc "https://github.com/tmfg/digitraffic/tree/master/src/js/"
  click TSsrc "https://github.com/tmfg/digitraffic/tree/master/src/ts/"
  click CSS "https://github.com/tmfg/digitraffic/blob/master/css/style.css"
  click JSbundle "https://github.com/tmfg/digitraffic/blob/master/js/bundle.js"
  click Gemfile "https://github.com/tmfg/digitraffic/tree/master/Gemfile"
  click GemfileLock "https://github.com/tmfg/digitraffic/blob/master/Gemfile.lock"
  click ConfigYml "https://github.com/tmfg/digitraffic/blob/master/_config.yml"
  click ConfigDev "https://github.com/tmfg/digitraffic/blob/master/_config_dev.yml"
  click PackageJson "https://github.com/tmfg/digitraffic/blob/master/package.json"
  click PnpmLock "https://github.com/tmfg/digitraffic/blob/master/pnpm-lock.yaml"
  click TSConfig "https://github.com/tmfg/digitraffic/blob/master/tsconfig.json"
  click BuildScripts "https://github.com/tmfg/digitraffic/blob/master/build-and-run-in-docker.sh"
  click Entrypoint "https://github.com/tmfg/digitraffic/blob/master/docker-entrypoint.sh"
  click CI "https://github.com/tmfg/digitraffic/blob/master/.github/workflows/check-links.yml"

  %% Styles
  classDef dev fill:#f9f,stroke:#333,stroke-width:1px
  classDef ci fill:#cfc,stroke:#333,stroke-width:1px
  classDef content fill:#ccf,stroke:#333
  classDef templates fill:#fcf,stroke:#333
  classDef styles fill:#cff,stroke:#333
  classDef scripts fill:#ffc,stroke:#333
  classDef build fill:#fdd,stroke:#333
  classDef container fill:#eef,stroke:#333,stroke-dasharray: 5 5
  classDef user fill:#efe,stroke:#333
```
