Upload 33 files

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

Dockerfile

@@ -0,0 +1,33 @@
+# SolverForge Quickstart Dockerfile
+# Compatible with HuggingFace Spaces (Docker SDK)
+
+FROM python:3.12
+
+# Install JDK 21 (required for solverforge-legacy)
+RUN apt-get update && \
+    apt-get install -y wget gnupg2 && \
+    wget -O- https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor > /usr/share/keyrings/adoptium-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/adoptium-archive-keyring.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list && \
+    apt-get update && \
+    apt-get install -y temurin-21-jdk && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy application files
+COPY . .
+
+# Install the application
+RUN pip install --no-cache-dir -e .
+
+# HuggingFace Spaces uses port 7860 by default
+# Our app uses 8080 internally, we'll configure uvicorn to use 7860
+ENV PORT=7860
+
+# Expose port
+EXPOSE 7860
+
+# Run the application (HuggingFace compatible)
+CMD ["python", "-m", "uvicorn", "my_quickstart:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README_HUGGINGFACE.md

@@ -0,0 +1,47 @@
+---
+title: SolverForge Quickstart
+emoji: "+"
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: apache
+---
+
+# SolverForge Quickstart
+
+A constraint optimization application powered by [SolverForge](https://github.com/solverforge).
+
+## What This Does
+
+This app solves a **task assignment optimization problem**:
+- Assign tasks to resources while respecting skill requirements
+- Balance workload fairly across resources
+- Minimize total duration
+
+## How to Use
+
+1. Click "Load Small Dataset" to load sample data
+2. Click "Solve" to start the optimization
+3. Watch the score improve as the solver works
+4. Click "Stop" to terminate early if needed
+
+## API
+
+Access the API documentation at `/q/swagger-ui`
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/demo-data` | List demo datasets |
+| GET | `/demo-data/{id}` | Get demo data |
+| POST | `/schedules` | Start solving |
+| GET | `/schedules/{id}` | Get solution |
+| DELETE | `/schedules/{id}` | Stop solving |
+
+## Technical Details
+
+- **Backend**: Python + FastAPI
+- **Solver**: SolverForge (Timefold-based metaheuristic)
+- **Runtime**: Requires JDK 21 (included in Docker image)

logging.conf

@@ -0,0 +1,30 @@
+[loggers]
+keys=root,solverforge
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=simpleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[logger_solverforge]
+level=INFO
+qualname=solverforge
+handlers=consoleHandler
+propagate=0
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=simpleFormatter
+args=(sys.stdout,)
+
+[formatter_simpleFormatter]
+class=uvicorn.logging.ColourizedFormatter
+format={levelprefix:<8} @ {name} : {message}
+style={
+use_colors=True

pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "my_quickstart"  # TODO: Change to your project name
+version = "1.0.0"
+description = "A SolverForge constraint optimization quickstart"
+requires-python = ">=3.10"
+dependencies = [
+    'solverforge-legacy == 1.24.1',
+    'fastapi == 0.111.0',
+    'pydantic == 2.7.3',
+    'uvicorn == 0.30.1',
+]
+
+[project.optional-dependencies]
+dev = [
+    'pytest == 8.2.2',
+]
+
+[project.scripts]
+run-app = "my_quickstart:main"

src/my_quickstart/__init__.py

@@ -0,0 +1,21 @@
+import uvicorn
+import os
+
+from .rest_api import app as app
+
+
+def main():
+    port = int(os.environ.get("PORT", 8080))
+    config = uvicorn.Config(
+        "my_quickstart:app",
+        host="0.0.0.0",
+        port=port,
+        log_config="logging.conf",
+        use_colors=True,
+    )
+    server = uvicorn.Server(config)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

src/my_quickstart/constraints.py

@@ -0,0 +1,239 @@
+"""
+Constraint definitions for your optimization problem.
+
+Constraints are defined using a fluent API:
+1. for_each(Entity) - iterate over all entities
+2. filter(predicate) - keep only matching entities
+3. join(OtherEntity, ...) - combine with other entities
+4. group_by(key, collector) - aggregate by key
+5. penalize(weight) or reward(weight) - affect the score
+
+TODO: Replace these example constraints with your own business rules.
+"""
+
+from solverforge_legacy.solver.score import (
+    constraint_provider,
+    ConstraintFactory,
+    Joiners,
+    HardSoftScore,
+    ConstraintCollectors,
+)
+
+from .domain import Resource, Task
+
+
+# =============================================================================
+# CONSTRAINT WEIGHTS
+# =============================================================================
+# Global weights that can be adjusted at runtime via the REST API.
+# Weight 0 = disabled, 100 = full strength.
+# Set by rest_api.py before solving starts.
+
+CONSTRAINT_WEIGHTS = {
+    'required_skill': 100,      # Hard constraint
+    'resource_capacity': 100,   # Hard constraint
+    'minimize_duration': 50,    # Soft constraint
+    'balance_load': 50,         # Soft constraint
+}
+
+
+def get_weight(name: str) -> int:
+    """Get the weight for a constraint (0-100 scale)."""
+    return CONSTRAINT_WEIGHTS.get(name, 100)
+
+
+@constraint_provider
+def define_constraints(constraint_factory: ConstraintFactory):
+    """
+    Define all constraints for the optimization problem.
+
+    Returns a list of constraints, evaluated in order:
+    - Hard constraints: Must be satisfied (score < 0 = infeasible)
+    - Soft constraints: Should be optimized (higher = better)
+    """
+    return [
+        # Hard constraints (must be satisfied)
+        required_skill(constraint_factory),
+        resource_capacity(constraint_factory),
+
+        # Soft constraints (optimize these)
+        minimize_total_duration(constraint_factory),
+        balance_resource_load(constraint_factory),
+    ]
+
+
+# =============================================================================
+# HARD CONSTRAINTS
+# =============================================================================
+
+def required_skill(constraint_factory: ConstraintFactory):
+    """
+    Hard: Each task must be assigned to a resource with the required skill.
+
+    Pattern: for_each -> filter -> penalize
+
+    NOTE: We check task.resource is not None FIRST, because unassigned tasks
+    should not be penalized - they're just not yet assigned.
+
+    NOTE: We use len(str(task.required_skill)) > 0 instead of just task.required_skill
+    because the value may be a Java String object which doesn't work with Python's
+    boolean operators directly.
+
+    WEIGHT: When weight=0, this constraint is effectively disabled.
+    """
+    weight = get_weight('required_skill')
+    if weight == 0:
+        # Return a no-op constraint when disabled
+        return (
+            constraint_factory.for_each(Task)
+            .filter(lambda task: False)  # Never matches
+            .penalize(HardSoftScore.ONE_HARD)
+            .as_constraint("Required skill missing")
+        )
+
+    return (
+        constraint_factory.for_each(Task)
+        .filter(lambda task: task.resource is not None
+                and len(str(task.required_skill)) > 0
+                and not task.has_required_skill())
+        .penalize(HardSoftScore.ONE_HARD, lambda task: weight)
+        .as_constraint("Required skill missing")
+    )
+
+
+def resource_capacity(constraint_factory: ConstraintFactory):
+    """
+    Hard: Total task duration per resource must not exceed capacity.
+
+    Pattern: for_each -> group_by -> filter -> penalize
+
+    WEIGHT: When weight=0, this constraint is effectively disabled.
+    """
+    weight = get_weight('resource_capacity')
+    if weight == 0:
+        return (
+            constraint_factory.for_each(Task)
+            .filter(lambda task: False)
+            .penalize(HardSoftScore.ONE_HARD)
+            .as_constraint("Resource capacity exceeded")
+        )
+
+    return (
+        constraint_factory.for_each(Task)
+        .group_by(
+            lambda task: task.resource,
+            ConstraintCollectors.sum(lambda task: task.duration)
+        )
+        .filter(lambda resource, total_duration:
+                resource is not None and total_duration > resource.capacity)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda resource, total_duration: (total_duration - resource.capacity) * weight // 100
+        )
+        .as_constraint("Resource capacity exceeded")
+    )
+
+
+# =============================================================================
+# SOFT CONSTRAINTS
+# =============================================================================
+
+def minimize_total_duration(constraint_factory: ConstraintFactory):
+    """
+    Soft: Prefer shorter total duration (makespan).
+
+    Pattern: for_each -> penalize with weight function
+
+    WEIGHT: Penalty multiplied by weight/100.
+    """
+    weight = get_weight('minimize_duration')
+    if weight == 0:
+        return (
+            constraint_factory.for_each(Task)
+            .filter(lambda task: False)
+            .penalize(HardSoftScore.ONE_SOFT)
+            .as_constraint("Minimize total duration")
+        )
+
+    return (
+        constraint_factory.for_each(Task)
+        .filter(lambda task: task.resource is not None)
+        .penalize(HardSoftScore.ONE_SOFT, lambda task: task.duration * weight // 100)
+        .as_constraint("Minimize total duration")
+    )
+
+
+def balance_resource_load(constraint_factory: ConstraintFactory):
+    """
+    Soft: Balance workload fairly across all resources.
+
+    Pattern: for_each -> group_by -> complement -> group_by(loadBalance) -> penalize
+
+    WEIGHT: Penalty multiplied by weight/100.
+    """
+    weight = get_weight('balance_load')
+    if weight == 0:
+        return (
+            constraint_factory.for_each(Task)
+            .filter(lambda task: False)
+            .penalize(HardSoftScore.ONE_SOFT)
+            .as_constraint("Balance resource load")
+        )
+
+    return (
+        constraint_factory.for_each(Task)
+        .group_by(
+            lambda task: task.resource,
+            ConstraintCollectors.sum(lambda task: task.duration)
+        )
+        .complement(Resource, lambda r: 0)  # Include resources with 0 tasks
+        .group_by(
+            ConstraintCollectors.load_balance(
+                lambda resource, duration: resource,
+                lambda resource, duration: duration,
+            )
+        )
+        .penalize(
+            HardSoftScore.ONE_SOFT,
+            lambda load_balance: int(load_balance.unfairness()) * weight // 100
+        )
+        .as_constraint("Balance resource load")
+    )
+
+
+# =============================================================================
+# ADDITIONAL CONSTRAINT PATTERNS (commented examples)
+# =============================================================================
+
+# def no_overlapping_tasks(constraint_factory: ConstraintFactory):
+#     """
+#     Example: Two tasks on same resource cannot overlap in time.
+#
+#     Pattern: for_each_unique_pair with Joiners
+#     """
+#     return (
+#         constraint_factory.for_each_unique_pair(
+#             Task,
+#             Joiners.equal(lambda task: task.resource),
+#             Joiners.overlapping(
+#                 lambda task: task.start_time,
+#                 lambda task: task.end_time
+#             ),
+#         )
+#         .penalize(HardSoftScore.ONE_HARD)
+#         .as_constraint("Overlapping tasks")
+#     )
+
+
+# def preferred_resource(constraint_factory: ConstraintFactory):
+#     """
+#     Example: Reward tasks assigned to their preferred resource.
+#
+#     Pattern: for_each -> filter -> reward
+#     """
+#     return (
+#         constraint_factory.for_each(Task)
+#         .filter(lambda task: task.resource == task.preferred_resource)
+#         .reward(HardSoftScore.ONE_SOFT)
+#         .as_constraint("Preferred resource")
+#     )

src/my_quickstart/demo_data.py

@@ -0,0 +1,84 @@
+"""
+Demo data generation.
+
+Provides sample datasets for testing and demonstration.
+TODO: Replace with realistic data for your domain.
+"""
+
+from enum import Enum
+from .domain import Resource, Task, Schedule
+
+
+class DemoData(str, Enum):
+    """Available demo datasets."""
+    SMALL = "SMALL"
+    MEDIUM = "MEDIUM"
+
+
+def generate_demo_data(dataset: DemoData) -> Schedule:
+    """
+    Generate a demo dataset.
+
+    TODO: Replace with realistic data for your domain.
+    """
+    if dataset == DemoData.SMALL:
+        return _generate_small()
+    elif dataset == DemoData.MEDIUM:
+        return _generate_medium()
+    else:
+        raise ValueError(f"Unknown dataset: {dataset}")
+
+
+def _generate_small() -> Schedule:
+    """Small dataset: 3 resources, 10 tasks."""
+    resources = [
+        Resource(name="Alice", capacity=100, skills={"python", "sql"}),
+        Resource(name="Bob", capacity=120, skills={"python", "java"}),
+        Resource(name="Charlie", capacity=80, skills={"sql", "java"}),
+    ]
+
+    tasks = [
+        Task(id="task-1", name="Data Pipeline", duration=30, required_skill="python"),
+        Task(id="task-2", name="API Development", duration=45, required_skill="python"),
+        Task(id="task-3", name="Database Schema", duration=20, required_skill="sql"),
+        Task(id="task-4", name="Query Optimization", duration=35, required_skill="sql"),
+        Task(id="task-5", name="Backend Service", duration=50, required_skill="java"),
+        Task(id="task-6", name="Data Analysis", duration=25, required_skill="python"),
+        Task(id="task-7", name="Report Generation", duration=15, required_skill="sql"),
+        Task(id="task-8", name="Integration Tests", duration=40, required_skill="java"),
+        Task(id="task-9", name="Code Review", duration=20),  # No skill required
+        Task(id="task-10", name="Documentation", duration=15),  # No skill required
+    ]
+
+    return Schedule(resources=resources, tasks=tasks)
+
+
+def _generate_medium() -> Schedule:
+    """Medium dataset: 5 resources, 25 tasks.
+
+    Total capacity: 700 min (150+140+130+160+120)
+    Total task duration: ~675 min (feasible but challenging)
+    """
+    resources = [
+        Resource(name="Alice", capacity=150, skills={"python", "sql", "ml"}),
+        Resource(name="Bob", capacity=140, skills={"python", "java", "devops"}),
+        Resource(name="Charlie", capacity=130, skills={"sql", "java", "frontend"}),
+        Resource(name="Diana", capacity=160, skills={"python", "ml", "devops"}),
+        Resource(name="Eve", capacity=120, skills={"frontend", "java", "sql"}),
+    ]
+
+    skills = ["python", "sql", "java", "ml", "devops", "frontend", ""]
+    tasks = []
+    for i in range(25):
+        skill = skills[i % len(skills)]
+        tasks.append(
+            Task(
+                id=f"task-{i+1}",
+                name=f"Task {i+1}",
+                # Duration formula: 15-39 min, total ~675 min (fits in 700 capacity)
+                duration=15 + (i * 3) % 25,
+                required_skill=skill,
+            )
+        )
+
+    return Schedule(resources=resources, tasks=tasks)

src/my_quickstart/domain.py

@@ -0,0 +1,141 @@
+"""
+Domain model for your optimization problem.
+
+This file defines:
+1. Problem facts (@dataclass) - immutable input data
+2. Planning entities (@planning_entity) - what the solver assigns
+3. Planning solution (@planning_solution) - container for the problem
+
+TODO: Replace this example with your own domain model.
+"""
+
+from dataclasses import dataclass, field
+from typing import Annotated, Optional, List
+from datetime import datetime
+
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.domain import (
+    planning_entity,
+    planning_solution,
+    PlanningId,
+    PlanningVariable,
+    PlanningEntityCollectionProperty,
+    ProblemFactCollectionProperty,
+    ValueRangeProvider,
+    PlanningScore,
+)
+from solverforge_legacy.solver.score import HardSoftScore
+
+from .json_serialization import JsonDomainBase
+from pydantic import Field
+
+
+# =============================================================================
+# PROBLEM FACTS (immutable input data)
+# =============================================================================
+
+@dataclass
+class Resource:
+    """
+    A resource that can be assigned to tasks.
+
+    TODO: Replace with your own problem fact (e.g., Employee, Room, Vehicle).
+    """
+    name: Annotated[str, PlanningId]
+    capacity: int = 100
+    skills: set[str] = field(default_factory=set)
+
+
+# =============================================================================
+# PLANNING ENTITIES (what the solver optimizes)
+# =============================================================================
+
+@planning_entity
+@dataclass
+class Task:
+    """
+    A task to be assigned to a resource.
+
+    The `resource` field is the planning variable - the solver will
+    try different assignments to find the best solution.
+
+    TODO: Replace with your own planning entity (e.g., Shift, Lesson, Delivery).
+    """
+    id: Annotated[str, PlanningId]
+    name: str
+    duration: int  # in minutes
+    required_skill: str = ""
+
+    # This is the planning variable - solver assigns this
+    resource: Annotated[Resource | None, PlanningVariable] = None
+
+    def has_required_skill(self) -> bool:
+        """Check if assigned resource has the required skill.
+
+        NOTE: We use len(str(...)) instead of boolean check because
+        required_skill may be a Java String during constraint evaluation.
+        """
+        if self.resource is None:
+            return False
+        if len(str(self.required_skill)) == 0:
+            return True
+        return str(self.required_skill) in self.resource.skills
+
+
+# =============================================================================
+# PLANNING SOLUTION (container)
+# =============================================================================
+
+@planning_solution
+@dataclass
+class Schedule:
+    """
+    The planning solution containing all problem facts and planning entities.
+
+    TODO: Rename to match your domain (e.g., Timetable, RoutePlan, Roster).
+    """
+    resources: Annotated[
+        list[Resource],
+        ProblemFactCollectionProperty,
+        ValueRangeProvider
+    ]
+    tasks: Annotated[list[Task], PlanningEntityCollectionProperty]
+    score: Annotated[HardSoftScore | None, PlanningScore] = None
+    solver_status: SolverStatus = SolverStatus.NOT_SOLVING
+
+
+# =============================================================================
+# PYDANTIC MODELS (for REST API serialization)
+# =============================================================================
+
+class ResourceModel(JsonDomainBase):
+    """Pydantic model for Resource serialization."""
+    name: str
+    capacity: int = 100
+    skills: List[str] = Field(default_factory=list)
+
+
+class TaskModel(JsonDomainBase):
+    """Pydantic model for Task serialization."""
+    id: str
+    name: str
+    duration: int
+    required_skill: str = Field(default="", alias="requiredSkill")
+    resource: Optional[str] = None  # Resource name or None
+
+
+class ConstraintWeightsModel(JsonDomainBase):
+    """Pydantic model for constraint weight configuration."""
+    required_skill: int = Field(default=100, ge=0, le=100)
+    resource_capacity: int = Field(default=100, ge=0, le=100)
+    minimize_duration: int = Field(default=50, ge=0, le=100)
+    balance_load: int = Field(default=50, ge=0, le=100)
+
+
+class ScheduleModel(JsonDomainBase):
+    """Pydantic model for Schedule serialization."""
+    resources: List[ResourceModel]
+    tasks: List[TaskModel]
+    score: Optional[str] = None
+    solver_status: Optional[str] = Field(default=None, alias="solverStatus")
+    constraint_weights: Optional[ConstraintWeightsModel] = Field(default=None, alias="constraintWeights")

src/my_quickstart/json_serialization.py

@@ -0,0 +1,42 @@
+"""
+Pydantic utilities for JSON serialization.
+
+This provides a base class with camelCase conversion for REST API compatibility.
+"""
+
+from solverforge_legacy.solver.score import HardSoftScore
+from typing import Any
+from pydantic import BaseModel, ConfigDict, PlainSerializer, BeforeValidator
+from pydantic.alias_generators import to_camel
+
+
+# Score serialization (HardSoftScore -> string like "0hard/0soft")
+ScoreSerializer = PlainSerializer(
+    lambda score: str(score) if score is not None else None,
+    return_type=str | None
+)
+
+
+def validate_score(v: Any) -> Any:
+    """Parse score from string format."""
+    if isinstance(v, HardSoftScore) or v is None:
+        return v
+    if isinstance(v, str):
+        return HardSoftScore.parse(v)
+    raise ValueError('"score" should be a string')
+
+
+ScoreValidator = BeforeValidator(validate_score)
+
+
+class JsonDomainBase(BaseModel):
+    """
+    Base class for Pydantic models with camelCase JSON serialization.
+
+    Converts Python snake_case to JavaScript camelCase automatically.
+    """
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )

src/my_quickstart/rest_api.py

@@ -0,0 +1,285 @@
+"""
+REST API endpoints.
+
+Provides a standard API for:
+- Listing and fetching demo data
+- Starting/stopping solving
+- Getting solution status
+- Analyzing scores
+"""
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from uuid import uuid4
+from dataclasses import replace
+from typing import Dict, List
+import os
+
+from .domain import Schedule, ScheduleModel, Resource, Task, ConstraintWeightsModel
+from .demo_data import DemoData, generate_demo_data
+from .solver import solver_manager, solution_manager
+from . import constraints  # For setting global weights
+
+
+app = FastAPI(
+    title="SolverForge Quickstart",
+    description="Constraint optimization API",
+    docs_url='/q/swagger-ui'
+)
+
+# In-memory storage for solving jobs
+data_sets: dict[str, Schedule] = {}
+
+
+# =============================================================================
+# DEMO DATA ENDPOINTS
+# =============================================================================
+
+@app.get("/demo-data")
+async def demo_data_list() -> list[DemoData]:
+    """List available demo datasets."""
+    return [e for e in DemoData]
+
+
+@app.get("/demo-data/{dataset_id}", response_model_exclude_none=True)
+async def get_demo_data(dataset_id: str) -> ScheduleModel:
+    """Get a specific demo dataset."""
+    demo_data = getattr(DemoData, dataset_id)
+    domain_schedule = generate_demo_data(demo_data)
+    return _schedule_to_model(domain_schedule)
+
+
+# =============================================================================
+# SOLVING ENDPOINTS
+# =============================================================================
+
+@app.post("/schedules")
+async def solve(schedule_model: ScheduleModel) -> str:
+    """
+    Start solving a schedule.
+
+    Returns a job ID that can be used to check progress and get results.
+    Accepts optional constraint_weights to adjust constraint penalties.
+    """
+    job_id = str(uuid4())
+
+    # Set constraint weights globally before solving
+    if schedule_model.constraint_weights:
+        weights = schedule_model.constraint_weights
+        constraints.CONSTRAINT_WEIGHTS = {
+            'required_skill': weights.required_skill,
+            'resource_capacity': weights.resource_capacity,
+            'minimize_duration': weights.minimize_duration,
+            'balance_load': weights.balance_load,
+        }
+    else:
+        # Reset to defaults
+        constraints.CONSTRAINT_WEIGHTS = {
+            'required_skill': 100,
+            'resource_capacity': 100,
+            'minimize_duration': 50,
+            'balance_load': 50,
+        }
+
+    schedule = _model_to_schedule(schedule_model)
+    data_sets[job_id] = schedule
+
+    solver_manager.solve_and_listen(
+        job_id,
+        schedule,
+        lambda solution: _update_schedule(job_id, solution)
+    )
+    return job_id
+
+
+@app.get("/schedules")
+async def list_schedules() -> List[str]:
+    """List all job IDs."""
+    return list(data_sets.keys())
+
+
+@app.get("/schedules/{job_id}", response_model_exclude_none=True)
+async def get_schedule(job_id: str) -> ScheduleModel:
+    """Get the current solution for a job."""
+    if job_id not in data_sets:
+        raise ValueError(f"No schedule found with ID {job_id}")
+
+    schedule = data_sets[job_id]
+    updated = replace(schedule, solver_status=solver_manager.get_solver_status(job_id))
+    return _schedule_to_model(updated)
+
+
+@app.get("/schedules/{job_id}/status")
+async def get_status(job_id: str) -> Dict:
+    """Get solving status and score."""
+    if job_id not in data_sets:
+        raise ValueError(f"No schedule found with ID {job_id}")
+
+    schedule = data_sets[job_id]
+    solver_status = solver_manager.get_solver_status(job_id)
+
+    return {
+        "score": {
+            "hardScore": schedule.score.hard_score if schedule.score else 0,
+            "softScore": schedule.score.soft_score if schedule.score else 0,
+        },
+        "solverStatus": solver_status.name,
+    }
+
+
+@app.delete("/schedules/{job_id}")
+async def stop_solving(job_id: str) -> ScheduleModel:
+    """Stop solving and return current solution."""
+    if job_id not in data_sets:
+        raise ValueError(f"No schedule found with ID {job_id}")
+
+    try:
+        solver_manager.terminate_early(job_id)
+    except Exception as e:
+        print(f"Warning: terminate_early failed for {job_id}: {e}")
+
+    return await get_schedule(job_id)
+
+
+@app.put("/schedules/analyze")
+async def analyze(schedule_model: ScheduleModel) -> Dict:
+    """Analyze a schedule's score breakdown."""
+    schedule = _model_to_schedule(schedule_model)
+    analysis = solution_manager.analyze(schedule)
+
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            {
+                "name": str(getattr(getattr(match, 'constraint_ref', None), 'constraint_name', "")),
+                "score": str(getattr(match, 'score', "0hard/0soft")),
+                "justification": str(getattr(match, 'justification', "")),
+            }
+            for match in getattr(constraint, 'matches', []) or []
+        ]
+        constraints.append({
+            "name": str(getattr(constraint, 'constraint_name', "")),
+            "weight": str(getattr(constraint, 'weight', "0hard/0soft")),
+            "score": str(getattr(constraint, 'score', "0hard/0soft")),
+            "matches": matches,
+        })
+
+    return {"constraints": constraints}
+
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def _update_schedule(job_id: str, schedule: Schedule):
+    """Callback for solver updates."""
+    global data_sets
+    data_sets[job_id] = schedule
+
+
+def _schedule_to_model(schedule: Schedule) -> ScheduleModel:
+    """Convert domain Schedule to Pydantic model."""
+    from .domain import ResourceModel, TaskModel, ScheduleModel
+
+    resources = [
+        ResourceModel(
+            name=r.name,
+            capacity=r.capacity,
+            skills=list(r.skills),
+        )
+        for r in schedule.resources
+    ]
+
+    tasks = [
+        TaskModel(
+            id=t.id,
+            name=t.name,
+            duration=t.duration,
+            requiredSkill=t.required_skill,
+            resource=t.resource.name if t.resource else None,
+        )
+        for t in schedule.tasks
+    ]
+
+    return ScheduleModel(
+        resources=resources,
+        tasks=tasks,
+        score=str(schedule.score) if schedule.score else None,
+        solverStatus=schedule.solver_status.name if schedule.solver_status else None,
+    )
+
+
+def _model_to_schedule(model: ScheduleModel) -> Schedule:
+    """Convert Pydantic model to domain Schedule."""
+    resources = {
+        r.name: Resource(
+            name=r.name,
+            capacity=r.capacity,
+            skills=set(r.skills),
+        )
+        for r in model.resources
+    }
+
+    tasks = [
+        Task(
+            id=t.id,
+            name=t.name,
+            duration=t.duration,
+            required_skill=t.required_skill or "",
+            resource=resources.get(t.resource) if t.resource else None,
+        )
+        for t in model.tasks
+    ]
+
+    return Schedule(
+        resources=list(resources.values()),
+        tasks=tasks,
+    )
+
+
+# =============================================================================
+# SOURCE CODE VIEWER ENDPOINTS
+# =============================================================================
+
+# Whitelist of files that can be viewed
+SOURCE_FILES = {
+    'domain.py': 'src/my_quickstart/domain.py',
+    'constraints.py': 'src/my_quickstart/constraints.py',
+    'solver.py': 'src/my_quickstart/solver.py',
+    'rest_api.py': 'src/my_quickstart/rest_api.py',
+    'demo_data.py': 'src/my_quickstart/demo_data.py',
+    'index.html': 'static/index.html',
+    'app.js': 'static/app.js',
+    'app.css': 'static/app.css',
+}
+
+
+@app.get("/source-code")
+async def list_source_files() -> List[str]:
+    """List available source files for the code viewer."""
+    return list(SOURCE_FILES.keys())
+
+
+@app.get("/source-code/{filename}")
+async def get_source_code(filename: str) -> Dict:
+    """Get the contents of a source file."""
+    if filename not in SOURCE_FILES:
+        raise ValueError(f"File not available: {filename}")
+
+    filepath = SOURCE_FILES[filename]
+    if not os.path.exists(filepath):
+        raise ValueError(f"File not found: {filepath}")
+
+    with open(filepath, 'r') as f:
+        content = f.read()
+
+    return {"filename": filename, "content": content}
+
+
+# =============================================================================
+# STATIC FILES (optional web UI)
+# =============================================================================
+
+# Mount static files if directory exists
+if os.path.exists("static"):
+    app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/my_quickstart/solver.py

@@ -0,0 +1,40 @@
+"""
+Solver configuration.
+
+This file configures the SolverForge optimization engine:
+- Solution class (what to optimize)
+- Entity classes (what to assign)
+- Constraint provider (business rules)
+- Termination config (when to stop)
+"""
+
+from solverforge_legacy.solver import SolverManager, SolverFactory, SolutionManager
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import Schedule, Task
+from .constraints import define_constraints
+
+
+# Solver configuration
+solver_config = SolverConfig(
+    solution_class=Schedule,
+    entity_class_list=[Task],
+    score_director_factory_config=ScoreDirectorFactoryConfig(
+        constraint_provider_function=define_constraints
+    ),
+    termination_config=TerminationConfig(
+        # Stop after 30 seconds (adjust for your problem size)
+        spent_limit=Duration(seconds=30)
+    ),
+)
+
+# Create solver manager (handles async solving)
+solver_manager = SolverManager.create(SolverFactory.create(solver_config))
+
+# Create solution manager (for score analysis)
+solution_manager = SolutionManager.create(solver_manager)

static/app.css

@@ -0,0 +1,728 @@
+/*
+ * =============================================================================
+ * SOLVERFORGE QUICKSTART TEMPLATE - APP STYLES
+ * =============================================================================
+ *
+ * Custom styles for the quickstart template UI.
+ * This file creates the "code-link" educational UI appearance.
+ *
+ * CUSTOMIZATION GUIDE:
+ * - Brand colors: Change #10b981 (green) and #3E00FF (violet)
+ * - Card styles: Modify .kpi-card, .task-card, .resource-card
+ * - Animations: Adjust @keyframes rules for different effects
+ *
+ * SECTIONS:
+ * 1. Global styles
+ * 2. Interactive Code clickable elements (code reveal on hover)
+ * 3. Hero section (gradient banner)
+ * 4. KPI cards (metrics display)
+ * 5. Control bar (solve/stop buttons)
+ * 6. Section cards (container panels)
+ * 7. Task cards (planning entity visualization)
+ * 8. Resource cards (problem fact visualization)
+ * 9. Constraint legend (clickable constraint badges)
+ * 10. Build tab (file navigator and code viewer)
+ * 11. Navigation overrides
+ * 12. Responsive adjustments
+ */
+
+/* =============================================================================
+ * 1. GLOBAL STYLES
+ *
+ * Base styles for the page. The light gray background (#f8fafc) provides
+ * contrast for white cards.
+ * ============================================================================= */
+body {
+    background: #f8fafc;
+}
+
+/* =============================================================================
+ * 2. INTERACTIVE CODE CLICKABLE ELEMENTS
+ *
+ * The "code-link" feature: every UI element shows a code icon on hover,
+ * indicating it can be clicked to view the source code that generates it.
+ *
+ * HOW IT WORKS:
+ * 1. Add class="code-link" to any element
+ * 2. Add data-target="filename:section" to specify the code location
+ * 3. CSS ::after pseudo-element creates the code icon
+ * 4. JavaScript handles click -> navigates to Build tab
+ *
+ * EXAMPLE:
+ * <div class="kpi-card code-link" data-target="app.js:updateKPIs">
+ *   <span class="code-tooltip">updateKPIs() in app.js</span>
+ *   ...content...
+ * </div>
+ * ============================================================================= */
+.code-link {
+    position: relative;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+/* Code icon that appears on hover (uses Font Awesome code icon) */
+.code-link::after {
+    content: '\f121'; /* fa-code unicode */
+    font-family: 'Font Awesome 6 Free';
+    font-weight: 900;
+    position: absolute;
+    top: 4px;
+    right: 4px;
+    width: 20px;
+    height: 20px;
+    background: rgba(62, 0, 255, 0.9); /* SolverForge violet */
+    color: white;
+    border-radius: 4px;
+    font-size: 10px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+    transform: scale(0.8);
+    transition: all 0.2s ease;
+}
+
+.code-link:hover::after {
+    opacity: 1;
+    transform: scale(1);
+}
+
+/* Violet glow border on hover to indicate clickability */
+.code-link:hover {
+    box-shadow: 0 0 0 2px rgba(62, 0, 255, 0.5);
+}
+
+/* Tooltip that appears above code-link elements */
+.code-tooltip {
+    position: absolute;
+    bottom: calc(100% + 8px);
+    left: 50%;
+    transform: translateX(-50%);
+    background: #1f2937;
+    color: white;
+    padding: 6px 12px;
+    border-radius: 6px;
+    font-size: 12px;
+    white-space: nowrap;
+    opacity: 0;
+    visibility: hidden;
+    transition: all 0.2s ease;
+    z-index: 1000;
+    pointer-events: none;
+}
+
+/* Tooltip arrow */
+.code-tooltip::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    border: 6px solid transparent;
+    border-top-color: #1f2937;
+}
+
+.code-link:hover .code-tooltip {
+    opacity: 1;
+    visibility: visible;
+}
+
+/* =============================================================================
+ * 3. HERO SECTION
+ *
+ * The prominent banner at the top of the Demo tab. Uses a gradient from
+ * SolverForge violet to green, with a rotating shimmer effect.
+ *
+ * TODO: Update the gradient colors to match your brand or problem domain.
+ * ============================================================================= */
+.hero-section {
+    background: linear-gradient(135deg, #2E1760 0%, #3E00FF 50%, #10b981 100%);
+    position: relative;
+    overflow: hidden;
+    border-radius: 16px;
+    padding: 2rem;
+}
+
+/* Animated shimmer effect - creates visual interest */
+.hero-section::before {
+    content: '';
+    position: absolute;
+    top: -50%;
+    right: -50%;
+    width: 100%;
+    height: 200%;
+    background: radial-gradient(circle, rgba(255,255,255,0.1) 0%, transparent 70%);
+    animation: shimmer 15s infinite linear;
+}
+
+@keyframes shimmer {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+
+/* Small badge above the hero title */
+.hero-badge {
+    background: rgba(255,255,255,0.2);
+    color: white;
+    padding: 4px 12px;
+    border-radius: 20px;
+    font-size: 12px;
+    display: inline-block;
+    margin-bottom: 1rem;
+}
+
+/* =============================================================================
+ * 4. KPI CARDS
+ *
+ * Key Performance Indicator cards show solution metrics at a glance.
+ *
+ * DEFAULT KPIs (customize for your domain):
+ * - Total Tasks: Count of planning entities
+ * - Assigned: Count with non-null planning variable
+ * - Violations: Count of hard constraint violations
+ * - Score: The HardSoftScore from the solver
+ *
+ * COLOR CODING:
+ * - Purple (#6366f1): Neutral/informational
+ * - Green (#10b981): Positive/success
+ * - Red (#ef4444): Negative/violations
+ * - Violet (#3E00FF): Score/brand
+ * ============================================================================= */
+.kpi-card {
+    background: white;
+    border-radius: 12px;
+    padding: 1.25rem;
+    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    text-align: center;
+    transition: transform 0.2s, box-shadow 0.2s;
+    height: 100%;
+}
+
+/* Hover lift effect - makes cards feel interactive */
+.kpi-card:hover {
+    transform: translateY(-4px);
+    box-shadow: 0 12px 20px -5px rgba(0, 0, 0, 0.15);
+}
+
+.kpi-icon {
+    font-size: 1.5rem;
+    margin-bottom: 0.5rem;
+    opacity: 0.8;
+}
+
+.kpi-value {
+    font-size: 2rem;
+    font-weight: 700;
+    line-height: 1.2;
+}
+
+.kpi-label {
+    font-size: 0.75rem;
+    color: #6b7280;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-top: 0.25rem;
+}
+
+/* KPI color variations - each card type has its own color */
+.kpi-tasks .kpi-icon, .kpi-tasks .kpi-value { color: #6366f1; }
+.kpi-assigned .kpi-icon, .kpi-assigned .kpi-value { color: #10b981; }
+.kpi-violations .kpi-icon, .kpi-violations .kpi-value { color: #ef4444; }
+.kpi-score .kpi-icon, .kpi-score .kpi-value { color: #3E00FF; }
+
+/* Pulse animation when KPI value changes (applied via JavaScript) */
+.kpi-pulse {
+    animation: kpiPulse 0.5s ease;
+}
+
+@keyframes kpiPulse {
+    0%, 100% { transform: scale(1); }
+    50% { transform: scale(1.05); }
+}
+
+/* =============================================================================
+ * 5. CONTROL BAR
+ *
+ * Contains the Solve/Stop buttons and solving spinner.
+ *
+ * BUTTONS:
+ * - #solveButton: Starts the solver (POST to /schedules)
+ * - #stopSolvingButton: Stops the solver (DELETE to /schedules/{id})
+ * - #analyzeButton: Shows score breakdown (PUT to /schedules/analyze)
+ *
+ * The spinner (#solvingSpinner) animates while solving is active.
+ * ============================================================================= */
+.control-bar {
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+    padding: 1rem 1.5rem;
+}
+
+/* Solving spinner - hidden by default, shown when solving */
+#solvingSpinner {
+    display: none;
+    width: 24px;
+    height: 24px;
+    border: 3px solid #10b981;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: spin 0.75s linear infinite;
+}
+
+#solvingSpinner.active {
+    display: inline-block;
+}
+
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+
+/* =============================================================================
+ * 6. SECTION CARDS
+ *
+ * Container panels for grouping content (Resources, Tasks, etc.).
+ * Consistent styling with header and body areas.
+ * ============================================================================= */
+.section-card {
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    overflow: hidden;
+    height: 100%;
+}
+
+.section-header {
+    background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
+    padding: 1rem 1.25rem;
+    border-bottom: 1px solid #e2e8f0;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+
+.section-header h5 {
+    margin: 0;
+    font-size: 1rem;
+    font-weight: 600;
+    color: #334155;
+}
+
+.section-body {
+    padding: 1.25rem;
+}
+
+/* =============================================================================
+ * 7. TASK CARDS
+ *
+ * Visualization for planning entities (what the solver assigns).
+ *
+ * STATES:
+ * - Default (green border): Task is assigned
+ * - .unassigned (orange): Task has no resource assigned
+ * - .violation (red): Task has a constraint violation
+ *
+ * CUSTOMIZATION:
+ * Modify createTaskCard() in app.js to change what's displayed.
+ * ============================================================================= */
+.task-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+    gap: 1rem;
+}
+
+.task-card {
+    background: #f8fafc;
+    border-radius: 10px;
+    padding: 1rem;
+    border-left: 4px solid #10b981; /* Green = assigned */
+    transition: all 0.2s ease;
+}
+
+.task-card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+/* Unassigned state - yellow/orange warning */
+.task-card.unassigned {
+    border-left-color: #f59e0b;
+    background: #fffbeb;
+}
+
+/* Violation state - red error */
+.task-card.violation {
+    border-left-color: #ef4444;
+    background: #fef2f2;
+}
+
+.task-name {
+    font-weight: 600;
+    color: #1e293b;
+    margin-bottom: 0.5rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+
+.task-detail {
+    font-size: 0.8rem;
+    color: #64748b;
+    margin-bottom: 0.25rem;
+}
+
+/* Skill tag badge */
+.skill-tag {
+    display: inline-block;
+    background: #dbeafe;
+    color: #1d4ed8;
+    padding: 2px 8px;
+    border-radius: 4px;
+    font-size: 0.7rem;
+    font-weight: 500;
+}
+
+.assigned-badge {
+    color: #10b981;
+    font-weight: 500;
+}
+
+.unassigned-badge {
+    color: #9ca3af;
+    font-style: italic;
+}
+
+/* =============================================================================
+ * 8. RESOURCE CARDS
+ *
+ * Visualization for problem facts (resources that can be assigned to).
+ *
+ * FEATURES:
+ * - Blue gradient background
+ * - Capacity bar showing utilization
+ * - Skills list
+ *
+ * CUSTOMIZATION:
+ * Modify renderResources() in app.js to change the display.
+ * ============================================================================= */
+.resource-card {
+    background: linear-gradient(135deg, #eff6ff 0%, #dbeafe 100%);
+    border-radius: 10px;
+    padding: 1rem;
+    margin-bottom: 0.75rem;
+    border: 1px solid #bfdbfe;
+}
+
+.resource-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 0.5rem;
+}
+
+.resource-name {
+    font-weight: 600;
+    color: #1e40af;
+}
+
+.resource-stats {
+    font-size: 0.75rem;
+    color: #3b82f6;
+}
+
+/* Capacity utilization bar */
+.capacity-bar {
+    height: 6px;
+    background: #e2e8f0;
+    border-radius: 3px;
+    overflow: hidden;
+    margin-top: 0.5rem;
+}
+
+.capacity-fill {
+    height: 100%;
+    background: #10b981; /* Green = under capacity */
+    border-radius: 3px;
+    transition: width 0.3s ease, background 0.3s ease;
+}
+
+/* Warning/danger states for capacity */
+.capacity-fill.warning { background: #f59e0b; } /* 80-100% */
+.capacity-fill.danger { background: #ef4444; }  /* >100% overflow */
+
+.skills-list {
+    margin-top: 0.5rem;
+}
+
+/* =============================================================================
+ * 9. CONSTRAINT LEGEND
+ *
+ * Clickable badges showing active constraints from constraints.py.
+ *
+ * CONSTRAINT TYPES:
+ * - Hard (red, lock icon): Must be satisfied, violations = infeasible
+ * - Soft (green, feather icon): Optimize these, more = worse score
+ *
+ * Each badge has a data-target attribute pointing to the constraint
+ * function in constraints.py. Clicking navigates to Build tab.
+ *
+ * TODO: Update these badges to match your constraints.py definitions.
+ * ============================================================================= */
+.constraints-legend {
+    background: white;
+    border-radius: 12px;
+    padding: 1.25rem;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+}
+
+.constraint-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 8px 14px;
+    border-radius: 20px;
+    font-size: 0.85rem;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+/* Hard constraint styling - red with lock icon */
+.constraint-badge.hard {
+    background: #fef2f2;
+    color: #dc2626;
+    border: 1px solid #fecaca;
+}
+
+.constraint-badge.hard:hover {
+    background: #fecaca;
+    transform: translateY(-2px);
+}
+
+/* Soft constraint styling - green with feather icon */
+.constraint-badge.soft {
+    background: #f0fdf4;
+    color: #16a34a;
+    border: 1px solid #bbf7d0;
+}
+
+.constraint-badge.soft:hover {
+    background: #bbf7d0;
+    transform: translateY(-2px);
+}
+
+/* =============================================================================
+ * 10. BUILD TAB STYLES
+ *
+ * The Build tab is a source code viewer showing actual quickstart files.
+ *
+ * COMPONENTS:
+ * - File navigator: Tree view of project files
+ * - Code viewer: Syntax-highlighted code display
+ * - Annotations: Jump-to-section links
+ *
+ * HOW IT WORKS:
+ * 1. User clicks a file in the navigator
+ * 2. app.js loads the source code (embedded or fetched)
+ * 3. Prism.js highlights the syntax
+ * 4. Annotations show key sections to jump to
+ * ============================================================================= */
+
+/* File navigator sidebar */
+.file-nav {
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+    overflow: hidden;
+}
+
+.file-nav-header {
+    background: #f8fafc;
+    padding: 1rem;
+    border-bottom: 1px solid #e2e8f0;
+    font-weight: 600;
+    color: #334155;
+}
+
+.file-tree {
+    padding: 0.5rem;
+}
+
+.folder-item {
+    padding: 0.5rem;
+}
+
+.folder-name {
+    color: #64748b;
+    font-size: 0.85rem;
+    font-weight: 500;
+    margin-bottom: 0.25rem;
+}
+
+/* File item in the tree */
+.file-item {
+    padding: 0.5rem 0.75rem;
+    margin-left: 1rem;
+    border-radius: 6px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 0.85rem;
+    color: #475569;
+    transition: all 0.2s ease;
+}
+
+.file-item:hover {
+    background: #f1f5f9;
+}
+
+.file-item.active {
+    background: #dbeafe;
+    color: #1d4ed8;
+}
+
+.file-item i {
+    width: 16px;
+}
+
+/* File type badge */
+.file-badge {
+    margin-left: auto;
+    font-size: 0.65rem;
+    background: #f1f5f9;
+    padding: 2px 6px;
+    border-radius: 4px;
+    color: #64748b;
+}
+
+/* Main code viewer panel */
+.code-viewer {
+    background: #0f172a;
+    border-radius: 12px;
+    overflow: hidden;
+    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+
+.code-viewer-header {
+    background: #1e293b;
+    padding: 0.75rem 1rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    border-bottom: 1px solid #334155;
+}
+
+.code-path {
+    color: #94a3b8;
+    font-family: monospace;
+    font-size: 0.85rem;
+}
+
+.code-viewer-body {
+    max-height: 600px;
+    overflow-y: auto;
+}
+
+.code-viewer-body pre {
+    margin: 0 !important;
+    padding: 1rem !important;
+    background: transparent !important;
+}
+
+/* Code annotations sidebar */
+.code-annotations {
+    background: white;
+    border-radius: 12px;
+    padding: 1rem;
+    margin-top: 1rem;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+}
+
+.annotation-item {
+    padding: 0.5rem 0.75rem;
+    border-radius: 6px;
+    cursor: pointer;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    font-size: 0.85rem;
+    transition: background 0.2s;
+}
+
+.annotation-item:hover {
+    background: #f1f5f9;
+}
+
+.annotation-line {
+    color: #94a3b8;
+    font-size: 0.75rem;
+}
+
+/* =============================================================================
+ * 11. NAVIGATION OVERRIDES
+ *
+ * Custom styling for the main tab navigation.
+ * Uses pill-style buttons with rounded corners.
+ * ============================================================================= */
+.nav-main {
+    display: flex;
+    gap: 0.5rem;
+}
+
+.nav-main .nav-link {
+    border-radius: 8px;
+    padding: 0.5rem 1rem;
+    color: #475569;
+    font-weight: 500;
+    transition: all 0.2s ease;
+}
+
+.nav-main .nav-link:hover {
+    background: #f1f5f9;
+    color: #1e293b;
+}
+
+/* Active tab styling - green background */
+.nav-main .nav-link.active {
+    background: #10b981;
+    color: white;
+}
+
+.nav-main .nav-link i {
+    margin-right: 6px;
+}
+
+/* =============================================================================
+ * 12. NOTIFICATION PANEL
+ *
+ * Fixed position panel for showing notifications (errors, success messages).
+ * Positioned in top-right corner.
+ * ============================================================================= */
+#notificationPanel {
+    position: fixed;
+    top: 1rem;
+    right: 1rem;
+    z-index: 1050;
+}
+
+/* =============================================================================
+ * 13. RESPONSIVE ADJUSTMENTS
+ *
+ * Mobile-friendly modifications for smaller screens.
+ * ============================================================================= */
+@media (max-width: 768px) {
+    /* Single column task grid on mobile */
+    .task-grid {
+        grid-template-columns: 1fr;
+    }
+
+    /* Smaller KPI values */
+    .kpi-value {
+        font-size: 1.5rem;
+    }
+
+    /* Hide progress step labels on mobile */
+    .step-label {
+        display: none;
+    }
+}

static/app.js

@@ -0,0 +1,1836 @@
+/**
+ * =============================================================================
+ * SOLVERFORGE QUICKSTART TEMPLATE - APPLICATION JAVASCRIPT
+ * =============================================================================
+ *
+ * This file contains all the client-side logic for the SolverForge quickstart
+ * template. It implements a "code-link" educational UI that teaches users
+ * how to build the very interface they're looking at.
+ *
+ * FILE STRUCTURE:
+ * ---------------
+ * 1. GLOBAL STATE - Variables tracking UI state, loaded data, solving jobs
+ * 2. INITIALIZATION - Document ready handler and app setup
+ * 3. AJAX CONFIGURATION - jQuery AJAX setup and HTTP method extensions
+ * 4. DEMO DATA LOADING - Fetching and selecting sample datasets
+ * 5. SCHEDULE/SOLUTION LOADING - Getting solution data from backend
+ * 6. RENDERING - Card-based visualization of tasks and resources
+ * 7. KPI UPDATES - Key Performance Indicator card updates
+ * 8. SOLVING OPERATIONS - Start, stop, and poll the solver
+ * 9. SCORE ANALYSIS - Constraint breakdown modal
+ * 10. TAB NAVIGATION HELPERS - Programmatic tab switching
+ * 11. BUILD TAB - Source code viewer with syntax highlighting
+ * 12. INTERACTIVE CODE FEATURES - Click-to-code navigation
+ * 13. NOTIFICATIONS - Toast messages for errors and info
+ * 14. UTILITY FUNCTIONS - Helpers and formatters
+ * 15. RESOURCE & TASK CRUD - Adding and removing entities dynamically
+ * 16. CONSTRAINT WEIGHT CONTROLS - Adjusting optimization weights
+ *
+ * CUSTOMIZATION GUIDE:
+ * --------------------
+ * When adapting this template for your domain:
+ *
+ * 1. renderSolution() - Change task card layout for your entities
+ * 2. renderResources() - Change resource card layout for your facts
+ * 3. updateKPIs() - Update metrics shown in KPI cards
+ * 4. countViolations() - Implement violation detection for your constraints
+ *
+ * API ENDPOINTS USED:
+ * -------------------
+ * - GET /demo-data           - List available demo datasets
+ * - GET /demo-data/{id}      - Get a specific demo dataset
+ * - POST /schedules          - Start solving (returns job ID)
+ * - GET /schedules/{jobId}   - Get current solution
+ * - DELETE /schedules/{jobId}- Stop solving
+ * - PUT /schedules/analyze   - Analyze score breakdown
+ */
+
+
+// =============================================================================
+// 1. GLOBAL STATE
+// =============================================================================
+// These variables track the application state throughout the session.
+// They are modified by various functions and checked to determine UI behavior.
+
+/**
+ * Interval ID for auto-refreshing the solution while solving.
+ * Set by setInterval() when solving starts, cleared when solving stops.
+ * Used to poll the backend for updates every 2 seconds.
+ *
+ * @type {number|null}
+ */
+let autoRefreshIntervalId = null;
+
+/**
+ * Currently selected demo data ID (e.g., "SMALL", "MEDIUM", "LARGE").
+ * Set when user selects from the Data dropdown.
+ * Used to fetch the initial dataset before solving.
+ *
+ * @type {string|null}
+ */
+let demoDataId = null;
+
+/**
+ * Current solving job ID (UUID string from the backend).
+ * Set when solve() successfully starts a job.
+ * Used to poll for updates and stop solving.
+ *
+ * @type {string|null}
+ */
+let scheduleId = null;
+
+/**
+ * The currently loaded schedule/solution data.
+ * Contains the full problem definition and current solution:
+ * - resources: Array of resource objects (problem facts)
+ * - tasks: Array of task objects (planning entities)
+ * - score: HardSoftScore string (e.g., "0hard/-50soft")
+ * - solverStatus: "NOT_SOLVING" or "SOLVING"
+ *
+ * @type {Object|null}
+ */
+let loadedSchedule = null;
+
+/**
+ * Currently displayed file in the Build tab code viewer.
+ * Used to track which file is being shown and for copy functionality.
+ *
+ * @type {string}
+ */
+let currentFile = 'domain.py';
+
+/**
+ * Cached source code content for the current file.
+ * Populated by loadSourceFile() when fetching from API.
+ *
+ * @type {string}
+ */
+let currentFileContent = '';
+
+
+// =============================================================================
+// 2. INITIALIZATION
+// =============================================================================
+// Application startup code. Sets up event handlers and loads initial data.
+
+/**
+ * Document ready handler with safe initialization.
+ *
+ * PATTERN: Double-initialization
+ * We use both $(window).on('load') and setTimeout() to ensure initialization
+ * happens even if some external resources load slowly or fail to fire the
+ * load event.
+ *
+ * This pattern is common in SolverForge quickstarts to handle:
+ * - Slow CDN responses
+ * - Browser caching issues
+ * - Race conditions with external scripts
+ */
+$(document).ready(function () {
+    let initialized = false;
+
+    /**
+     * Safe initialization wrapper.
+     * Ensures initializeApp() is only called once.
+     */
+    function safeInitialize() {
+        if (!initialized) {
+            initialized = true;
+            initializeApp();
+        }
+    }
+
+    // Primary: Initialize when all resources (images, scripts) are loaded
+    $(window).on('load', safeInitialize);
+
+    // Fallback: Initialize after short delay if load event doesn't fire
+    setTimeout(safeInitialize, 100);
+});
+
+/**
+ * Main initialization function.
+ *
+ * Called once when the page is ready. This function:
+ * 1. Sets up button click handlers
+ * 2. Configures AJAX defaults
+ * 3. Loads the demo data list
+ * 4. Initializes the Build tab code viewer
+ * 5. Sets up code-link click handlers
+ *
+ * CUSTOMIZATION: Add your own initialization code here.
+ */
+function initializeApp() {
+    console.log('SolverForge Quickstart Template initializing...');
+
+    // =========================================================================
+    // BUTTON CLICK HANDLERS
+    // =========================================================================
+
+    // Solve button - starts the optimization
+    // Connected to solve() function which POSTs to /schedules
+    $("#solveButton").click(function () {
+        solve();
+    });
+
+    // Stop button - terminates solving early
+    // Connected to stopSolving() which DELETEs /schedules/{id}
+    $("#stopSolvingButton").click(function () {
+        stopSolving();
+    });
+
+    // Analyze button - shows score breakdown modal
+    // Connected to analyze() which PUTs to /schedules/analyze
+    $("#analyzeButton").click(function () {
+        analyze();
+    });
+
+    // =========================================================================
+    // AJAX SETUP & DATA LOADING
+    // =========================================================================
+
+    // Configure jQuery AJAX defaults (headers, methods)
+    setupAjax();
+
+    // Load the list of available demo datasets
+    fetchDemoData();
+
+    // =========================================================================
+    // BUILD TAB INITIALIZATION
+    // =========================================================================
+
+    // Set up file navigator click handlers
+    setupBuildTab();
+
+    // Load the default file (domain.py)
+    loadSourceFile('domain.py');
+
+    // =========================================================================
+    // INTERACTIVE CODE FEATURE INITIALIZATION
+    // =========================================================================
+
+    // Set up click handlers for code-link elements
+    setupCodeLinkHandlers();
+
+    console.log('Initialization complete');
+}
+
+
+// =============================================================================
+// 3. AJAX CONFIGURATION
+// =============================================================================
+// jQuery AJAX setup for communicating with the backend REST API.
+
+/**
+ * Configures jQuery AJAX with proper headers and HTTP method extensions.
+ *
+ * WHAT THIS DOES:
+ * 1. Sets default Content-Type and Accept headers for JSON
+ * 2. Adds $.put() and $.delete() methods to jQuery
+ *    (jQuery only has $.get() and $.post() by default)
+ *
+ * WHY WE NEED THIS:
+ * RESTful APIs use all HTTP methods (GET, POST, PUT, DELETE).
+ * The Accept header includes text/plain because job IDs are returned as text.
+ */
+function setupAjax() {
+    // Set default headers for all AJAX requests
+    $.ajaxSetup({
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json,text/plain', // text/plain for job ID
+        }
+    });
+
+    // Extend jQuery with PUT and DELETE methods
+    // These mirror the signature of $.get() and $.post()
+    jQuery.each(["put", "delete"], function (i, method) {
+        jQuery[method] = function (url, data, callback, type) {
+            // Handle optional parameters (data can be omitted)
+            if (jQuery.isFunction(data)) {
+                type = type || callback;
+                callback = data;
+                data = undefined;
+            }
+            return jQuery.ajax({
+                url: url,
+                type: method,
+                dataType: type,
+                data: data,
+                success: callback
+            });
+        };
+    });
+}
+
+
+// =============================================================================
+// 4. DEMO DATA LOADING
+// =============================================================================
+// Functions for loading sample datasets from the backend.
+
+/**
+ * Fetches the list of available demo datasets and populates the dropdown.
+ *
+ * FLOW:
+ * 1. GET /demo-data returns ["SMALL", "MEDIUM", "LARGE"] (or similar)
+ * 2. For each dataset, create a dropdown menu item
+ * 3. Auto-select and load the first dataset
+ *
+ * CUSTOMIZATION:
+ * The backend demo_data.py defines what datasets are available.
+ * Each dataset is a complete Schedule object with resources and tasks.
+ */
+function fetchDemoData() {
+    $.get("/demo-data", function (data) {
+        const dropdown = $("#dataDropdown");
+        dropdown.empty();
+
+        // Create a dropdown item for each available dataset
+        data.forEach(item => {
+            const menuItem = $(`
+                <li>
+                    <a class="dropdown-item" href="#" data-dataset="${item}">
+                        ${item}
+                    </a>
+                </li>
+            `);
+
+            // Click handler for this dataset
+            menuItem.find('a').click(function (e) {
+                e.preventDefault();
+
+                // Update visual selection
+                dropdown.find('.dropdown-item').removeClass('active');
+                $(this).addClass('active');
+
+                // Reset solving state and load new data
+                scheduleId = null;
+                demoDataId = item;
+
+                // Load and display the selected dataset
+                refreshSchedule();
+            });
+
+            dropdown.append(menuItem);
+        });
+
+        // Auto-select the first dataset
+        if (data.length > 0) {
+            demoDataId = data[0];
+            dropdown.find('.dropdown-item').first().addClass('active');
+            refreshSchedule();
+        }
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        // Handle case where backend is not running or has no data
+        showNotification("Failed to load demo data. Is the server running?", "danger");
+        console.error('Failed to fetch demo data:', thrownError);
+    });
+}
+
+
+// =============================================================================
+// 5. SCHEDULE/SOLUTION LOADING
+// =============================================================================
+// Functions for fetching and displaying solution data.
+
+/**
+ * Fetches and displays the current schedule/solution.
+ *
+ * LOGIC:
+ * - If scheduleId is set: GET /schedules/{scheduleId} for solving progress
+ * - If scheduleId is null: GET /demo-data/{demoDataId} for initial data
+ *
+ * WHEN CALLED:
+ * - When a dataset is selected from the dropdown
+ * - Every 2 seconds while solving (via setInterval)
+ * - After stopping solving
+ */
+function refreshSchedule() {
+    // Determine which endpoint to call
+    let path = "/schedules/" + scheduleId;
+    if (scheduleId === null) {
+        // No active job - load demo data instead
+        if (demoDataId === null) {
+            showNotification("Please select a dataset from the Data dropdown.", "warning");
+            return;
+        }
+        path = "/demo-data/" + demoDataId;
+    }
+
+    // Fetch the schedule data
+    $.getJSON(path, function (schedule) {
+        loadedSchedule = schedule;
+        renderSchedule(schedule);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showNotification("Failed to load schedule data.", "danger");
+        console.error('Failed to fetch schedule:', thrownError);
+        refreshSolvingButtons(false);
+    });
+}
+
+/**
+ * Renders the complete schedule/solution to the UI.
+ *
+ * UPDATES:
+ * - Solve/Stop button visibility
+ * - Spinner animation
+ * - KPI cards
+ * - Task cards in the tasks panel
+ * - Resource cards in the resources panel
+ *
+ * @param {Object} schedule - The schedule data from the backend
+ */
+function renderSchedule(schedule) {
+    if (!schedule) {
+        console.error('No schedule data provided to renderSchedule');
+        return;
+    }
+
+    console.log('Rendering schedule:', schedule);
+
+    // Update solving buttons based on solver status
+    const isSolving = schedule.solverStatus != null &&
+                      schedule.solverStatus !== "NOT_SOLVING";
+    refreshSolvingButtons(isSolving);
+
+    // Update KPI cards with current metrics
+    updateKPIs(schedule);
+
+    // Render the solution visualization (task cards)
+    renderSolution(schedule);
+
+    // Render the resources panel
+    renderResources(schedule);
+}
+
+
+// =============================================================================
+// 6. RENDERING - Card-Based Visualization
+// =============================================================================
+// Functions that create the visual representation of tasks and resources.
+
+/**
+ * Renders the tasks panel with card-based layout.
+ *
+ * CARD STATES:
+ * - Default (green border): Task is assigned to a resource
+ * - .unassigned (orange border): Task has no resource assigned
+ * - .violation (red border): Task has a constraint violation
+ *
+ * CUSTOMIZATION:
+ * Modify this function to match your domain model:
+ * - Change what fields are displayed
+ * - Add domain-specific badges or indicators
+ * - Implement custom violation detection
+ *
+ * @param {Object} schedule - Schedule containing tasks array
+ */
+function renderSolution(schedule) {
+    const panel = $("#tasksPanel");
+    panel.empty();
+
+    // Update task count badge
+    const taskCount = schedule.tasks ? schedule.tasks.length : 0;
+    $("#taskCount").text(taskCount);
+
+    // Handle empty state
+    if (!schedule.tasks || schedule.tasks.length === 0) {
+        panel.html('<p class="text-muted text-center">No tasks in this dataset</p>');
+        return;
+    }
+
+    // Create the task grid container
+    const grid = $('<div class="task-grid"></div>');
+
+    // Render each task as a card
+    schedule.tasks.forEach(task => {
+        const card = createTaskCard(task, schedule);
+        grid.append(card);
+    });
+
+    panel.append(grid);
+}
+
+/**
+ * Creates a single task card element.
+ *
+ * STRUCTURE:
+ * <div class="task-card [unassigned|violation] code-link">
+ *   <div class="task-name">Task Name <duration></div>
+ *   <div class="task-detail">Skill: skill_name</div>
+ *   <div class="task-detail">Assigned: resource_name</div>
+ * </div>
+ *
+ * CUSTOMIZATION:
+ * Modify this to show your domain-specific fields.
+ *
+ * @param {Object} task - The task object
+ * @param {Object} schedule - The full schedule (for violation checking)
+ * @returns {jQuery} The task card jQuery element
+ */
+function createTaskCard(task, schedule) {
+    // Determine card state
+    const isAssigned = task.resource != null;
+    const hasViolation = checkTaskViolation(task, schedule);
+
+    // Build CSS classes
+    let cardClass = 'task-card code-link';
+    if (hasViolation) {
+        cardClass += ' violation';
+    } else if (!isAssigned) {
+        cardClass += ' unassigned';
+    }
+
+    // Create the card (escaping id for onclick)
+    const escapedId = task.id.replace(/'/g, "\\'");
+    const card = $(`<div class="${cardClass}" data-target="app.js:createTaskCard"></div>`);
+
+    // Task name, duration, and remove button
+    const nameRow = $('<div class="task-name"></div>');
+    nameRow.append($('<span></span>').text(task.name));
+    const rightSide = $('<div class="d-flex align-items-center gap-2"></div>');
+    rightSide.append($('<span class="task-duration"></span>').text(`${task.duration}m`));
+    rightSide.append($(`<button class="btn btn-sm btn-outline-danger" onclick="removeTask('${escapedId}', event)" title="Remove Task"><i class="fas fa-minus"></i></button>`));
+    nameRow.append(rightSide);
+    card.append(nameRow);
+
+    // Required skill (if any)
+    if (task.requiredSkill) {
+        const skillRow = $('<div class="task-detail"></div>');
+        skillRow.append($('<span class="skill-tag"></span>').text(task.requiredSkill));
+        card.append(skillRow);
+    }
+
+    // Assignment status
+    const assignmentRow = $('<div class="task-detail"></div>');
+    if (isAssigned) {
+        assignmentRow.html(`<span class="assigned-badge"><i class="fas fa-check me-1"></i>${task.resource}</span>`);
+    } else {
+        assignmentRow.html('<span class="unassigned-badge">Unassigned</span>');
+    }
+    card.append(assignmentRow);
+
+    return card;
+}
+
+/**
+ * Checks if a task has any constraint violations.
+ *
+ * CUSTOMIZATION:
+ * Implement your domain-specific violation detection here.
+ * This example checks:
+ * - Required skill: Is the task assigned to a resource with the required skill?
+ *
+ * @param {Object} task - The task to check
+ * @param {Object} schedule - The schedule containing resources
+ * @returns {boolean} True if task has a violation
+ */
+function checkTaskViolation(task, schedule) {
+    // If not assigned, it's not a violation (just unassigned)
+    if (!task.resource) {
+        return false;
+    }
+
+    // Check required skill constraint
+    if (task.requiredSkill) {
+        const resource = schedule.resources.find(r => r.name === task.resource);
+        if (resource) {
+            // Check if resource has the required skill
+            const hasSkill = resource.skills &&
+                           resource.skills.includes(task.requiredSkill);
+            if (!hasSkill) {
+                return true; // Skill violation!
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Renders the resources panel with card-based layout.
+ *
+ * CARD STRUCTURE:
+ * - Resource name
+ * - Capacity utilization bar (color-coded)
+ * - Skills list
+ *
+ * CUSTOMIZATION:
+ * Modify this function to match your problem facts.
+ *
+ * @param {Object} schedule - Schedule containing resources array
+ */
+function renderResources(schedule) {
+    const panel = $("#resourcesPanel");
+    panel.empty();
+
+    // Update resource count badge
+    const resourceCount = schedule.resources ? schedule.resources.length : 0;
+    $("#resourceCount").text(resourceCount);
+
+    // Handle empty state
+    if (!schedule.resources || schedule.resources.length === 0) {
+        panel.html('<p class="text-muted text-center">No resources in this dataset</p>');
+        return;
+    }
+
+    // Render each resource as a card
+    schedule.resources.forEach(resource => {
+        const card = createResourceCard(resource, schedule);
+        panel.append(card);
+    });
+}
+
+/**
+ * Creates a single resource card element.
+ *
+ * FEATURES:
+ * - Capacity bar showing utilization
+ * - Color-coded: green (<80%), orange (80-100%), red (>100%)
+ * - Skills displayed as tags
+ *
+ * @param {Object} resource - The resource object
+ * @param {Object} schedule - The schedule (for calculating utilization)
+ * @returns {jQuery} The resource card jQuery element
+ */
+function createResourceCard(resource, schedule) {
+    // Calculate utilization
+    const totalDuration = schedule.tasks
+        ? schedule.tasks
+            .filter(t => t.resource === resource.name)
+            .reduce((sum, t) => sum + t.duration, 0)
+        : 0;
+    const utilization = resource.capacity > 0
+        ? (totalDuration / resource.capacity) * 100
+        : 0;
+
+    // Determine capacity bar color
+    let fillClass = '';
+    if (utilization > 100) {
+        fillClass = 'danger';
+    } else if (utilization > 80) {
+        fillClass = 'warning';
+    }
+
+    // Create skills badges HTML
+    const skillsHtml = resource.skills && resource.skills.length > 0
+        ? resource.skills.map(s => `<span class="skill-tag me-1">${s}</span>`).join('')
+        : '<span class="text-muted small">No skills</span>';
+
+    // Build the card (escaping name for onclick)
+    const escapedName = resource.name.replace(/'/g, "\\'");
+    const card = $(`
+        <div class="resource-card code-link" data-target="app.js:createResourceCard">
+            <div class="resource-header">
+                <span class="resource-name">${resource.name}</span>
+                <div class="d-flex align-items-center gap-2">
+                    <span class="resource-stats">${totalDuration}/${resource.capacity} min</span>
+                    <button class="btn btn-sm btn-outline-danger" onclick="removeResource('${escapedName}', event)" title="Remove Resource">
+                        <i class="fas fa-minus"></i>
+                    </button>
+                </div>
+            </div>
+            <div class="capacity-bar">
+                <div class="capacity-fill ${fillClass}" style="width: ${Math.min(utilization, 100)}%"></div>
+            </div>
+            <div class="skills-list mt-2">
+                ${skillsHtml}
+            </div>
+        </div>
+    `);
+
+    return card;
+}
+
+
+// =============================================================================
+// 7. KPI UPDATES
+// =============================================================================
+// Functions for updating the Key Performance Indicator cards.
+
+/**
+ * Updates all KPI cards with current metrics.
+ *
+ * KPIs DISPLAYED:
+ * - Total Tasks: Number of planning entities
+ * - Assigned: Tasks with non-null planning variable
+ * - Violations: Hard constraint violations
+ * - Score: Current HardSoftScore
+ *
+ * ANIMATION:
+ * KPI values pulse when they change (using .kpi-pulse class).
+ *
+ * CUSTOMIZATION:
+ * Modify this to show metrics relevant to your domain.
+ *
+ * @param {Object} schedule - The schedule data
+ */
+function updateKPIs(schedule) {
+    // Calculate metrics
+    const totalTasks = schedule.tasks ? schedule.tasks.length : 0;
+    const assignedTasks = schedule.tasks
+        ? schedule.tasks.filter(t => t.resource != null).length
+        : 0;
+    const violations = countViolations(schedule);
+    const score = schedule.score || '?';
+
+    // Update KPI values with pulse animation
+    updateKPIValue('#kpiTotalTasks', totalTasks);
+    updateKPIValue('#kpiAssigned', assignedTasks);
+    updateKPIValue('#kpiViolations', violations);
+    updateKPIValue('#kpiScore', formatScore(score));
+}
+
+/**
+ * Updates a single KPI value with optional pulse animation.
+ *
+ * @param {string} selector - jQuery selector for the KPI value element
+ * @param {string|number} newValue - The new value to display
+ */
+function updateKPIValue(selector, newValue) {
+    const el = $(selector);
+    const oldValue = el.text();
+
+    // Only animate if value changed
+    if (oldValue !== String(newValue)) {
+        el.text(newValue);
+        el.addClass('kpi-pulse');
+        setTimeout(() => el.removeClass('kpi-pulse'), 500);
+    }
+}
+
+/**
+ * Counts the number of hard constraint violations.
+ *
+ * CUSTOMIZATION:
+ * Implement your domain-specific violation counting here.
+ * This example counts:
+ * - Required skill violations
+ * - Capacity violations
+ *
+ * @param {Object} schedule - The schedule data
+ * @returns {number} Number of violations
+ */
+function countViolations(schedule) {
+    if (!schedule.tasks || !schedule.resources) {
+        return 0;
+    }
+
+    let violations = 0;
+
+    // Count required skill violations
+    schedule.tasks.forEach(task => {
+        if (task.resource && task.requiredSkill) {
+            const resource = schedule.resources.find(r => r.name === task.resource);
+            if (resource && resource.skills) {
+                if (!resource.skills.includes(task.requiredSkill)) {
+                    violations++;
+                }
+            }
+        }
+    });
+
+    // Count capacity violations
+    schedule.resources.forEach(resource => {
+        const totalDuration = schedule.tasks
+            .filter(t => t.resource === resource.name)
+            .reduce((sum, t) => sum + t.duration, 0);
+        if (totalDuration > resource.capacity) {
+            violations++;
+        }
+    });
+
+    return violations;
+}
+
+/**
+ * Formats a score string for display.
+ *
+ * EXAMPLES:
+ * - "0hard/-50soft" -> "0/-50"
+ * - "-2hard/-15soft" -> "-2/-15"
+ * - null -> "?"
+ *
+ * @param {string|null} score - The score string
+ * @returns {string} Formatted score
+ */
+function formatScore(score) {
+    if (!score || score === '?') {
+        return '?';
+    }
+
+    const components = getScoreComponents(score);
+
+    // Format as hard/soft
+    return `${components.hard}/${components.soft}`;
+}
+
+
+// =============================================================================
+// 8. SOLVING OPERATIONS
+// =============================================================================
+// Functions for starting, stopping, and monitoring the solver.
+
+/**
+ * Starts the optimization solver.
+ *
+ * FLOW:
+ * 1. Get current constraint weights from UI sliders
+ * 2. POST schedule + weights to /schedules
+ * 3. Backend returns a job ID (UUID)
+ * 4. Store job ID and start polling for updates
+ *
+ * POLLING:
+ * While solving, refreshSchedule() is called every 2 seconds
+ * via setInterval(). This polls GET /schedules/{jobId}.
+ */
+function solve() {
+    // Check that we have data to solve
+    if (!loadedSchedule) {
+        showNotification("No data loaded. Please select a dataset first.", "warning");
+        return;
+    }
+
+    // Get constraint weights from UI sliders
+    const constraintWeights = getConstraintWeights();
+    console.log('Constraint weights:', constraintWeights);
+
+    // Build the request payload with schedule and weights
+    const payload = {
+        ...loadedSchedule,
+        constraintWeights: constraintWeights
+    };
+
+    console.log('Starting solver with payload:', payload);
+
+    // Send the schedule to the solver
+    $.post("/schedules", JSON.stringify(payload), function (data) {
+        // Store the job ID for future requests
+        scheduleId = data;
+        console.log('Solving started, job ID:', scheduleId);
+
+        // Update UI to show solving state
+        refreshSolvingButtons(true);
+
+        showNotification("Solver started!", "success");
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showNotification("Failed to start solving: " + thrownError, "danger");
+        console.error('Failed to start solving:', xhr.responseText);
+        refreshSolvingButtons(false);
+    }, "text");
+}
+
+/**
+ * Stops the currently running solver.
+ *
+ * FLOW:
+ * 1. DELETE /schedules/{jobId}
+ * 2. Backend terminates the solver
+ * 3. Update UI to idle state
+ * 4. Refresh to show final solution
+ */
+function stopSolving() {
+    if (!scheduleId) {
+        console.warn('No active solving job to stop');
+        return;
+    }
+
+    console.log('Stopping solver, job ID:', scheduleId);
+
+    $.delete(`/schedules/${scheduleId}`, function () {
+        // Update UI to show stopped state
+        refreshSolvingButtons(false);
+
+        // Refresh to get final solution
+        refreshSchedule();
+
+        showNotification("Solver stopped", "info");
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showNotification("Failed to stop solving: " + thrownError, "danger");
+        console.error('Failed to stop solving:', xhr.responseText);
+    });
+}
+
+/**
+ * Updates the UI to reflect solving/not-solving state.
+ *
+ * WHEN SOLVING:
+ * - Hides Solve button, shows Stop button
+ * - Shows spinner animation
+ * - Starts polling for updates every 2 seconds
+ *
+ * WHEN NOT SOLVING:
+ * - Shows Solve button, hides Stop button
+ * - Hides spinner
+ * - Stops polling
+ *
+ * @param {boolean} solving - Whether solving is currently in progress
+ */
+function refreshSolvingButtons(solving) {
+    if (solving) {
+        // Solving state
+        $("#solveButton").hide();
+        $("#stopSolvingButton").show();
+        $("#solvingSpinner").addClass("active");
+
+        // Start polling for updates if not already polling
+        if (autoRefreshIntervalId == null) {
+            autoRefreshIntervalId = setInterval(refreshSchedule, 2000);
+        }
+    } else {
+        // Idle state
+        $("#solveButton").show();
+        $("#stopSolvingButton").hide();
+        $("#solvingSpinner").removeClass("active");
+
+        // Stop polling
+        if (autoRefreshIntervalId != null) {
+            clearInterval(autoRefreshIntervalId);
+            autoRefreshIntervalId = null;
+        }
+    }
+}
+
+
+// =============================================================================
+// 9. SCORE ANALYSIS
+// =============================================================================
+// Functions for displaying the score analysis modal.
+
+/**
+ * Shows the score analysis modal with constraint breakdown.
+ *
+ * FLOW:
+ * 1. Show the modal
+ * 2. PUT /schedules/analyze with current schedule
+ * 3. Render constraint breakdown table
+ *
+ * DISPLAY:
+ * - Warning icon for violated hard constraints
+ * - Check icon for satisfied constraints
+ * - Match count and score contribution
+ */
+function analyze() {
+    // Show the modal
+    const modal = new bootstrap.Modal("#scoreAnalysisModal");
+    modal.show();
+
+    const modalContent = $("#scoreAnalysisContent");
+    modalContent.html('<p class="text-center"><i class="fas fa-spinner fa-spin me-2"></i>Analyzing...</p>');
+
+    // Check if we have a score to analyze
+    if (!loadedSchedule) {
+        modalContent.html('<p class="text-muted text-center">No data loaded.</p>');
+        return;
+    }
+
+    // Update the score label in the modal header
+    $('#scoreAnalysisScore').text(loadedSchedule.score || '?');
+
+    // Fetch the score analysis from the backend
+    $.put("/schedules/analyze", JSON.stringify(loadedSchedule), function (scoreAnalysis) {
+        renderScoreAnalysis(scoreAnalysis, modalContent);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        modalContent.html('<p class="text-danger text-center">Failed to analyze score.</p>');
+        console.error('Failed to analyze score:', xhr.responseText);
+    }, "json");
+}
+
+/**
+ * Renders the score analysis table in the modal.
+ *
+ * TABLE COLUMNS:
+ * - Icon: Warning/check status
+ * - Constraint: Name of the constraint
+ * - Type: hard/soft
+ * - Matches: Number of violations
+ * - Weight: Constraint weight
+ * - Score: Score contribution
+ *
+ * @param {Object} scoreAnalysis - The analysis data from the backend
+ * @param {jQuery} container - The container element to render into
+ */
+function renderScoreAnalysis(scoreAnalysis, container) {
+    container.empty();
+
+    let constraints = scoreAnalysis.constraints || [];
+
+    if (constraints.length === 0) {
+        container.html('<p class="text-muted text-center">No constraint data available.</p>');
+        return;
+    }
+
+    // Sort constraints: violated hard constraints first, then by impact
+    constraints.sort((a, b) => {
+        let aComponents = getScoreComponents(a.score);
+        let bComponents = getScoreComponents(b.score);
+
+        // Hard constraints with negative score first
+        if (aComponents.hard < 0 && bComponents.hard >= 0) return -1;
+        if (aComponents.hard >= 0 && bComponents.hard < 0) return 1;
+
+        // Then by absolute hard score
+        if (Math.abs(aComponents.hard) !== Math.abs(bComponents.hard)) {
+            return Math.abs(bComponents.hard) - Math.abs(aComponents.hard);
+        }
+
+        // Then by soft score
+        return Math.abs(bComponents.soft) - Math.abs(aComponents.soft);
+    });
+
+    // Build the analysis table
+    let html = '<table class="table table-sm">';
+    html += `
+        <thead>
+            <tr>
+                <th></th>
+                <th>Constraint</th>
+                <th>Type</th>
+                <th>Matches</th>
+                <th>Score</th>
+            </tr>
+        </thead>
+        <tbody>
+    `;
+
+    constraints.forEach(constraint => {
+        const components = getScoreComponents(constraint.score || "0hard/0soft");
+        const isHard = components.hard !== 0;
+        const isViolated = components.hard < 0 || components.soft < 0;
+        const matchCount = constraint.matches ? constraint.matches.length : 0;
+
+        // Status icon
+        let icon = '';
+        if (isHard && components.hard < 0) {
+            icon = '<i class="fas fa-exclamation-triangle text-danger"></i>';
+        } else if (matchCount === 0) {
+            icon = '<i class="fas fa-check-circle text-success"></i>';
+        } else {
+            icon = '<i class="fas fa-minus-circle text-warning"></i>';
+        }
+
+        // Type badge
+        const typeBadge = isHard
+            ? '<span class="badge bg-danger">hard</span>'
+            : '<span class="badge bg-success">soft</span>';
+
+        // Score display
+        const scoreDisplay = isHard ? components.hard : components.soft;
+
+        html += `
+            <tr>
+                <td>${icon}</td>
+                <td>${constraint.name}</td>
+                <td>${typeBadge}</td>
+                <td><strong>${matchCount}</strong></td>
+                <td>${scoreDisplay}</td>
+            </tr>
+        `;
+    });
+
+    html += '</tbody></table>';
+    container.html(html);
+}
+
+/**
+ * Parses a score string into its component parts.
+ *
+ * EXAMPLES:
+ * - "0hard/0soft" -> {hard: 0, soft: 0}
+ * - "-2hard/-15soft" -> {hard: -2, soft: -15}
+ *
+ * @param {string} score - The score string to parse
+ * @returns {Object} Object with hard, medium, soft properties
+ */
+function getScoreComponents(score) {
+    let components = {hard: 0, medium: 0, soft: 0};
+
+    if (!score || typeof score !== 'string') {
+        return components;
+    }
+
+    // Match patterns like "-2hard", "0soft", "-5medium"
+    const matches = [...score.matchAll(/(-?\d*\.?\d+)(hard|medium|soft)/g)];
+    matches.forEach(match => {
+        components[match[2]] = parseFloat(match[1]);
+    });
+
+    return components;
+}
+
+
+// =============================================================================
+// 10. TAB NAVIGATION HELPERS
+// =============================================================================
+// Functions for switching between tabs programmatically.
+
+/**
+ * Navigates to Build tab and shows a specific file.
+ *
+ * Used by code-link elements to view source code.
+ *
+ * @param {string} filename - The file to show in the Build tab
+ */
+function showInBuild(filename) {
+    // Switch to Build tab using Bootstrap 5 API
+    const tabEl = document.querySelector('[data-bs-target="#build"]');
+    if (tabEl) {
+        const tab = new bootstrap.Tab(tabEl);
+        tab.show();
+    }
+
+    // Load the requested file after a short delay to ensure tab is visible
+    setTimeout(() => {
+        loadSourceFile(filename);
+    }, 100);
+}
+
+/**
+ * Navigates from Build tab to Demo tab.
+ *
+ * Used by "See in Demo" button in the code viewer.
+ */
+function showInDemo() {
+    // Switch to Demo tab using Bootstrap 5 API
+    const tabEl = document.querySelector('[data-bs-target="#demo"]');
+    if (tabEl) {
+        const tab = new bootstrap.Tab(tabEl);
+        tab.show();
+    }
+}
+
+
+// =============================================================================
+// 11. BUILD TAB - Source Code Viewer
+// =============================================================================
+// Functions for the source code viewer with syntax highlighting.
+
+/**
+ * Sets up click handlers for the file navigator.
+ */
+function setupBuildTab() {
+    // File item click handlers
+    $('.file-item').click(function() {
+        const filename = $(this).data('file');
+        if (filename) {
+            // Update active state
+            $('.file-item').removeClass('active');
+            $(this).addClass('active');
+
+            // Load the file
+            loadSourceFile(filename);
+        }
+    });
+}
+
+/**
+ * Loads and displays a source file in the code viewer.
+ *
+ * FLOW:
+ * 1. Fetch source code from /source-code/{filename} API
+ * 2. Update the code viewer header with file path
+ * 3. Set the code content and language class
+ * 4. Trigger Prism.js highlighting
+ * 5. If section is provided, find its line number and scroll to it
+ *
+ * RUNTIME LINE DETECTION:
+ * When a section name is provided (e.g., "updateKPIs"), we search the loaded
+ * content for patterns that indicate where that section is defined:
+ * - Python: "def section_name" or "class SectionName"
+ * - JavaScript: "function sectionName" or "sectionName(" or "const sectionName"
+ *
+ * This approach is more robust than hardcoded line numbers because:
+ * - Line numbers change as code is edited
+ * - Different environments might have different line endings
+ * - The search adapts to the actual file content at runtime
+ *
+ * @param {string} filename - The file to load
+ * @param {string} [section] - Optional section/function name to scroll to
+ */
+function loadSourceFile(filename, section = null) {
+    console.log('Loading source file:', filename, section ? `(section: ${section})` : '');
+    currentFile = filename;
+
+    // Determine language for syntax highlighting based on file extension
+    // Prism.js uses different language identifiers for different file types
+    let language = 'python';
+    if (filename.endsWith('.js')) {
+        language = 'javascript';
+    } else if (filename.endsWith('.html')) {
+        language = 'markup';  // Prism uses 'markup' for HTML
+    }
+
+    // Update header with file path and appropriate icon
+    const icon = language === 'python' ? 'fab fa-python'
+               : language === 'javascript' ? 'fab fa-js'
+               : 'fab fa-html5';
+    const path = filename.endsWith('.py')
+        ? `src/my_quickstart/${filename}`
+        : `static/${filename}`;
+
+    $('#currentFilePath').html(`<i class="${icon} me-2"></i>${path}`);
+
+    // Show loading state while fetching
+    const codeEl = $('#codeContent');
+    codeEl.text('Loading...');
+
+    // Fetch source code from API
+    // The /source-code/{filename} endpoint returns {filename, content}
+    $.getJSON(`/source-code/${filename}`, function(data) {
+        currentFileContent = data.content || '// File not found';
+
+        // Update code content in the <code> element
+        codeEl.text(currentFileContent);
+        codeEl.attr('class', `language-${language}`);
+
+        // Trigger Prism.js syntax highlighting
+        // This transforms plain text into highlighted HTML with line numbers
+        if (typeof Prism !== 'undefined') {
+            Prism.highlightElement(codeEl[0]);
+        }
+
+        // RUNTIME LINE DETECTION: If a section was requested, find and scroll to it
+        // We do this AFTER Prism highlighting because:
+        // 1. The content needs to be rendered before we can scroll
+        // 2. Prism adds line-numbers-rows elements we use for accurate scrolling
+        if (section) {
+            // Small delay to ensure Prism.js has finished rendering line numbers
+            // Prism's highlightElement is synchronous, but DOM updates need a tick
+            setTimeout(() => {
+                const lineNumber = findSectionLineNumber(currentFileContent, section, language);
+                if (lineNumber > 0) {
+                    console.log(`Found "${section}" at line ${lineNumber}`);
+                    scrollToLine(lineNumber);
+                } else {
+                    console.warn(`Section "${section}" not found in ${filename}`);
+                }
+            }, 50);
+        }
+
+    }).fail(function(xhr, status, error) {
+        console.error('Failed to load source file:', error);
+        codeEl.text('// Error loading file: ' + error);
+        currentFileContent = '';
+    });
+}
+
+
+/**
+ * Finds the line number where a section (function/class) is defined.
+ *
+ * RUNTIME LINE DETECTION EXPLAINED:
+ * ---------------------------------
+ * This is the core of our "smart scroll" feature. Instead of hardcoding line
+ * numbers (which break when code changes), we search the actual file content
+ * at runtime to find where a function or class is defined.
+ *
+ * HOW IT WORKS:
+ * 1. Split the file content into lines
+ * 2. Build regex patterns based on the language and section name
+ * 3. Search each line for a match
+ * 4. Return the 1-based line number (or 0 if not found)
+ *
+ * PATTERNS SEARCHED:
+ * - Python:     "def section_name(" or "class SectionName"
+ * - JavaScript: "function sectionName(" or "sectionName = function"
+ *               or "const/let/var sectionName" or "sectionName(" at definition
+ *
+ * WHY THIS APPROACH:
+ * - Resilient: Works even as code is edited and line numbers change
+ * - Flexible: Can find functions, classes, or any named definition
+ * - Language-aware: Uses appropriate patterns for Python vs JavaScript
+ *
+ * TRADE-OFFS:
+ * - May not find minified code or unusual formatting
+ * - Could match wrong occurrence if same name appears multiple times
+ *   (we return the FIRST match, which is usually the definition)
+ *
+ * @param {string} content - The full file content
+ * @param {string} sectionName - The function/class name to find
+ * @param {string} language - The file language ('python', 'javascript', 'markup')
+ * @returns {number} 1-based line number, or 0 if not found
+ */
+function findSectionLineNumber(content, sectionName, language) {
+    if (!content || !sectionName) {
+        return 0;
+    }
+
+    // Split content into lines for line-by-line search
+    const lines = content.split('\n');
+
+    // Build search patterns based on language
+    // We use multiple patterns to catch different definition styles
+    const patterns = [];
+
+    if (language === 'python') {
+        // Python patterns:
+        // - "def function_name(" - function definition
+        // - "class ClassName" - class definition (may or may not have parens)
+        // - "@decorator" followed by def - decorated functions
+        patterns.push(new RegExp(`^\\s*def\\s+${sectionName}\\s*\\(`));
+        patterns.push(new RegExp(`^\\s*class\\s+${sectionName}\\b`));
+        patterns.push(new RegExp(`^\\s*async\\s+def\\s+${sectionName}\\s*\\(`));
+    } else if (language === 'javascript') {
+        // JavaScript patterns:
+        // - "function functionName(" - classic function declaration
+        // - "functionName = function" - function expression
+        // - "const/let/var functionName" - modern declaration
+        // - "functionName(" in object/class context
+        // - "async function" variants
+        patterns.push(new RegExp(`^\\s*function\\s+${sectionName}\\s*\\(`));
+        patterns.push(new RegExp(`^\\s*async\\s+function\\s+${sectionName}\\s*\\(`));
+        patterns.push(new RegExp(`^\\s*(const|let|var)\\s+${sectionName}\\s*=`));
+        patterns.push(new RegExp(`^\\s*${sectionName}\\s*[:=]\\s*(async\\s+)?function`));
+        patterns.push(new RegExp(`^\\s*${sectionName}\\s*\\(`));  // Method shorthand
+    } else {
+        // HTML/markup: search for id or class attributes
+        patterns.push(new RegExp(`id=["']${sectionName}["']`));
+        patterns.push(new RegExp(`class=["'][^"']*${sectionName}[^"']*["']`));
+    }
+
+    // Search each line for any of our patterns
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of patterns) {
+            if (pattern.test(line)) {
+                // Return 1-based line number (lines array is 0-indexed)
+                return i + 1;
+            }
+        }
+    }
+
+    // Fallback: simple substring search for the section name
+    // This catches cases our patterns missed (e.g., comments mentioning the section)
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(sectionName)) {
+            console.log(`Fallback match for "${sectionName}" at line ${i + 1}`);
+            return i + 1;
+        }
+    }
+
+    return 0;  // Not found
+}
+
+
+/**
+ * Scrolls the code viewer to a specific line.
+ *
+ * Uses multiple approaches to accurately scroll to a line:
+ * 1. Try to find Prism.js line-numbers-rows spans
+ * 2. Fall back to measuring line height from rendered code
+ *
+ * @param {number} lineNumber - The line to scroll to
+ */
+function scrollToLine(lineNumber) {
+    const viewer = $('.code-viewer-body');
+    const preEl = viewer.find('pre')[0];
+    const codeEl = viewer.find('code')[0];
+
+    if (!preEl || !codeEl) {
+        console.warn('No code element found for scrolling');
+        return;
+    }
+
+    let offset = 0;
+
+    // Method 1: Try to use Prism.js line-numbers-rows spans
+    const lineNumbersRows = preEl.querySelector('.line-numbers-rows');
+    if (lineNumbersRows && lineNumbersRows.children.length > 0) {
+        // Get the height of a single line number span
+        const firstLineSpan = lineNumbersRows.children[0];
+        if (firstLineSpan) {
+            const lineHeight = firstLineSpan.getBoundingClientRect().height;
+            offset = (lineNumber - 1) * lineHeight;
+            console.log(`Using line-numbers-rows method: lineHeight=${lineHeight}px, offset=${offset}px`);
+        }
+    }
+
+    // Method 2: Fall back to measuring from pre element
+    if (offset === 0) {
+        const preStyle = window.getComputedStyle(preEl);
+        let lineHeight = parseFloat(preStyle.lineHeight);
+
+        // If lineHeight is 'normal', compute from font size
+        if (isNaN(lineHeight) || lineHeight <= 0) {
+            const fontSize = parseFloat(preStyle.fontSize) || 14;
+            lineHeight = fontSize * 1.5;
+        }
+
+        offset = (lineNumber - 1) * lineHeight;
+        console.log(`Using fallback method: lineHeight=${lineHeight}px, offset=${offset}px`);
+    }
+
+    // Add padding offset from the pre element
+    const preStyle = window.getComputedStyle(preEl);
+    const paddingTop = parseFloat(preStyle.paddingTop) || 0;
+    offset += paddingTop;
+
+    // Animate scroll with some padding above the target line
+    const viewerHeight = viewer.height();
+    const scrollTarget = Math.max(0, offset - (viewerHeight * 0.2));
+
+    viewer.animate({
+        scrollTop: scrollTarget
+    }, 300);
+
+    console.log(`Scrolling to line ${lineNumber}, final offset ${scrollTarget}px`);
+
+    // Highlight the line briefly
+    highlightLine(lineNumber);
+}
+
+/**
+ * Briefly highlights a line in the code viewer.
+ *
+ * @param {number} lineNumber - The line to highlight
+ */
+function highlightLine(lineNumber) {
+    // Remove any existing highlights
+    $('.line-highlight').remove();
+
+    const viewer = $('.code-viewer-body');
+    const preEl = viewer.find('pre')[0];
+
+    if (!preEl) return;
+
+    // Get line height
+    const lineNumbersRows = preEl.querySelector('.line-numbers-rows');
+    let lineHeight = 21; // default
+
+    if (lineNumbersRows && lineNumbersRows.children.length > 0) {
+        lineHeight = lineNumbersRows.children[0].getBoundingClientRect().height;
+    }
+
+    const preStyle = window.getComputedStyle(preEl);
+    const paddingTop = parseFloat(preStyle.paddingTop) || 0;
+
+    // Create highlight element
+    const highlight = $('<div class="line-highlight"></div>');
+    highlight.css({
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        top: paddingTop + (lineNumber - 1) * lineHeight,
+        height: lineHeight,
+        background: 'rgba(62, 0, 255, 0.15)',
+        borderLeft: '3px solid #3E00FF',
+        pointerEvents: 'none',
+        zIndex: 10
+    });
+
+    // Add to pre element (needs relative positioning)
+    $(preEl).css('position', 'relative').append(highlight);
+
+    // Fade out after 2 seconds
+    setTimeout(() => {
+        highlight.fadeOut(500, function() {
+            $(this).remove();
+        });
+    }, 2000);
+}
+
+/**
+ * Copies the current code to clipboard.
+ */
+function copyCurrentCode() {
+    const code = currentFileContent || '';
+
+    if (!code) {
+        showNotification('No code loaded to copy', 'warning');
+        return;
+    }
+
+    navigator.clipboard.writeText(code).then(() => {
+        showNotification('Code copied to clipboard!', 'success');
+    }).catch(err => {
+        console.error('Failed to copy:', err);
+        showNotification('Failed to copy code', 'danger');
+    });
+}
+
+
+// =============================================================================
+// 12. INTERACTIVE CODE FEATURES - Click-to-Code Navigation
+// =============================================================================
+// The "code-link" feature: clicking UI elements reveals their source code.
+
+/**
+ * Sets up click handlers for code-link elements.
+ *
+ * Elements with class="code-link" and data-target="file:section"
+ * will navigate to the Build tab and highlight the relevant code.
+ *
+ * EXAMPLES:
+ * - data-target="app.js:updateKPIs" -> app.js, scrolls to updateKPIs function
+ * - data-target="constraints.py:required_skill" -> constraints.py
+ */
+function setupCodeLinkHandlers() {
+    // Main code-link elements
+    $(document).on('click', '.code-link', function(e) {
+        // Don't trigger for nested clickable elements
+        if ($(e.target).closest('.btn').length > 0) {
+            return; // Let button clicks work normally
+        }
+
+        const target = $(this).data('target');
+        if (target) {
+            navigateToCode(target);
+        }
+    });
+
+    // Constraint badges
+    $(document).on('click', '.constraint-badge', function(e) {
+        e.stopPropagation();
+        const target = $(this).data('target');
+        if (target) {
+            navigateToCode(target);
+        }
+    });
+}
+
+/**
+ * Navigates to a specific code location from an code-link target.
+ *
+ * TARGET FORMAT: "filename:section"
+ * - filename: The file to show (e.g., "app.js", "constraints.py")
+ * - section: Optional section/function name to scroll to (e.g., "updateKPIs")
+ *
+ * RUNTIME LINE DETECTION:
+ * Unlike static line numbers that would break when code changes, this function
+ * uses runtime search to find the section. After the file loads from the API,
+ * we search the actual content for the section name (function/class definition)
+ * and scroll to where it's found. This keeps code-links working even as code evolves.
+ *
+ * @param {string} target - The target in "file:section" format
+ */
+function navigateToCode(target) {
+    console.log('Navigating to code:', target);
+
+    // Parse target: "filename:section" -> ["filename", "section"]
+    // The section is optional - if not provided, we just show the file from the top
+    const [filename, section] = target.split(':');
+
+    // Switch to Build tab using Bootstrap 5 Tab API
+    // We access the nav-link element and create a Tab instance to show it
+    const tabEl = document.querySelector('[data-bs-target="#build"]');
+    if (tabEl) {
+        const tab = new bootstrap.Tab(tabEl);
+        tab.show();
+    }
+
+    // Load the file after a short delay to ensure tab transition completes
+    // The delay is needed because Bootstrap's tab.show() is asynchronous
+    setTimeout(() => {
+        // Update file navigator active state for visual feedback
+        $('.file-item').removeClass('active');
+        $(`.file-item[data-file="${filename}"]`).addClass('active');
+
+        // Load the file, passing the section name for line scrolling
+        // If section is provided, loadSourceFile will search for it after loading
+        loadSourceFile(filename, section);
+    }, 100);
+
+    // Show notification with file and section info
+    const sectionInfo = section ? ` → ${section}` : '';
+    showNotification(`Viewing ${filename}${sectionInfo}`, 'info');
+}
+
+
+// =============================================================================
+// 13. NOTIFICATIONS
+// =============================================================================
+// Toast-style notification messages.
+
+/**
+ * Shows a notification toast message.
+ *
+ * TYPES:
+ * - 'success': Green checkmark
+ * - 'danger': Red X
+ * - 'warning': Yellow warning
+ * - 'info': Blue info
+ *
+ * @param {string} message - The message to display
+ * @param {string} type - The notification type (success, danger, warning, info)
+ */
+function showNotification(message, type = 'info') {
+    const panel = $('#notificationPanel');
+
+    // Create the toast
+    const toast = $(`
+        <div class="alert alert-${type} alert-dismissible fade show" role="alert">
+            ${message}
+            <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+        </div>
+    `);
+
+    panel.append(toast);
+
+    // Auto-dismiss after 5 seconds
+    setTimeout(() => {
+        toast.alert('close');
+    }, 5000);
+}
+
+
+// =============================================================================
+// 14. UTILITY FUNCTIONS
+// =============================================================================
+// Helper functions used throughout the application.
+
+/**
+ * Escapes HTML special characters to prevent XSS.
+ *
+ * @param {string} text - The text to escape
+ * @returns {string} Escaped text safe for HTML insertion
+ */
+function escapeHtml(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+}
+// =============================================================================
+// 15. RESOURCE & TASK CRUD OPERATIONS
+// =============================================================================
+// Functions for adding and removing resources and tasks dynamically.
+
+/**
+ * Shows the Add Resource modal dialog.
+ *
+ * @param {Event} event - Click event (to stop propagation)
+ */
+function showAddResourceModal(event) {
+    event.stopPropagation();
+
+    // Clear previous values
+    $('#resourceName').val('');
+    $('#resourceCapacity').val(100);
+    $('#resourceSkills').val('');
+
+    // Show modal
+    const modal = new bootstrap.Modal('#addResourceModal');
+    modal.show();
+}
+
+/**
+ * Adds a new resource to the schedule.
+ *
+ * Reads values from the Add Resource modal form and adds
+ * a new resource to loadedSchedule.resources.
+ */
+function addResource() {
+    const name = $('#resourceName').val().trim();
+    const capacity = parseInt($('#resourceCapacity').val()) || 100;
+    const skillsStr = $('#resourceSkills').val().trim();
+    const skills = skillsStr ? skillsStr.split(',').map(s => s.trim().toLowerCase()) : [];
+
+    // Validate
+    if (!name) {
+        showNotification('Please enter a resource name', 'warning');
+        return;
+    }
+
+    // Check for duplicate
+    if (loadedSchedule && loadedSchedule.resources) {
+        if (loadedSchedule.resources.some(r => r.name === name)) {
+            showNotification('A resource with this name already exists', 'warning');
+            return;
+        }
+    }
+
+    // Initialize schedule if needed
+    if (!loadedSchedule) {
+        loadedSchedule = { resources: [], tasks: [] };
+    }
+    if (!loadedSchedule.resources) {
+        loadedSchedule.resources = [];
+    }
+
+    // Add the resource
+    loadedSchedule.resources.push({
+        name: name,
+        capacity: capacity,
+        skills: skills
+    });
+
+    // Close modal and re-render
+    bootstrap.Modal.getInstance('#addResourceModal').hide();
+    renderSchedule(loadedSchedule);
+    showNotification(`Added resource: ${name}`, 'success');
+}
+
+/**
+ * Removes a resource from the schedule.
+ *
+ * @param {string} resourceName - Name of the resource to remove
+ * @param {Event} event - Click event (to stop propagation)
+ */
+function removeResource(resourceName, event) {
+    event.stopPropagation();
+
+    if (!loadedSchedule || !loadedSchedule.resources) {
+        return;
+    }
+
+    // Remove the resource
+    loadedSchedule.resources = loadedSchedule.resources.filter(r => r.name !== resourceName);
+
+    // Unassign any tasks assigned to this resource
+    if (loadedSchedule.tasks) {
+        loadedSchedule.tasks.forEach(task => {
+            if (task.resource === resourceName) {
+                task.resource = null;
+            }
+        });
+    }
+
+    // Re-render
+    renderSchedule(loadedSchedule);
+    showNotification(`Removed resource: ${resourceName}`, 'info');
+}
+
+/**
+ * Shows the Add Task modal dialog.
+ *
+ * @param {Event} event - Click event (to stop propagation)
+ */
+function showAddTaskModal(event) {
+    event.stopPropagation();
+
+    // Clear previous values
+    $('#taskName').val('');
+    $('#taskDuration').val(30);
+    $('#taskSkill').val('');
+
+    // Show modal
+    const modal = new bootstrap.Modal('#addTaskModal');
+    modal.show();
+}
+
+/**
+ * Adds a new task to the schedule.
+ *
+ * Reads values from the Add Task modal form and adds
+ * a new task to loadedSchedule.tasks.
+ */
+function addTask() {
+    const name = $('#taskName').val().trim();
+    const duration = parseInt($('#taskDuration').val()) || 30;
+    const requiredSkill = $('#taskSkill').val().trim().toLowerCase();
+
+    // Validate
+    if (!name) {
+        showNotification('Please enter a task name', 'warning');
+        return;
+    }
+
+    // Initialize schedule if needed
+    if (!loadedSchedule) {
+        loadedSchedule = { resources: [], tasks: [] };
+    }
+    if (!loadedSchedule.tasks) {
+        loadedSchedule.tasks = [];
+    }
+
+    // Generate unique ID
+    const existingIds = loadedSchedule.tasks.map(t => t.id);
+    let newId = `task-${loadedSchedule.tasks.length + 1}`;
+    let counter = loadedSchedule.tasks.length + 1;
+    while (existingIds.includes(newId)) {
+        counter++;
+        newId = `task-${counter}`;
+    }
+
+    // Add the task
+    loadedSchedule.tasks.push({
+        id: newId,
+        name: name,
+        duration: duration,
+        requiredSkill: requiredSkill || '',
+        resource: null
+    });
+
+    // Close modal and re-render
+    bootstrap.Modal.getInstance('#addTaskModal').hide();
+    renderSchedule(loadedSchedule);
+    showNotification(`Added task: ${name}`, 'success');
+}
+
+/**
+ * Removes a task from the schedule.
+ *
+ * @param {string} taskId - ID of the task to remove
+ * @param {Event} event - Click event (to stop propagation)
+ */
+function removeTask(taskId, event) {
+    event.stopPropagation();
+
+    if (!loadedSchedule || !loadedSchedule.tasks) {
+        return;
+    }
+
+    // Find task name for notification
+    const task = loadedSchedule.tasks.find(t => t.id === taskId);
+    const taskName = task ? task.name : taskId;
+
+    // Remove the task
+    loadedSchedule.tasks = loadedSchedule.tasks.filter(t => t.id !== taskId);
+
+    // Re-render
+    renderSchedule(loadedSchedule);
+    showNotification(`Removed task: ${taskName}`, 'info');
+}
+
+
+// =============================================================================
+// 16. CONSTRAINT WEIGHT CONTROLS
+// =============================================================================
+// Functions for adjusting constraint weights via sliders.
+
+/**
+ * Default constraint weight values.
+ * Hard constraints default to 100, soft constraints to 50.
+ */
+const DEFAULT_WEIGHTS = {
+    RequiredSkill: 100,
+    ResourceCapacity: 100,
+    MinimizeDuration: 50,
+    BalanceLoad: 50
+};
+
+/**
+ * Updates the displayed value for a constraint weight slider.
+ *
+ * Called by oninput on each slider.
+ *
+ * @param {string} constraintName - Name of the constraint (e.g., "RequiredSkill")
+ */
+function updateWeightDisplay(constraintName) {
+    const value = $(`#weight${constraintName}`).val();
+    $(`#weight${constraintName}Value`).text(value);
+}
+
+/**
+ * Resets all constraint weights to their default values.
+ */
+function resetConstraintWeights() {
+    Object.keys(DEFAULT_WEIGHTS).forEach(name => {
+        $(`#weight${name}`).val(DEFAULT_WEIGHTS[name]);
+        $(`#weight${name}Value`).text(DEFAULT_WEIGHTS[name]);
+    });
+    showNotification('Constraint weights reset to defaults', 'info');
+}
+
+/**
+ * Gets the current constraint weights from the sliders.
+ *
+ * @returns {Object} Object with constraint names and their weights (0-100)
+ */
+function getConstraintWeights() {
+    return {
+        required_skill: parseInt($('#weightRequiredSkill').val()) || 100,
+        resource_capacity: parseInt($('#weightResourceCapacity').val()) || 100,
+        minimize_duration: parseInt($('#weightMinimizeDuration').val()) || 50,
+        balance_load: parseInt($('#weightBalanceLoad').val()) || 50
+    };
+}

static/index.html

@@ -0,0 +1,856 @@
+<!DOCTYPE html>
+<html lang="en">
+<!--
+================================================================================
+SOLVERFORGE QUICKSTART TEMPLATE - index.html
+================================================================================
+
+This is an interactive educational UI template. It serves two purposes:
+1. A working UI for your SolverForge optimization problem
+2. A teaching tool that shows how to build itself
+
+HOW TO CUSTOMIZE THIS TEMPLATE:
+1. Replace "Task Assignment Solver" with your problem name
+2. Update the KPI cards to match your domain metrics
+3. Modify the task/resource rendering to match your entities
+4. Update constraint badges to match your constraints.py
+
+STRUCTURE:
+- <head>: CSS dependencies and custom styles
+- <body>:
+  - Header with logo and navigation
+  - Demo tab: Live solver visualization
+  - Build tab: Source code viewer
+  - Guide tab: cURL examples
+  - API tab: Swagger UI
+
+INTERACTIVE CODE LINKS:
+Elements with class="code-link" and data-target="file:section"
+will show a code icon on hover. Clicking navigates to the Build tab and
+highlights the relevant source code - helping you learn by exploring.
+================================================================================
+-->
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+    <!-- =======================================================================
+         PAGE TITLE
+         TODO: Change this to match your quickstart name
+         ======================================================================= -->
+    <title>SolverForge Quickstart Template - Learn by Building</title>
+
+    <!-- =======================================================================
+         CSS DEPENDENCIES
+
+         Required libraries:
+         - Bootstrap 5.3: Layout, components, utilities
+         - Font Awesome 6.5: Icons
+         - Prism.js Tomorrow theme: Syntax highlighting for code viewer
+         - SolverForge webui.css: Brand colors and standard styles
+
+         TIP: These are loaded from CDN for simplicity. In production, you may
+         want to bundle them locally for offline use.
+         ======================================================================= -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/css/bootstrap.min.css"/>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css"/>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css"/>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/line-numbers/prism-line-numbers.min.css"/>
+    <link rel="stylesheet" href="/webjars/solverforge/css/solverforge-webui.css"/>
+    <link rel="stylesheet" href="/app.css"/>
+    <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
+</head>
+
+<body>
+
+<!--
+================================================================================
+HEADER
+================================================================================
+
+The header contains:
+1. SolverForge logo (links to solverforge.org)
+2. Main navigation tabs (Demo, Learn, Build, Guide, API)
+3. Data dropdown (populated by app.js from /demo-data endpoint)
+
+CUSTOMIZATION:
+- The logo is loaded from /webjars/solverforge/img/
+- Navigation uses Bootstrap 5 pills with custom .nav-main styling
+- Add/remove tabs by modifying the <ul class="nav"> list
+================================================================================
+-->
+<header class="bg-white shadow-sm">
+    <div class="container-fluid py-3">
+        <div class="d-flex justify-content-between align-items-center flex-wrap gap-3">
+
+            <!-- Logo - Links to SolverForge homepage -->
+            <a href="https://www.solverforge.org" class="text-decoration-none">
+                <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge" height="40">
+            </a>
+
+            <!--
+            NAVIGATION TABS
+
+            Each tab corresponds to a .tab-pane in the main content area.
+            Bootstrap's data-bs-toggle="pill" handles tab switching.
+
+            TO ADD A NEW TAB:
+            1. Add a new <li class="nav-item"> here
+            2. Add a matching <div class="tab-pane" id="your-tab"> below
+            -->
+            <ul class="nav nav-main" role="tablist">
+                <li class="nav-item">
+                    <button class="nav-link active" data-bs-toggle="pill" data-bs-target="#demo">
+                        <i class="fas fa-play-circle"></i>Demo
+                    </button>
+                </li>
+                <li class="nav-item">
+                    <button class="nav-link" data-bs-toggle="pill" data-bs-target="#build">
+                        <i class="fas fa-code"></i>Build
+                    </button>
+                </li>
+                <li class="nav-item">
+                    <button class="nav-link" data-bs-toggle="pill" data-bs-target="#guide">
+                        <i class="fas fa-book"></i>Guide
+                    </button>
+                </li>
+                <li class="nav-item">
+                    <button class="nav-link" data-bs-toggle="pill" data-bs-target="#api">
+                        <i class="fas fa-plug"></i>API
+                    </button>
+                </li>
+            </ul>
+
+            <!--
+            DATA DROPDOWN
+
+            Populated by app.js from the /demo-data endpoint.
+            Each item loads a different sample dataset.
+
+            See: loadDemoData() in app.js
+            -->
+            <div class="dropdown">
+                <button class="btn btn-success dropdown-toggle" type="button" data-bs-toggle="dropdown">
+                    <i class="fas fa-database me-1"></i>Data
+                </button>
+                <ul class="dropdown-menu" id="dataDropdown">
+                    <!-- Items added by app.js - see loadDemoData() -->
+                </ul>
+            </div>
+        </div>
+    </div>
+</header>
+
+<!--
+================================================================================
+NOTIFICATION PANEL
+================================================================================
+
+Fixed-position container for toast notifications.
+Use showNotification(message, type) from app.js to display messages.
+
+Types: 'success', 'danger', 'warning', 'info'
+================================================================================
+-->
+<div id="notificationPanel"></div>
+
+<!--
+================================================================================
+MAIN CONTENT - TAB PANELS
+================================================================================
+
+Each tab-pane corresponds to a navigation tab above.
+Bootstrap handles showing/hiding based on which tab is active.
+================================================================================
+-->
+<div class="tab-content p-4">
+
+    <!--
+    ===========================================================================
+    DEMO TAB
+    ===========================================================================
+
+    The main interactive solver visualization.
+
+    SECTIONS:
+    1. Hero: Problem title and description
+    2. KPIs: Key metrics (tasks, assigned, violations, score)
+    3. Control Bar: Solve/Stop buttons
+    4. Resources Panel: List of available resources
+    5. Tasks Panel: Grid of tasks with assignments
+    6. Constraints Legend: Clickable constraint badges
+
+    INTERACTIVE CODE FEATURE:
+    All major elements have class="code-link" and data-target
+    attributes. Clicking reveals the source code that generates them.
+    ===========================================================================
+    -->
+    <div class="tab-pane fade show active" id="demo">
+
+        <!--
+        HERO SECTION
+
+        The prominent banner introducing your optimization problem.
+
+        TODO: Customize these values for your domain:
+        - Change the icon (fa-project-diagram) to match your problem
+        - Update the title (Task Assignment Solver)
+        - Modify the description text
+
+        INTERACTIVE CODE: data-target="index.html:hero-section" links to this HTML
+        -->
+        <div class="hero-section mb-4 code-link" data-target="index.html:hero-section">
+            <span class="code-tooltip">Click to view HTML code</span>
+            <span class="hero-badge"><i class="fas fa-flask me-1"></i>Interactive Demo</span>
+            <h1 class="text-white mb-2">
+                <i class="fas fa-project-diagram me-2"></i>Task Assignment Solver
+            </h1>
+            <p class="text-white-50 mb-0">
+                Assign tasks to resources while respecting skill requirements and capacity constraints.
+                <strong class="text-white">Click any element</strong> to see its source code.
+            </p>
+        </div>
+
+        <!--
+        KPI CARDS
+
+        Display key metrics about the current solution.
+
+        DEFAULT KPIs (customize for your domain):
+        - kpiTotalTasks: Total planning entities
+        - kpiAssigned: Entities with assigned planning variable
+        - kpiViolations: Hard constraint violations
+        - kpiScore: HardSoftScore string
+
+        Each card has code-link pointing to updateKPIs() in app.js.
+
+        TO ADD A NEW KPI:
+        1. Add a new col-6 col-md-3 div here
+        2. Update updateKPIs() in app.js to populate it
+        -->
+        <div class="row g-3 mb-4">
+            <!-- Total Tasks KPI -->
+            <div class="col-6 col-md-3">
+                <div class="kpi-card kpi-tasks code-link" data-target="app.js:updateKPIs">
+                    <span class="code-tooltip">updateKPIs() in app.js</span>
+                    <div class="kpi-icon"><i class="fas fa-tasks"></i></div>
+                    <div class="kpi-value" id="kpiTotalTasks">0</div>
+                    <div class="kpi-label">Total Tasks</div>
+                </div>
+            </div>
+
+            <!-- Assigned Tasks KPI -->
+            <div class="col-6 col-md-3">
+                <div class="kpi-card kpi-assigned code-link" data-target="app.js:updateKPIs">
+                    <span class="code-tooltip">updateKPIs() in app.js</span>
+                    <div class="kpi-icon"><i class="fas fa-check-circle"></i></div>
+                    <div class="kpi-value" id="kpiAssigned">0</div>
+                    <div class="kpi-label">Assigned</div>
+                </div>
+            </div>
+
+            <!-- Violations KPI -->
+            <div class="col-6 col-md-3">
+                <div class="kpi-card kpi-violations code-link" data-target="app.js:countViolations">
+                    <span class="code-tooltip">countViolations() in app.js</span>
+                    <div class="kpi-icon"><i class="fas fa-exclamation-triangle"></i></div>
+                    <div class="kpi-value" id="kpiViolations">0</div>
+                    <div class="kpi-label">Violations</div>
+                </div>
+            </div>
+
+            <!-- Score KPI -->
+            <div class="col-6 col-md-3">
+                <div class="kpi-card kpi-score code-link" data-target="app.js:renderSchedule">
+                    <span class="code-tooltip">renderSchedule() in app.js</span>
+                    <div class="kpi-icon"><i class="fas fa-star"></i></div>
+                    <div class="kpi-value" id="kpiScore">?</div>
+                    <div class="kpi-label">Score</div>
+                </div>
+            </div>
+        </div>
+
+        <!--
+        CONTROL BAR
+
+        Contains buttons for controlling the solver.
+
+        BUTTONS:
+        - #solveButton: Starts solving (calls solve() in app.js)
+        - #stopSolvingButton: Stops solving (calls stopSolving() in app.js)
+        - #solvingSpinner: Shows while solver is running
+        - #analyzeButton: Shows score breakdown (calls analyze() in app.js)
+
+        The stop button is hidden by default, shown when solving starts.
+        -->
+        <div class="control-bar mb-4 d-flex align-items-center gap-3 flex-wrap code-link" data-target="app.js:solve">
+            <span class="code-tooltip">solve() and stopSolving() in app.js</span>
+
+            <!-- Solve button - visible when not solving -->
+            <button id="solveButton" class="btn btn-success btn-lg">
+                <i class="fas fa-play me-2"></i>Solve
+            </button>
+
+            <!-- Stop button - visible when solving -->
+            <button id="stopSolvingButton" class="btn btn-danger btn-lg" style="display: none;">
+                <i class="fas fa-stop me-2"></i>Stop
+            </button>
+
+            <!-- Spinner - animated when solving -->
+            <span id="solvingSpinner"></span>
+
+            <div class="ms-auto d-flex align-items-center gap-2">
+                <!-- Analyze button - shows score breakdown -->
+                <button id="analyzeButton" class="btn btn-outline-secondary code-link" data-target="app.js:analyze">
+                    <span class="code-tooltip">analyze() in app.js</span>
+                    <i class="fas fa-microscope me-1"></i>Analyze
+                </button>
+            </div>
+        </div>
+
+        <!--
+        MAIN CONTENT GRID
+
+        Two-column layout:
+        - Left (col-lg-4): Resources panel - problem facts
+        - Right (col-lg-8): Tasks panel - planning entities
+
+        Both panels have code-link pointing to their render functions.
+        -->
+        <div class="row g-4">
+            <!--
+            RESOURCES PANEL
+
+            Displays problem facts (resources that tasks can be assigned to).
+            Content populated by renderResources() in app.js.
+
+            Each resource shows:
+            - Name
+            - Capacity with utilization bar
+            - Available skills
+            -->
+            <div class="col-lg-4">
+                <div class="section-card code-link" data-target="app.js:renderResources">
+                    <span class="code-tooltip">renderResources() in app.js</span>
+                    <div class="section-header">
+                        <h5><i class="fas fa-users me-2"></i>Resources</h5>
+                        <div class="d-flex align-items-center gap-2">
+                            <span class="badge bg-secondary" id="resourceCount">0</span>
+                            <button class="btn btn-sm btn-success" onclick="showAddResourceModal(event)" title="Add Resource">
+                                <i class="fas fa-plus"></i>
+                            </button>
+                        </div>
+                    </div>
+                    <div class="section-body" id="resourcesPanel">
+                        <p class="text-muted text-center">Select a dataset to load resources</p>
+                    </div>
+                </div>
+            </div>
+
+            <!--
+            TASKS PANEL
+
+            Displays planning entities (tasks to be assigned).
+            Content populated by renderSolution() in app.js.
+
+            Each task shows:
+            - Name and ID
+            - Duration
+            - Required skill (if any)
+            - Assigned resource (or "Unassigned")
+            - Violation status (red border if constraint violated)
+            -->
+            <div class="col-lg-8">
+                <div class="section-card code-link" data-target="app.js:renderSolution">
+                    <span class="code-tooltip">renderSolution() in app.js</span>
+                    <div class="section-header">
+                        <h5><i class="fas fa-clipboard-list me-2"></i>Tasks</h5>
+                        <div class="d-flex align-items-center gap-2">
+                            <span class="badge bg-secondary" id="taskCount">0</span>
+                            <button class="btn btn-sm btn-success" onclick="showAddTaskModal(event)" title="Add Task">
+                                <i class="fas fa-plus"></i>
+                            </button>
+                        </div>
+                    </div>
+                    <div class="section-body" id="tasksPanel">
+                        <p class="text-muted text-center">Select a dataset to load tasks</p>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!--
+        CONSTRAINTS LEGEND
+
+        Clickable badges showing all active constraints from constraints.py.
+        Each badge links to the constraint function definition.
+
+        CONSTRAINT TYPES:
+        - Hard (red, lock icon): MUST be satisfied. Violations make solution infeasible.
+        - Soft (green, feather icon): SHOULD be optimized. More violations = worse score.
+
+        TODO: Update these badges to match your constraints.py definitions.
+        Each data-target points to "constraints.py:function_name"
+        -->
+        <div class="constraints-legend mt-4 code-link" data-target="constraints.py:define_constraints">
+            <span class="code-tooltip">constraints.py - define_constraints()</span>
+            <h6 class="mb-3"><i class="fas fa-balance-scale me-2"></i>Active Constraints</h6>
+            <div class="d-flex flex-wrap gap-2">
+                <!-- Hard constraint: Required skill -->
+                <span class="constraint-badge hard" data-target="constraints.py:required_skill">
+                    <i class="fas fa-lock"></i>Required Skill
+                </span>
+
+                <!-- Hard constraint: Resource capacity -->
+                <span class="constraint-badge hard" data-target="constraints.py:resource_capacity">
+                    <i class="fas fa-lock"></i>Resource Capacity
+                </span>
+
+                <!-- Soft constraint: Minimize duration -->
+                <span class="constraint-badge soft" data-target="constraints.py:minimize_total_duration">
+                    <i class="fas fa-feather"></i>Minimize Duration
+                </span>
+
+                <!-- Soft constraint: Balance load -->
+                <span class="constraint-badge soft" data-target="constraints.py:balance_resource_load">
+                    <i class="fas fa-feather"></i>Balance Load
+                </span>
+            </div>
+        </div>
+
+        <!--
+        CONSTRAINT WEIGHT SLIDERS
+
+        Interactive sliders to adjust constraint weights.
+        Weight 0 = disabled, 100 = full strength.
+        Changes are applied when clicking Solve.
+        -->
+        <div class="constraints-legend mt-3">
+            <div class="d-flex justify-content-between align-items-center mb-3">
+                <h6 class="mb-0"><i class="fas fa-sliders-h me-2"></i>Constraint Weights</h6>
+                <button class="btn btn-sm btn-outline-secondary" onclick="resetConstraintWeights()">
+                    <i class="fas fa-undo me-1"></i>Reset
+                </button>
+            </div>
+
+            <!-- Hard constraint: Required Skill -->
+            <div class="mb-3">
+                <div class="d-flex justify-content-between mb-1">
+                    <label class="form-label mb-0">
+                        <span class="badge bg-danger me-1">Hard</span>Required Skill
+                    </label>
+                    <span class="text-muted" id="weightRequiredSkillValue">100</span>
+                </div>
+                <input type="range" class="form-range" id="weightRequiredSkill" min="0" max="100" value="100"
+                       oninput="updateWeightDisplay('RequiredSkill')">
+            </div>
+
+            <!-- Hard constraint: Resource Capacity -->
+            <div class="mb-3">
+                <div class="d-flex justify-content-between mb-1">
+                    <label class="form-label mb-0">
+                        <span class="badge bg-danger me-1">Hard</span>Resource Capacity
+                    </label>
+                    <span class="text-muted" id="weightResourceCapacityValue">100</span>
+                </div>
+                <input type="range" class="form-range" id="weightResourceCapacity" min="0" max="100" value="100"
+                       oninput="updateWeightDisplay('ResourceCapacity')">
+            </div>
+
+            <!-- Soft constraint: Minimize Duration -->
+            <div class="mb-3">
+                <div class="d-flex justify-content-between mb-1">
+                    <label class="form-label mb-0">
+                        <span class="badge bg-success me-1">Soft</span>Minimize Duration
+                    </label>
+                    <span class="text-muted" id="weightMinimizeDurationValue">50</span>
+                </div>
+                <input type="range" class="form-range" id="weightMinimizeDuration" min="0" max="100" value="50"
+                       oninput="updateWeightDisplay('MinimizeDuration')">
+            </div>
+
+            <!-- Soft constraint: Balance Load -->
+            <div class="mb-3">
+                <div class="d-flex justify-content-between mb-1">
+                    <label class="form-label mb-0">
+                        <span class="badge bg-success me-1">Soft</span>Balance Load
+                    </label>
+                    <span class="text-muted" id="weightBalanceLoadValue">50</span>
+                </div>
+                <input type="range" class="form-range" id="weightBalanceLoad" min="0" max="100" value="50"
+                       oninput="updateWeightDisplay('BalanceLoad')">
+            </div>
+
+            <small class="text-muted">
+                <i class="fas fa-info-circle me-1"></i>
+                Set to 0 to disable a constraint. Changes apply on next Solve.
+            </small>
+        </div>
+    </div>
+
+    <!--
+    ===========================================================================
+    BUILD TAB
+    ===========================================================================
+
+    Source code viewer showing actual quickstart files with syntax highlighting.
+
+    COMPONENTS:
+    1. File Navigator (left): Tree view of project files
+    2. Code Viewer (right): Syntax-highlighted code display
+
+    HOW IT WORKS:
+    1. User clicks a file in the navigator
+    2. app.js fetches source code from /source-code/{filename} API
+    3. Prism.js highlights the syntax
+
+    INTERACTIVE CODE INTEGRATION:
+    When user clicks a code-link element in Demo tab,
+    they're navigated here with the relevant file displayed.
+    ===========================================================================
+    -->
+    <div class="tab-pane fade" id="build">
+        <div class="row g-4">
+            <!--
+            FILE NAVIGATOR
+
+            Tree view showing all project source files.
+            Click a file to load it in the code viewer.
+
+            Each .file-item has:
+            - data-file: The filename to load
+            - Icon: Language-specific (fa-python, fa-html5, fa-js)
+            - Badge: File type description
+
+            TO ADD A NEW FILE:
+            1. Add a .file-item div with data-file="filename"
+            2. Add the file to SOURCE_FILES whitelist in rest_api.py
+            -->
+            <div class="col-lg-3">
+                <div class="file-nav">
+                    <div class="file-nav-header">
+                        <i class="fas fa-folder-tree me-2"></i>Project Files
+                    </div>
+                    <div class="file-tree">
+                        <!-- Python source files -->
+                        <div class="folder-item">
+                            <div class="folder-name"><i class="fas fa-folder me-2"></i>src/my_quickstart/</div>
+                            <div class="file-item active" data-file="domain.py">
+                                <i class="fab fa-python"></i>
+                                <span>domain.py</span>
+                                <span class="file-badge">Model</span>
+                            </div>
+                            <div class="file-item" data-file="constraints.py">
+                                <i class="fab fa-python"></i>
+                                <span>constraints.py</span>
+                                <span class="file-badge">Rules</span>
+                            </div>
+                            <div class="file-item" data-file="solver.py">
+                                <i class="fab fa-python"></i>
+                                <span>solver.py</span>
+                                <span class="file-badge">Config</span>
+                            </div>
+                            <div class="file-item" data-file="rest_api.py">
+                                <i class="fab fa-python"></i>
+                                <span>rest_api.py</span>
+                                <span class="file-badge">API</span>
+                            </div>
+                            <div class="file-item" data-file="demo_data.py">
+                                <i class="fab fa-python"></i>
+                                <span>demo_data.py</span>
+                                <span class="file-badge">Data</span>
+                            </div>
+                        </div>
+                        <!-- Frontend files -->
+                        <div class="folder-item mt-2">
+                            <div class="folder-name"><i class="fas fa-folder me-2"></i>static/</div>
+                            <div class="file-item" data-file="index.html">
+                                <i class="fab fa-html5"></i>
+                                <span>index.html</span>
+                                <span class="file-badge">UI</span>
+                            </div>
+                            <div class="file-item" data-file="app.js">
+                                <i class="fab fa-js"></i>
+                                <span>app.js</span>
+                                <span class="file-badge">Logic</span>
+                            </div>
+                            <div class="file-item" data-file="app.css">
+                                <i class="fab fa-css3-alt"></i>
+                                <span>app.css</span>
+                                <span class="file-badge">Styles</span>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+            </div>
+
+            <!--
+            CODE VIEWER
+
+            Main panel showing syntax-highlighted source code.
+
+            Components:
+            - Header: File path and action buttons
+            - Body: Prism.js highlighted code with line numbers
+
+            Action buttons:
+            - Copy: Copies code to clipboard
+            - See in Demo: Navigates to Demo tab (useful for HTML/JS)
+            -->
+            <div class="col-lg-9">
+                <div class="code-viewer">
+                    <div class="code-viewer-header">
+                        <span class="code-path" id="currentFilePath">
+                            <i class="fab fa-python me-2"></i>src/my_quickstart/domain.py
+                        </span>
+                        <div>
+                            <button class="btn btn-sm btn-outline-light me-2" onclick="copyCurrentCode()">
+                                <i class="fas fa-copy me-1"></i>Copy
+                            </button>
+                            <button class="btn btn-sm btn-outline-success" onclick="showInDemo()">
+                                <i class="fas fa-eye me-1"></i>See in Demo
+                            </button>
+                        </div>
+                    </div>
+                    <div class="code-viewer-body">
+                        <!--
+                        Prism.js handles syntax highlighting.
+                        The .line-numbers class enables line number display.
+                        Language class (language-python) sets highlighting rules.
+                        -->
+                        <pre class="line-numbers"><code class="language-python" id="codeContent">Loading...</code></pre>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!--
+    ===========================================================================
+    GUIDE TAB
+    ===========================================================================
+
+    REST API integration guide with cURL examples.
+
+    Shows the typical workflow:
+    1. Download demo data
+    2. Start solving (get job ID)
+    3. Check status
+    4. Get solution
+    5. Stop solving
+
+    TODO: Update endpoint paths and examples to match your API.
+    ===========================================================================
+    -->
+    <div class="tab-pane fade" id="guide">
+        <div class="container">
+            <h1 class="mb-4"><i class="fas fa-book me-2"></i>REST API Guide</h1>
+            <h2>Integration via cURL</h2>
+
+            <h3 class="mt-4">1. Download demo data</h3>
+            <pre class="bg-dark text-light p-3 rounded"><code>curl -X GET http://localhost:8080/demo-data/SMALL -o sample.json</code></pre>
+
+            <h3 class="mt-4">2. Start solving</h3>
+            <p>Returns a <code>jobId</code> for subsequent requests.</p>
+            <pre class="bg-dark text-light p-3 rounded"><code>curl -X POST -H 'Content-Type:application/json' http://localhost:8080/schedules -d @sample.json</code></pre>
+
+            <h3 class="mt-4">3. Check status</h3>
+            <pre class="bg-dark text-light p-3 rounded"><code>curl -X GET http://localhost:8080/schedules/{jobId}/status</code></pre>
+
+            <h3 class="mt-4">4. Get solution</h3>
+            <pre class="bg-dark text-light p-3 rounded"><code>curl -X GET http://localhost:8080/schedules/{jobId}</code></pre>
+
+            <h3 class="mt-4">5. Stop solving</h3>
+            <pre class="bg-dark text-light p-3 rounded"><code>curl -X DELETE http://localhost:8080/schedules/{jobId}</code></pre>
+        </div>
+    </div>
+
+    <!--
+    ===========================================================================
+    API TAB (SWAGGER UI)
+    ===========================================================================
+
+    Embeds the FastAPI auto-generated Swagger UI documentation.
+
+    The iframe loads /q/swagger-ui which is served by the FastAPI backend.
+    This provides interactive API documentation and testing.
+
+    NOTE: The /q/ prefix is the Quarkus-style path used by FastAPI with
+    the swagger-ui extension.
+    ===========================================================================
+    -->
+    <div class="tab-pane fade" id="api">
+        <h1 class="mb-4"><i class="fas fa-plug me-2"></i>REST API Reference</h1>
+        <div class="ratio ratio-1x1" style="max-height: 800px;">
+            <iframe src="/q/swagger-ui" style="border-radius: 12px;"></iframe>
+        </div>
+    </div>
+
+</div>
+
+<!--
+================================================================================
+SCORE ANALYSIS MODAL
+================================================================================
+
+Modal dialog showing detailed score breakdown from /schedules/analyze endpoint.
+
+Displayed when user clicks the Analyze button.
+Content populated by analyze() function in app.js.
+
+Shows:
+- Overall score
+- Constraint match details (which constraints are violated and by how much)
+================================================================================
+-->
+<div class="modal fade" id="scoreAnalysisModal" tabindex="-1">
+    <div class="modal-dialog modal-lg modal-dialog-scrollable">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title">
+                    <i class="fas fa-microscope me-2"></i>Score Analysis
+                    <span id="scoreAnalysisScore" class="text-muted ms-2"></span>
+                </h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+            </div>
+            <div class="modal-body" id="scoreAnalysisContent">
+                <!-- Populated by analyze() in app.js -->
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!--
+================================================================================
+ADD RESOURCE MODAL
+================================================================================
+-->
+<div class="modal fade" id="addResourceModal" tabindex="-1">
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title">
+                    <i class="fas fa-user-plus me-2"></i>Add Resource
+                </h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+            </div>
+            <div class="modal-body">
+                <div class="mb-3">
+                    <label for="resourceName" class="form-label">Name</label>
+                    <input type="text" class="form-control" id="resourceName" placeholder="e.g., Alice">
+                </div>
+                <div class="mb-3">
+                    <label for="resourceCapacity" class="form-label">Capacity (minutes)</label>
+                    <input type="number" class="form-control" id="resourceCapacity" value="100" min="1">
+                </div>
+                <div class="mb-3">
+                    <label for="resourceSkills" class="form-label">Skills (comma-separated)</label>
+                    <input type="text" class="form-control" id="resourceSkills" placeholder="e.g., python, sql, java">
+                </div>
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+                <button type="button" class="btn btn-success" onclick="addResource()">
+                    <i class="fas fa-plus me-1"></i>Add Resource
+                </button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!--
+================================================================================
+ADD TASK MODAL
+================================================================================
+-->
+<div class="modal fade" id="addTaskModal" tabindex="-1">
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title">
+                    <i class="fas fa-tasks me-2"></i>Add Task
+                </h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+            </div>
+            <div class="modal-body">
+                <div class="mb-3">
+                    <label for="taskName" class="form-label">Name</label>
+                    <input type="text" class="form-control" id="taskName" placeholder="e.g., API Development">
+                </div>
+                <div class="mb-3">
+                    <label for="taskDuration" class="form-label">Duration (minutes)</label>
+                    <input type="number" class="form-control" id="taskDuration" value="30" min="1">
+                </div>
+                <div class="mb-3">
+                    <label for="taskSkill" class="form-label">Required Skill (optional)</label>
+                    <input type="text" class="form-control" id="taskSkill" placeholder="e.g., python">
+                </div>
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+                <button type="button" class="btn btn-success" onclick="addTask()">
+                    <i class="fas fa-plus me-1"></i>Add Task
+                </button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!--
+================================================================================
+JAVASCRIPT DEPENDENCIES
+================================================================================
+
+Required libraries (loaded from CDN):
+- jQuery 3.7.1: DOM manipulation and AJAX
+- Popper.js 2.11.8: Bootstrap positioning engine
+- Bootstrap 5.3.3: UI components (modals, tabs, dropdowns)
+- Prism.js 1.29.0: Syntax highlighting for code viewer
+  - Core library
+  - Python language support
+  - JavaScript language support
+  - Line numbers plugin
+
+LOAD ORDER MATTERS:
+1. jQuery (required by Bootstrap)
+2. Popper.js (required by Bootstrap)
+3. Bootstrap
+4. Prism.js (core, then language modules, then plugins)
+5. app.js (our custom code)
+
+TIP: For production, consider bundling these locally.
+================================================================================
+-->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/2.11.8/umd/popper.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/js/bootstrap.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
+
+<!--
+================================================================================
+APPLICATION JAVASCRIPT
+================================================================================
+
+The main application logic is in app.js. It handles:
+- Loading demo data from the API
+- Starting/stopping the solver
+- Polling for solution updates
+- Rendering the solution visualization
+- Learn tab lesson navigation
+- Build tab code viewer
+- Interactive Code click-to-code feature
+
+See app.js for detailed documentation of each function.
+================================================================================
+-->
+<script src="/app.js"></script>
+
+</body>
+</html>

static/webjars/solverforge/css/solverforge-webui.css

@@ -0,0 +1,122 @@
+/*
+ * =============================================================================
+ * SOLVERFORGE QUICKSTART - WEB UI STYLESHEET
+ * =============================================================================
+ *
+ * This CSS file provides the base styling for all SolverForge quickstart UIs.
+ * It customizes Bootstrap 5 variables and adds SolverForge-specific styles.
+ *
+ * CUSTOMIZATION GUIDE:
+ * --------------------
+ * 1. Colors: Modify the CSS variables in :root to match your branding
+ * 2. Buttons: The .btn classes customize Bootstrap button styles
+ * 3. Navigation: .nav-pills styles the main navigation tabs
+ * 4. Layout: The navbar height is defined for consistent positioning
+ *
+ * The main colors used are:
+ * - Green (#10b981): Primary action color, success states
+ * - Violet (#3E00FF): Secondary accent, links
+ * - Gray (#666666): Text, borders
+ * - Light (#F2F2F2): Background
+ */
+
+:root {
+    /* =======================================================================
+     * NAVBAR & LAYOUT
+     * Keep in sync with .navbar height on a large screen.
+     * ======================================================================= */
+    --ts-navbar-height: 109px;
+
+    /* =======================================================================
+     * COLOR PALETTE
+     * These are the SolverForge brand colors. Modify to match your branding.
+     * ======================================================================= */
+    --ts-green-1-rgb: #10b981;  /* Primary green - used for success, primary actions */
+    --ts-green-2-rgb: #059669;  /* Darker green - used for hover states */
+    --ts-violet-1-rgb: #3E00FF; /* Primary violet - used for links, accents */
+    --ts-violet-2-rgb: #3423A6; /* Secondary violet - used for hover states */
+    --ts-violet-3-rgb: #2E1760; /* Dark violet - used for dark backgrounds */
+    --ts-violet-4-rgb: #200F4F; /* Darker violet */
+    --ts-violet-5-rgb: #000000; /* Darkest (currently black) */
+    --ts-violet-dark-1-rgb: #b6adfd; /* Light violet for dark backgrounds */
+    --ts-violet-dark-2-rgb: #c1bbfd; /* Lighter violet for dark backgrounds */
+    --ts-gray-rgb: #666666;     /* Gray text */
+    --ts-white-rgb: #FFFFFF;    /* White */
+    --ts-light-rgb: #F2F2F2;    /* Light background */
+    --ts-gray-border: #c5c5c5;  /* Border color */
+
+    /* =======================================================================
+     * BOOTSTRAP OVERRIDES
+     * These override Bootstrap's default CSS variables.
+     * ======================================================================= */
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5);
+    --bs-body-bg: var(--ts-light-rgb);
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+
+/* ===========================================================================
+ * BUTTON STYLES
+ * Customizes Bootstrap buttons with rounded corners and SolverForge colors.
+ * =========================================================================== */
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+
+/* Primary button - violet color */
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+
+/* Outline primary button */
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+
+/* ===========================================================================
+ * NAVBAR STYLES
+ * Styles for the dark navbar variant.
+ * =========================================================================== */
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+
+/* ===========================================================================
+ * NAVIGATION PILLS
+ * Styles for the main tab navigation.
+ * =========================================================================== */
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-green-1-rgb);
+}
+
+.nav-pills .nav-link:hover {
+    color: var(--ts-green-1-rgb);
+}
+
+.nav-pills .nav-link.active:hover {
+    color: var(--ts-white-rgb);
+}

