# gagnieray/opale architecture

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

- Interactive diagram: https://gitdiagram.com/gagnieray/opale
- Repository: https://github.com/gagnieray/opale

## Overview

**Opale is not an “application” with services**; it’s a **Redmine 6.x theme** (static assets) with a **Node/Grunt-based build toolchain** that compiles **SCSS → CSS** and ships assets that are then served by **Redmine (Rails) + its asset pipeline** to the browser.

So the “system design” is primarily:
- **Source asset architecture** (how SCSS is organized and composed)
- **Build pipeline** (watch/lint/build via Node/Grunt + git hooks + CI)
- **Runtime integration** (how Redmine consumes the theme CSS; how production assets:precompile impacts it)
- **Plugin styling overlay** (Redmine Backlogs plugin stylesheet overrides)

##### Runtime view (Redmine → theme assets → browser)
2) **Build/Delivery view** (developer changes SCSS → build outputs → deployed theme → Redmine precompile)

##### Theme runtime deliverables (what Redmine ultimately uses)
- `stylesheets/application.css`
**Primary compiled output** that Redmine serves as theme CSS.
- `webfonts/`
Font assets referenced by CSS.
- `plugins/redmine_backlogs/*.css` and `plugins/redmine_backlogs/jquery/*.css`
**Prebuilt/packaged CSS overrides** specifically for the Redmine Backlogs plugin.

##### Source (what engineers actually edit)
- `src/sass/application.scss`
**Root entrypoint** SCSS file (the “main module”).
- `src/sass/_variables.scss`, `_mixins.scss`, `_functions.scss`
Global theming primitives.
- `src/sass/components/*`
Componentized styling; this is effectively your “internal modules”.
- `src/sass/functions/*`, `src/sass/mixins/*`
Reusable SCSS helpers.
- `src/sass/plugins/redmine_backlogs/*`
SCSS sources for plugin-specific styling (mirrors the packaged CSS in `/plugins/...`).
- `src/sass/vendor/`

##### Build / lint / automation (pipeline nodes)
- `Gruntfile.js`
- `package.json`, `package-lock.json`
Node dependencies + scripts (`watch`, `lint`, `build` per README).
- `.stylelintrc.js`
SCSS/CSS lint rules (Standard SCSS + SMACSS property ordering).
- `.eslintrc.js`
JS lint rules (even if JS is minimal, it’s part of repo tooling).
- `.husky/pre-commit`, `.lintstagedrc.js`
Local pre-commit enforcement: lint/build before commits.
- `.github/workflows/lint.yml`
CI pipeline step that validates style quality on PRs/commits.

- `README.md`, `CONTRIBUTING.md`, `LICENSE`, `AUTHORS.md`
- `screenshots/` (not architectural, but confirms UI theme nature)

##### Runtime (C4 “Context/Container” style)
**Actors**
- **End User (Browser)**
- **Admin/Developer** (selects theme in Redmine admin UI)

**System containers**
- **Redmine 6.x (Rails app)**
Serves HTML + links theme CSS + runs asset precompilation in production.
- **Opale theme (this repo contents deployed under `{redmine}/themes/opale`)**
Supplies `stylesheets/application.css`, fonts, and optional plugin styles.
- **Optional: Redmine Backlogs plugin**
Has its own asset directory; Opale provides overrides that must be copied.

- Browser → Redmine: HTTP requests (HTML/CSS)
- Redmine → Theme assets: resolves theme CSS path, serves `application.css` (+ fonts)
- (If Backlogs installed) Redmine → Backlogs plugin assets: serves plugin CSS
- Theme/Backlogs CSS → Browser rendering: styling applied

- Redmine production often requires: `bundle exec rake assets:precompile RAILS_ENV=production`
That missing/broken styling can be due to assets not precompiled or server not restarted.

##### Build/Customization pipeline (this is the “architecture” that matters most here)
**Build actors / environments**
- Developer workstation (Node.js + npm installed)
- Git (Husky hooks)
- GitHub Actions CI
- Redmine server (production) running rake tasks

