feat: Add application-level settings for CSS color management

- Introduced a new table `application_setting` to store configurable application options.
- Implemented functions to manage CSS color settings, including loading, updating, and reading environment overrides.
- Added a new settings view to render and manage theme colors.
- Updated UI to include a settings page with theme color management and environment overrides display.
- Enhanced CSS styles for the settings page and sidebar navigation.
- Created unit and end-to-end tests for the new settings functionality and CSS management.

docs/architecture/05_building_block_view.md

@@ -4,6 +4,7 @@ description: "Explain the static structure: modules, components, services and th
 status: draft
 ---
 
+<!-- markdownlint-disable-next-line MD025 -->
 # 05 — Building Block View
 
 ## Architecture overview
@@ -25,6 +26,7 @@ Refer to the detailed architecture chapters in `docs/architecture/`:
   - leveraging a shared dependency module (`routes/dependencies.get_db`) for SQLAlchemy session management.
 - **Models** (`models/`): SQLAlchemy ORM models representing database tables and relationships, encapsulating domain entities like Scenario, CapEx, OpEx, Consumption, ProductionOutput, Equipment, Maintenance, and SimulationResult.
 - **Services** (`services/`): business logic layer that processes data, performs calculations, and interacts with models. Key services include reporting calculations and Monte Carlo simulation scaffolding.
+  - `services/settings.py`: manages application settings backed by the `application_setting` table, including CSS variable defaults, persistence, and environment-driven overrides that surface in both the API and UI.
 - **Database** (`config/database.py`): sets up the SQLAlchemy engine and session management for PostgreSQL interactions.
 
 ### Frontend
@@ -32,6 +34,8 @@ Refer to the detailed architecture chapters in `docs/architecture/`:
 - **Templates** (`templates/`): Jinja2 templates for server-rendered HTML views, extending a shared base layout with a persistent sidebar for navigation.
 - **Static Assets** (`static/`): CSS and JavaScript files for styling and interactivity. Shared CSS variables in `static/css/main.css` define the color palette, while page-specific JS modules in `static/js/` handle dynamic behaviors.
 - **Reusable partials** (`templates/partials/components.html`): macro library that standardises select inputs, feedback/empty states, and table wrappers so pages remain consistent while keeping DOM hooks stable for existing JavaScript modules.
+  - `templates/settings.html`: Settings hub that renders theme controls and environment override tables using metadata provided by `routes/ui.py`.
+  - `static/js/settings.js`: applies client-side validation, form submission, and live CSS updates for theme changes, respecting environment-managed variables returned by the API.
 
 ### Middleware & Utilities
 
@@ -45,6 +49,7 @@ Refer to the detailed architecture chapters in `docs/architecture/`:
 - `consumption.py`, `production_output.py`: operational data tables.
 - `equipment.py`, `maintenance.py`: asset management models.
 - `simulation_result.py`: stores Monte Carlo iteration outputs.
+- `application_setting.py`: persists editable application configuration, currently focused on theme variables but designed to store future settings categories.
 
 ## Service Layer
 

docs/architecture/07_deployment_view.md

@@ -15,7 +15,12 @@ The CalMiner application is deployed using a multi-tier architecture consisting
 1. **Client Layer**: This layer consists of web browsers that interact with the application through a user interface rendered by Jinja2 templates and enhanced with JavaScript (Chart.js for dashboards).
 2. **Web Application Layer**: This layer hosts the FastAPI application, which handles API requests, business logic, and serves HTML templates. It communicates with the database layer for data persistence.
 3. **Database Layer**: This layer consists of a PostgreSQL database that stores all application data, including scenarios, parameters, costs, consumption, production outputs, equipment, maintenance logs, and simulation results.
-4. **Caching Layer**: This layer uses Redis to cache frequently accessed data and improve application performance.
+
+```mermaid
+graph TD
+    A[Client Layer<br/>(Web Browsers)] --> B[Web Application Layer<br/>(FastAPI)]
+    B --> C[Database Layer<br/>(PostgreSQL)]
+```
 
 ## Infrastructure Components
 
