How gagnieray/opale works
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