**Core pipeline components**
- SCSS sources in `src/sass/**`
- Grunt build (via `Gruntfile.js`)
- Linters: Stylelint (SCSS/CSS), ESLint (JS tooling)
- Output artifacts: `stylesheets/application.css` and plugin CSS under `plugins/redmine_backlogs/**`
- Deployment target: `{redmine}/themes/opale`

##### Developer edits `src/sass/`
→ `npm run watch` (Grunt watch)
→ Sass compilation
→ emits `stylesheets/application.css` (and potentially plugin-related outputs depending on tasks)
##### Pre-commit gate: staged files
→ Husky + lint-staged
→ run lint/build
→ allows commit only if checks pass
##### Remote gate: push/PR
→ GitHub Actions `lint.yml`
→ runs linters (and possibly build)
→ status required for merging (if configured)
##### Deploy to Redmine
→ theme folder under `{redmine}/themes/opale`
→ in production: run `rake assets:precompile` or restart server
→ browser sees updated styling

- Optional `src/sass/_custom-variables.scss` (gitignored)
imported early in `application.scss`
uses `@use 'variables' with (...)` to override `!default` values.
This as: **custom variables → application.scss → compiled CSS**.

- Source of truth in repo: `opale/plugins/redmine_backlogs/**`
- Manual install step: copy to
`{redmine}/plugins/redmine_backlogs/assets/stylesheets`
- Restart Redmine

##### Architectural patterns / principles to highlight
- **Entry-point + modules pattern** in SCSS: `application.scss` as root, with structured partials:
- `components/` for UI areas (admin, forms, gantt, wiki, etc.)
- `mixins/` and `functions/` as reusable primitives
- `vendor/` segregates third-party sources
- `plugins/` isolates plugin-specific overrides
- **Policy-as-code for style quality**: Stylelint/ESLint locally + CI + pre-commit hooks
- **Two-phase “build then serve” delivery**:
- Node/Grunt compiles theme assets
- Redmine/Rails serves them; production often requires precompile/restart

##### Diagramming conventions to enforce (so it reads like an architecture doc)
- **Clear labels**: include *path hints* in the label, e.g.
“SCSS sources (`src/sass/**`)", “Compiled CSS (`stylesheets/application.css`)"
- Rectangles: components/artifacts (SCSS, CSS, fonts)
- Rounded rectangles: processes (Grunt build, lint, precompile)
- Blue: runtime (Redmine, Browser)
- Green: source (SCSS)
- Orange: build/CI processes
- Gray: packaged artifacts (CSS/fonts)