@@ -29,6 +34,16 @@ The infrastructure components for the application include:
 - **CI/CD Pipeline**: Automated pipelines (Gitea Actions) run tests, build/push Docker images, and trigger deployments.
 - **Cloud Infrastructure (optional)**: The application can be deployed on cloud platforms.
 
+```mermaid
+graph TD
+    A[Web Server] --> B[Database Server]
+    A --> C[Static File Server]
+    A --> D[Reverse Proxy]
+    A --> E[Containerization]
+    A --> F[CI/CD Pipeline]
+    A --> G[Cloud Infrastructure]
+```
+
 ## Environments
 
 The application can be deployed in multiple environments to support development, testing, and production:

docs/architecture/08_concepts.md

@@ -55,6 +55,7 @@ See [Domain Models](08_concepts/08_01_domain_models.md) document for detailed cl
 - `production_output`: production metrics per scenario.
 - `equipment` and `maintenance`: equipment inventory and maintenance events with dates/costs.
 - `simulation_result`: staging table for future Monte Carlo outputs (not yet populated by `run_simulation`).
+- `application_setting`: centralized key/value store for UI and system configuration, supporting typed values, categories, and editability flags so administrators can manage theme variables and future global options without code changes.
 
 Foreign keys secure referential integrity between domain tables and their scenarios, enabling per-scenario analytics.
 

docs/quickstart.md

@@ -52,6 +52,15 @@ If you maintain a Postgres or Redis dependency locally, consider authoring a `do
 - **API base URL**: `http://localhost:8000/api`
 - Key routes include creating scenarios, parameters, costs, consumption, production, equipment, maintenance, and reporting summaries. See the `routes/` directory for full details.
 
+### Theme configuration
+
+- Open `/ui/settings` to access the Settings dashboard. The **Theme Colors** form lists every CSS variable persisted in the `application_setting` table. Updates apply immediately across the UI once saved.
+- Use the accompanying API endpoints for automation or integration tests:
+  - `GET /api/settings/css` returns the active variables, defaults, and metadata describing any environment overrides.
+  - `PUT /api/settings/css` accepts a payload such as `{"variables": {"--color-primary": "#112233"}}` and persists the change unless an environment override is in place.
+- Environment variables prefixed with `CALMINER_THEME_` win over database values. For example, setting `CALMINER_THEME_COLOR_PRIMARY="#112233"` renders the corresponding input read-only and surfaces the override in the Environment Overrides table.
+- Acceptable values include hex (`#rrggbb` or `#rrggbbaa`), `rgb()/rgba()`, and `hsl()/hsla()` expressions with the expected number of components. Invalid inputs trigger a validation error and the API responds with HTTP 422.
+
 ## Dashboard Preview
 
 1. Start the FastAPI server and navigate to `/`.
@@ -70,7 +79,7 @@ E2E tests use Playwright and a session-scoped `live_server` fixture that starts
 
 ## Migrations & Baseline
 
-A consolidated baseline migration (`scripts/migrations/000_base.sql`) captures all schema changes required for a fresh installation. The script is idempotent: it creates the `currency` and `measurement_unit` reference tables, ensures consumption and production records expose unit metadata, and enforces the foreign keys used by CAPEX and OPEX.
+A consolidated baseline migration (`scripts/migrations/000_base.sql`) captures all schema changes required for a fresh installation. The script is idempotent: it creates the `currency` and `measurement_unit` reference tables, provisions the `application_setting` store for configurable UI/system options, ensures consumption and production records expose unit metadata, and enforces the foreign keys used by CAPEX and OPEX.
 
 Configure granular database settings in your PowerShell session before running migrations:
 
@@ -88,6 +97,8 @@ python scripts/setup_database.py --run-migrations --seed-data
 
 The dry-run invocation reports which steps would execute without making changes. The live run applies the baseline (if not already recorded in `schema_migrations`) and seeds the reference data relied upon by the UI and API.
 
+> ℹ️ When `--seed-data` is supplied without `--run-migrations`, the bootstrap script automatically applies any pending SQL migrations first so the `application_setting` table (and future settings-backed features) are present before seeding.
+
 > ℹ️ The application still accepts `DATABASE_URL` as a fallback if the granular variables are not set.
 
 ## Database bootstrap workflow