static/webjars/solverforge/js/solverforge-webui.js

@@ -0,0 +1,333 @@
+/*
+ * =============================================================================
+ * SOLVERFORGE QUICKSTART - SHARED WEB UI UTILITIES
+ * =============================================================================
+ *
+ * This file provides shared utility functions for all SolverForge quickstart UIs.
+ * It includes:
+ * - Header/footer generation
+ * - Error notification handling
+ * - Application info display
+ * - Color utilities for visualizations
+ *
+ * USAGE:
+ * ------
+ * 1. Include this file AFTER jQuery and Bootstrap in your HTML
+ * 2. Call replaceQuickstartSolverForgeAutoHeaderFooter() in your app.js
+ * 3. Use showError() for displaying error notifications
+ * 4. Use pickColor()/nextColor() for consistent visualization colors
+ */
+
+
+// =============================================================================
+// HEADER & FOOTER GENERATION
+// =============================================================================
+
+/**
+ * Replaces the placeholder header and footer with the SolverForge branded versions.
+ *
+ * This function looks for:
+ * - <header id="solverforge-auto-header"> - replaced with navbar
+ * - <footer id="solverforge-auto-footer"> - replaced with footer links
+ *
+ * The header includes:
+ * - SolverForge logo linking to homepage
+ * - Navigation tabs: Demo UI, Guide, REST API
+ * - Data dropdown for selecting demo datasets
+ *
+ * CUSTOMIZATION:
+ * - Modify the HTML template below to change navigation items
+ * - Update logo src to use a different logo
+ * - Add/remove nav items as needed
+ */
+function replaceQuickstartSolverForgeAutoHeaderFooter() {
+    const solverforgeHeader = $("header#solverforge-auto-header");
+    if (solverforgeHeader != null) {
+        // Set white background for header
+        solverforgeHeader.css("background-color", "#ffffff");
+
+        // Append the navbar HTML
+        solverforgeHeader.append(
+            $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg shadow-sm mb-3" style="background-color: #ffffff;">
+          <!-- Logo - links to SolverForge homepage -->
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge logo" width="400">
+          </a>
+
+          <!-- Mobile toggle button -->
+          <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+            <span class="navbar-toggler-icon"></span>
+          </button>
+
+          <!-- Navigation items -->
+          <div class="collapse navbar-collapse" id="navbarNav">
+            <ul class="nav nav-pills">
+              <!-- Demo UI tab - shows the main visualization -->
+              <li class="nav-item active" id="navUIItem">
+                <button class="nav-link active" id="navUI" data-bs-toggle="pill" data-bs-target="#demo" type="button" style="color: #1f2937;">Demo UI</button>
+              </li>
+              <!-- Guide tab - shows REST API usage guide -->
+              <li class="nav-item" id="navRestItem">
+                <button class="nav-link" id="navRest" data-bs-toggle="pill" data-bs-target="#rest" type="button" style="color: #1f2937;">Guide</button>
+              </li>
+              <!-- REST API tab - shows Swagger/OpenAPI docs -->
+              <li class="nav-item" id="navOpenApiItem">
+                <button class="nav-link" id="navOpenApi" data-bs-toggle="pill" data-bs-target="#openapi" type="button" style="color: #1f2937;">REST API</button>
+              </li>
+            </ul>
+          </div>
+
+          <!-- Data dropdown - populated dynamically with demo datasets -->
+          <div class="ms-auto">
+              <div class="dropdown">
+                  <button class="btn dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false" style="background-color: #10b981; color: #ffffff; border-color: #10b981;">
+                      Data
+                  </button>
+                  <div id="testDataButton" class="dropdown-menu" aria-labelledby="dropdownMenuButton">
+                      <!-- Demo data items will be added here by fetchDemoData() -->
+                  </div>
+              </div>
+          </div>
+        </nav>
+      </div>`));
+    }
+
+    const solverforgeFooter = $("footer#solverforge-auto-footer");
+    if (solverforgeFooter != null) {
+        // Append the footer HTML
+        solverforgeFooter.append(
+            $(`<footer class="bg-black text-white-50">
+               <div class="container">
+                 <div class="hstack gap-3 p-4">
+                   <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+                   <div class="vr"></div>
+                   <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+                   <div class="vr"></div>
+                   <div><a class="text-white" href="https://github.com/SolverForge/solverforge">Code</a></div>
+                   <div class="vr"></div>
+                   <div class="me-auto"><a class="text-white" href="mailto:[email protected]">Support</a></div>
+                 </div>
+               </div>
+               <!-- Application info will be displayed here -->
+               <div id="applicationInfo" class="container text-center"></div>
+             </footer>`));
+
+        // Load and display application info
+        applicationInfo();
+    }
+}
+
+
+// =============================================================================
+// ERROR NOTIFICATION HANDLING
+// =============================================================================
+
+/**
+ * Shows a simple error notification with just a title.
+ *
+ * Use this for simple error messages that don't have additional details.
+ * The notification auto-dismisses after 30 seconds.
+ *
+ * @param {string} title - The error message to display
+ *
+ * EXAMPLE:
+ *   showSimpleError("No schedule data available");
+ */
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+/**
+ * Shows a detailed error notification from an AJAX error response.
+ *
+ * This extracts error details from the XMLHttpRequest object and displays:
+ * - Error title (from the caller)
+ * - Server error message
+ * - Error code
+ * - Error ID (for debugging)
+ *
+ * @param {string} title - A human-readable title for the error
+ * @param {XMLHttpRequest} xhr - The jQuery AJAX error object
+ *
+ * EXAMPLE:
+ *   $.post("/schedules", data).fail(function(xhr) {
+ *       showError("Failed to start solving", xhr);
+ *   });
+ */
+function showError(title, xhr) {
+    // Extract error details from response
+    var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+    var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+    var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+    var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+    // Handle case where responseJSON exists but has unexpected format
+    if (xhr.responseJSON && !serverErrorMessage) {
+        serverErrorMessage = JSON.stringify(xhr.responseJSON);
+        serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+        serverErrorId = `----`;
+    }
+
+    // Log to console for debugging
+    console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+
+    // Create and show toast notification
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+            .append($(`<pre/>`)
+                .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+            )
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+
+// =============================================================================
+// APPLICATION INFO
+// =============================================================================
+
+/**
+ * Fetches and displays application version information in the footer.
+ *
+ * This calls the /info endpoint (if available) and displays:
+ * - Application name
+ * - Version number
+ * - Build timestamp
+ *
+ * NOTE: Your backend must implement the /info endpoint for this to work.
+ * If not implemented, the footer will just show the links without version info.
+ */
+function applicationInfo() {
+    $.getJSON("info", function (info) {
+        $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        console.warn("Unable to collect application information");
+    });
+}
+
+
+// =============================================================================
+// TANGO COLOR FACTORY
+// =============================================================================
+//
+// These functions provide a consistent color palette for visualizations.
+// The colors are based on the Tango color palette, which provides good
+// contrast and accessibility.
+//
+// USAGE:
+//   let color = pickColor("employee-1");  // Returns consistent color for same object
+//   let color = nextColor();              // Returns next color in sequence
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+/**
+ * Returns a consistent color for an object.
+ *
+ * If the object has been seen before, returns the same color.
+ * Otherwise, assigns and returns a new color.
+ *
+ * @param {*} object - Any object/value to get a color for
+ * @returns {string} A hex color string (e.g., "#8ae234")
+ */
+function pickColor(object) {
+    let color = colorMap[object];
+    if (color !== undefined) {
+        return color;
+    }
+    color = nextColor();
+    colorMap[object] = color;
+    return color;
+}
+
+/**
+ * Returns the next color in the sequence.
+ *
+ * Cycles through SEQUENCE_1, then SEQUENCE_2, then generates
+ * interpolated colors for additional objects.
+ *
+ * @returns {string} A hex color string (e.g., "#8ae234")
+ */
+function nextColor() {
+    let color;
+    let colorIndex = nextColorCount % SEQUENCE_1.length;
+    let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+
+    if (shadeIndex === 0) {
+        color = SEQUENCE_1[colorIndex];
+    } else if (shadeIndex === 1) {
+        color = SEQUENCE_2[colorIndex];
+    } else {
+        // Generate interpolated colors for additional items
+        shadeIndex -= 3;
+        let floorColor = SEQUENCE_2[colorIndex];
+        let ceilColor = SEQUENCE_1[colorIndex];
+        let base = Math.floor((shadeIndex / 2) + 1);
+        let divisor = 2;
+        while (base >= divisor) {
+            divisor *= 2;
+        }
+        base = (base * 2) - divisor + 1;
+        let shadePercentage = base / divisor;
+        color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+    }
+    nextColorCount++;
+    return "#" + color.toString(16);
+}
+
+/**
+ * Interpolates between two colors.
+ *
+ * @param {number} floorColor - The starting color (as integer)
+ * @param {number} ceilColor - The ending color (as integer)
+ * @param {number} shadePercentage - How far to interpolate (0-1)
+ * @returns {number} The interpolated color (as integer)
+ */
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+    let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+    let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+    let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+    return red | green | blue;
+}
+
+
+// =============================================================================
+// CLIPBOARD UTILITY
+// =============================================================================
+
+/**
+ * Copies text content to the clipboard.
+ *
+ * Used by the Guide tab to let users copy cURL commands.
+ *
+ * @param {string} elementId - The ID of the element containing text to copy
+ */
+function copyTextToClipboard(elementId) {
+    const text = document.getElementById(elementId).textContent;
+    navigator.clipboard.writeText(text).then(function() {
+        console.log('Copied to clipboard: ' + text.substring(0, 50) + '...');
+    }).catch(function(err) {
+        console.error('Failed to copy text: ', err);
+    });
+}

tests/test_constraints.py

@@ -0,0 +1,140 @@
+"""
+Constraint verification tests.
+
+These tests verify that each constraint behaves correctly in isolation.
+Use ConstraintVerifier to test individual constraints without running the full solver.
+"""
+
+import pytest
+from solverforge_legacy.solver.test import ConstraintVerifier
+from my_quickstart.domain import Resource, Task, Schedule
+from my_quickstart.constraints import define_constraints
+
+
+@pytest.fixture
+def constraint_verifier():
+    """Create a constraint verifier for testing."""
+    return ConstraintVerifier.build(
+        define_constraints,
+        Schedule,
+        Task,
+    )
+
+
+# =============================================================================
+# TEST DATA FIXTURES
+# =============================================================================
+
+@pytest.fixture
+def alice():
+    return Resource(name="Alice", capacity=100, skills={"python", "sql"})
+
+
+@pytest.fixture
+def bob():
+    return Resource(name="Bob", capacity=50, skills={"java"})
+
+
+# =============================================================================
+# HARD CONSTRAINT TESTS
+# =============================================================================
+
+class TestRequiredSkill:
+    """Tests for the 'Required skill missing' constraint."""
+
+    def test_no_penalty_when_skill_matches(self, constraint_verifier, alice):
+        """Task with matching skill should not be penalized."""
+        task = Task(id="1", name="Python Task", duration=30, required_skill="python", resource=alice)
+
+        constraint_verifier.verify_that("Required skill missing") \
+            .given(task) \
+            .penalizes_by(0)
+
+    def test_penalty_when_skill_missing(self, constraint_verifier, bob):
+        """Task assigned to resource without required skill should be penalized."""
+        task = Task(id="1", name="Python Task", duration=30, required_skill="python", resource=bob)
+
+        constraint_verifier.verify_that("Required skill missing") \
+            .given(task) \
+            .penalizes_by(1)
+
+    def test_no_penalty_when_no_skill_required(self, constraint_verifier, alice):
+        """Task with no skill requirement should not be penalized."""
+        task = Task(id="1", name="Any Task", duration=30, required_skill="", resource=alice)
+
+        constraint_verifier.verify_that("Required skill missing") \
+            .given(task) \
+            .penalizes_by(0)
+
+
+class TestResourceCapacity:
+    """Tests for the 'Resource capacity exceeded' constraint."""
+
+    def test_no_penalty_under_capacity(self, constraint_verifier, alice):
+        """Tasks under capacity should not be penalized."""
+        task1 = Task(id="1", name="Task 1", duration=30, resource=alice)
+        task2 = Task(id="2", name="Task 2", duration=40, resource=alice)
+        # Total: 70, Capacity: 100
+
+        constraint_verifier.verify_that("Resource capacity exceeded") \
+            .given(task1, task2) \
+            .penalizes_by(0)
+
+    def test_penalty_over_capacity(self, constraint_verifier, bob):
+        """Tasks exceeding capacity should be penalized by the overflow amount."""
+        task1 = Task(id="1", name="Task 1", duration=30, resource=bob)
+        task2 = Task(id="2", name="Task 2", duration=40, resource=bob)
+        # Total: 70, Capacity: 50, Overflow: 20
+
+        constraint_verifier.verify_that("Resource capacity exceeded") \
+            .given(task1, task2) \
+            .penalizes_by(20)
+
+
+# =============================================================================
+# SOFT CONSTRAINT TESTS
+# =============================================================================
+
+class TestMinimizeDuration:
+    """Tests for the 'Minimize total duration' constraint."""
+
+    def test_penalizes_by_duration(self, constraint_verifier, alice):
+        """Each assigned task should be penalized by its duration."""
+        task = Task(id="1", name="Task", duration=45, resource=alice)
+
+        constraint_verifier.verify_that("Minimize total duration") \
+            .given(task) \
+            .penalizes_by(45)
+
+    def test_unassigned_not_penalized(self, constraint_verifier):
+        """Unassigned tasks should not be penalized."""
+        task = Task(id="1", name="Task", duration=45, resource=None)
+
+        constraint_verifier.verify_that("Minimize total duration") \
+            .given(task) \
+            .penalizes_by(0)
+
+
+# =============================================================================
+# INTEGRATION TEST
+# =============================================================================
+
+class TestFullSolution:
+    """Test the full constraint set on a complete solution."""
+
+    def test_feasible_solution(self, constraint_verifier, alice, bob):
+        """A feasible solution should have no hard constraint violations."""
+        tasks = [
+            Task(id="1", name="Python Task", duration=30, required_skill="python", resource=alice),
+            Task(id="2", name="SQL Task", duration=20, required_skill="sql", resource=alice),
+            Task(id="3", name="Java Task", duration=40, required_skill="java", resource=bob),
+        ]
+
+        # Verify no hard violations
+        constraint_verifier.verify_that("Required skill missing") \
+            .given(*tasks) \
+            .penalizes_by(0)
+
+        constraint_verifier.verify_that("Resource capacity exceeded") \
+            .given(*tasks) \
+            .penalizes_by(0)

tests/test_rest_api.py

@@ -0,0 +1,79 @@
+"""
+REST API endpoint tests.
+
+Tests for the FastAPI endpoints including the source code viewer API.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from my_quickstart.rest_api import app
+
+
+@pytest.fixture
+def client():
+    """Create a test client for the API."""
+    return TestClient(app)
+
+
+# =============================================================================
+# SOURCE CODE VIEWER TESTS
+# =============================================================================
+
+class TestSourceCodeEndpoints:
+    """Tests for the /source-code endpoints."""
+
+    def test_list_source_files(self, client):
+        """GET /source-code should return list of available files."""
+        response = client.get("/source-code")
+        assert response.status_code == 200
+        files = response.json()
+        assert isinstance(files, list)
+        assert "domain.py" in files
+        assert "constraints.py" in files
+        assert "rest_api.py" in files
+
+    def test_get_domain_py(self, client):
+        """GET /source-code/domain.py should return file contents."""
+        response = client.get("/source-code/domain.py")
+        assert response.status_code == 200
+        data = response.json()
+        assert "filename" in data
+        assert "content" in data
+        assert data["filename"] == "domain.py"
+        assert "@planning_entity" in data["content"]
+
+    def test_get_constraints_py(self, client):
+        """GET /source-code/constraints.py should return file contents."""
+        response = client.get("/source-code/constraints.py")
+        assert response.status_code == 200
+        data = response.json()
+        assert "content" in data
+        assert "@constraint_provider" in data["content"]
+
+    def test_get_nonexistent_file(self, client):
+        """GET /source-code/nonexistent.py should return error."""
+        response = client.get("/source-code/nonexistent.py")
+        assert response.status_code != 200
+
+
+# =============================================================================
+# DEMO DATA TESTS
+# =============================================================================
+
+class TestDemoDataEndpoints:
+    """Tests for the /demo-data endpoints."""
+
+    def test_list_demo_data(self, client):
+        """GET /demo-data should return list of datasets."""
+        response = client.get("/demo-data")
+        assert response.status_code == 200
+        datasets = response.json()
+        assert isinstance(datasets, list)
+
+    def test_get_small_dataset(self, client):
+        """GET /demo-data/SMALL should return a schedule."""
+        response = client.get("/demo-data/SMALL")
+        assert response.status_code == 200
+        data = response.json()
+        assert "resources" in data
+        assert "tasks" in data