##### Don’t overthink it: split into “as many components as possible”
For this repo, “more components” means:
- Split SCSS into: entrypoint, variables, mixins, functions, components, vendor, plugin
- Split pipeline into: lint (stylelint/eslint), build (grunt/sass), watch, hooks, CI
- Split runtime into: Redmine server, theme folder, plugin folder, browser

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — Runtime Integration
  %% =========================
  subgraph "Runtime Integration (Redmine serves compiled theme assets)"
    direction TB

    U["EndUser (Browser)"]:::runtime

    subgraph "Redmine 6.x (Rails app)"
      direction TB
      R["Redmine (Rails)"]:::runtime
      AUI["AdminUI:SelectTheme\n(Admin>Settings>Display)"]:::ops
      PRE["ProductionOps:assets:precompile\n(+restart if needed)"]:::ops
    end

    subgraph "Opale Theme (deployed under {redmine}/themes/opale)"
      direction TB
      THEME["ThemeFolder:opale"]:::artifact
      CSS_OUT["CompiledThemeCSS\n(application.css)"]:::artifact
      FONTS["Webfonts"]:::artifact
    end

    subgraph "Optional Plugin: Redmine Backlogs"
      direction TB
      BL["BacklogsPlugin"]:::runtime
      BL_CSS["PackagedBacklogsCSSOverrides"]:::artifact
      BL_JQ["PackagedBacklogsjQuery/UIOverrides"]:::artifact
    end

    U -->|"HTTPrequests(HTML/CSS)"| R
    AUI -.->|"selectsTheme"| R

    R -->|"resolvesThemeAssets"| THEME
    THEME -->|"serves"| CSS_OUT
    THEME -->|"serves"| FONTS
    CSS_OUT -->|"appliesStyling"| U
    FONTS -->|"fontLoads"| U

    R -.->|"ifinstalled:servesPluginAssets"| BL
    BL -->|"serves"| BL_CSS
    BL -->|"serves"| BL_JQ
    BL_CSS -->|"appliesPluginStyling"| U
    BL_JQ -->|"appliesjQuery/UIStyling"| U

    PRE -.->|"runtaskinproduction"| R
  end

  %% =========================
  %% Diagram 2 — Build / QA / Delivery Pipeline
  %% =========================
  subgraph "Build / QA / Delivery Pipeline (SCSS -> CSS artifacts -> deployed theme)"
    direction TB

    DEV["DeveloperWorkstation\n(Node.js+npm)"]:::actor

    subgraph "SCSS Sources (engineers edit)"
      direction TB
      SCSS_ENTRY["SCSS:Entrypoint\n(application.scss)"]:::source
      SCSS_VARS["SCSS:GlobalVariables\n(_variables.scss)"]:::source
      SCSS_MIX["SCSS:GlobalMixins\n(_mixins.scss)"]:::source
      SCSS_FUN["SCSS:GlobalFunctions\n(_functions.scss)"]:::source

      SCSS_COMP["SCSS:Components/*"]:::source
      SCSS_FUNH["SCSS:Functions/*"]:::source
      SCSS_MIXH["SCSS:Mixins/*"]:::source
      SCSS_VENDOR["SCSS:Vendor/*"]:::source

      SCSS_BL_SRC["SCSS:PluginBacklogs/*"]:::source
      SCSS_BL_JQ_SRC["SCSS:PluginBacklogsjQuery/*"]:::source

      CUSTOMVARS["Optional:_custom-variables.scss\n(gitignored)"]:::source
    end

    subgraph "Node Tooling"
      direction TB
      NPM["npmScripts\n(watch/lint/build)"]:::tool
      PKG["package.json"]:::tool
      LOCK["package-lock.json"]:::tool
      GRUNT["GruntBuild\n(Gruntfile.js)"]:::process
    end

    subgraph "Local Quality Gates (Git hooks)"
      direction TB
      HUSKY["Husky:pre-commit"]:::process
      LSTAGED["lint-staged"]:::process
      STYLELINT["Stylelint\n(.stylelintrc.js)"]:::process
      ESLINT["ESLint\n(.eslintrc.js)"]:::process
    end

    subgraph "CI Quality Gate (GitHub Actions)"
      direction TB
      GHA["CI:LintWorkflow\n(lint.yml)"]:::process
    end

    subgraph "Build Outputs (repo artifacts)"
      direction TB
      OUT_CSS["Output:ThemeCSS\n(stylesheets/application.css)"]:::artifact
      OUT_FONTS["Output:Webfonts\n(webfonts/)"]:::artifact
      OUT_BL["Output:BacklogsOverrides\n(plugins/redmine_backlogs/)"]:::artifact
      OUT_BL_JQ["Output:BacklogsjQueryOverrides\n(plugins/redmine_backlogs/jquery/)"]:::artifact
    end

    subgraph "Delivery Target"
      direction TB
      DEPLOY["DeployToRedmine\n({redmine}/themes/opale)"]:::ops
      PRECOMP["RedmineTask:assets:precompile\n(RAILS_ENV=production)"]:::ops
      SERVE["RedmineServesUpdatedAssets"]:::runtime
      BROWSER2["BrowserRendersUpdatedTheme"]:::runtime
    end

    %% Dev edit & build flow
    DEV -->|"edits"| SCSS_ENTRY
    DEV -->|"edits"| SCSS_COMP
    DEV -->|"edits"| SCSS_VARS
    DEV -->|"edits"| SCSS_MIX
    DEV -->|"edits"| SCSS_FUN
    DEV -->|"edits"| SCSS_FUNH
    DEV -->|"edits"| SCSS_MIXH
    DEV -->|"edits"| SCSS_VENDOR
    DEV -->|"edits"| SCSS_BL_SRC
    DEV -->|"edits"| SCSS_BL_JQ_SRC
    DEV -.->|"optionaloverride"| CUSTOMVARS

    PKG -->|"defines"| NPM
    LOCK -->|"pinsdepsfor"| NPM
    NPM -->|"runs"| GRUNT

    %% SCSS dependency hints into entrypoint
    CUSTOMVARS -->|"importedearly"| SCSS_ENTRY
    SCSS_VARS -->|"usedby"| SCSS_ENTRY
    SCSS_MIX -->|"usedby"| SCSS_ENTRY
    SCSS_FUN -->|"usedby"| SCSS_ENTRY
    SCSS_COMP -->|"includedby"| SCSS_ENTRY
    SCSS_FUNH -->|"includedby"| SCSS_ENTRY
    SCSS_MIXH -->|"includedby"| SCSS_ENTRY
    SCSS_VENDOR -->|"includedby"| SCSS_ENTRY
    SCSS_BL_SRC -->|"includedby"| SCSS_ENTRY
    SCSS_BL_JQ_SRC -->|"includedby"| SCSS_ENTRY

    SCSS_ENTRY -->|"compiledby"| GRUNT
    GRUNT -->|"emits"| OUT_CSS
    GRUNT -->|"emits"| OUT_FONTS
    GRUNT -->|"ships/updates"| OUT_BL
    GRUNT -->|"ships/updates"| OUT_BL_JQ

    %% Pre-commit enforcement
    DEV -->|"gitcommit"| HUSKY
    HUSKY -->|"runs"| LSTAGED
    LSTAGED -->|"runs"| STYLELINT
    LSTAGED -->|"runs"| ESLINT
    LSTAGED -->|"mayrun"| GRUNT

    %% CI enforcement
    DEV -->|"push/PR"| GHA
    GHA -->|"runs"| STYLELINT
    GHA -->|"runs"| ESLINT

    %% Delivery
    OUT_CSS -->|"copied/deployed"| DEPLOY
    OUT_FONTS -->|"copied/deployed"| DEPLOY
    OUT_BL -.->|"manualcopytoPluginAssets"| DEPLOY
    OUT_BL_JQ -.->|"manualcopytoPluginAssets"| DEPLOY

    DEPLOY -->|"productionstep"| PRECOMP
    PRECOMP -->|"updatesassets"| SERVE
    SERVE -->|"HTTP"| BROWSER2
  end

  %% =========================
  %% Diagram 3 — Plugin Override Installation (manual step)
  %% =========================
  subgraph "Plugin Override Installation (manual operation)"
    direction TB
    SRC_OVR["OpalePackagedBacklogsOverrides\n(inside theme repo)"]:::artifact
    MANUAL["ManualCopyOperation\n(to {redmine}/plugins/redmine_backlogs/assets/stylesheets)\n+restart"]:::ops
    PLUGIN_ASSETS["BacklogsPluginAssetsDir\n(on Redmine server)"]:::runtime

    SRC_OVR -.->|"copy"| MANUAL
    MANUAL -->|"installsinto"| PLUGIN_ASSETS
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click CSS_OUT "https://github.com/gagnieray/opale/blob/master/stylesheets/application.css"
  click OUT_CSS "https://github.com/gagnieray/opale/blob/master/stylesheets/application.css"
  click FONTS "https://github.com/gagnieray/opale/tree/master/webfonts/"
  click OUT_FONTS "https://github.com/gagnieray/opale/tree/master/webfonts/"
  click BL_CSS "https://github.com/gagnieray/opale/tree/master/plugins/redmine_backlogs/"
  click OUT_BL "https://github.com/gagnieray/opale/tree/master/plugins/redmine_backlogs/"
  click BL_JQ "https://github.com/gagnieray/opale/tree/master/plugins/redmine_backlogs/jquery/"
  click OUT_BL_JQ "https://github.com/gagnieray/opale/tree/master/plugins/redmine_backlogs/jquery/"

  click SCSS_ENTRY "https://github.com/gagnieray/opale/blob/master/src/sass/application.scss"
  click SCSS_VARS "https://github.com/gagnieray/opale/blob/master/src/sass/_variables.scss"
  click SCSS_MIX "https://github.com/gagnieray/opale/blob/master/src/sass/_mixins.scss"
  click SCSS_FUN "https://github.com/gagnieray/opale/blob/master/src/sass/_functions.scss"
  click SCSS_COMP "https://github.com/gagnieray/opale/tree/master/src/sass/components/"
  click SCSS_FUNH "https://github.com/gagnieray/opale/tree/master/src/sass/functions/"
  click SCSS_MIXH "https://github.com/gagnieray/opale/tree/master/src/sass/mixins/"
  click SCSS_BL_SRC "https://github.com/gagnieray/opale/tree/master/src/sass/plugins/redmine_backlogs/"
  click SCSS_BL_JQ_SRC "https://github.com/gagnieray/opale/tree/master/src/sass/plugins/redmine_backlogs/jquery/"
  click SCSS_VENDOR "https://github.com/gagnieray/opale/tree/master/src/sass/vendor/"

  click GRUNT "https://github.com/gagnieray/opale/blob/master/Gruntfile.js"
  click PKG "https://github.com/gagnieray/opale/blob/master/package.json"
  click LOCK "https://github.com/gagnieray/opale/blob/master/package-lock.json"
  click STYLELINT "https://github.com/gagnieray/opale/blob/master/.stylelintrc.js"
  click ESLINT "https://github.com/gagnieray/opale/blob/master/.eslintrc.js"
  click HUSKY "https://github.com/gagnieray/opale/blob/master/.husky/pre-commit"
  click LSTAGED "https://github.com/gagnieray/opale/blob/master/.lintstagedrc.js"
  click GHA "https://github.com/gagnieray/opale/blob/master/.github/workflows/lint.yml"

  click PRE "https://github.com/gagnieray/opale/blob/master/README.md"
  click NPM "https://github.com/gagnieray/opale/blob/master/README.md"
  click AUI "https://github.com/gagnieray/opale/blob/master/README.md"
  click DEPLOY "https://github.com/gagnieray/opale/blob/master/README.md"
  click PRECOMP "https://github.com/gagnieray/opale/blob/master/README.md"
  click SRC_OVR "https://github.com/gagnieray/opale/tree/master/plugins/redmine_backlogs/"
  click MANUAL "https://github.com/gagnieray/opale/blob/master/README.md"

  %% Supporting docs/material
  click DEV "https://github.com/gagnieray/opale/blob/master/CONTRIBUTING.md"
  click BROWSER2 "https://github.com/gagnieray/opale/tree/master/screenshots/"
  click U "https://github.com/gagnieray/opale/tree/master/screenshots/"

  %% =========================
  %% Styles (color is required)
  %% =========================
  classDef runtime fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0f172a
  classDef source fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
  classDef process fill:#ffedd5,stroke:#ea580c,stroke-width:1px,color:#431407
  classDef tool fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
  classDef artifact fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#111827
  classDef ops fill:#ede9fe,stroke:#6d28d9,stroke-width:1px,color:#2e1065
  classDef actor fill:#cffafe,stroke:#0891b2,stroke-width:1px,color:#083344
```
