.

Dockerfile

@@ -0,0 +1,24 @@
+# Use Python 3.12 base image
+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/*
+
+# Copy application files
+COPY . .
+
+# Install the application
+RUN pip install --no-cache-dir -e .
+
+# Expose port 8080
+EXPOSE 8080
+
+# Run the application
+CMD ["run-app"]

README.md

@@ -1,12 +1,139 @@
 ---
-title: Vm Placement
-emoji: 🌍
-colorFrom: purple
-colorTo: purple
+title: Virtual Machine Placement (Python)
+emoji: 👀
+colorFrom: gray
+colorTo: green
 sdk: docker
+app_port: 8080
 pinned: false
 license: apache-2.0
-short_description: Virtual Machine Placement Optimization with SolverForge
+short_description: SolverForge Quickstart for the Vehicle Routing problem
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# VM Placement Quickstart
+
+A SolverForge quickstart demonstrating **constraint-based virtual machine placement optimization**.
+
+## The Problem
+
+You manage a datacenter with physical servers organized in racks, and must place virtual machines (VMs) onto those servers. Each server has limited CPU cores, memory, and storage capacity.
+
+**The challenge**: Place all VMs while:
+- Never exceeding any server's CPU, memory, or storage capacity
+- Keeping database replicas on separate servers (anti-affinity)
+- Placing related services together when possible (affinity)
+- Minimizing the number of active servers (consolidation)
+- Balancing load across active servers
+
+## Why Constraint Solving?
+
+With constraints, you describe *what* a valid placement looks like, not *how* to compute one. Adding a new business rule (e.g., "GPU workloads need GPU servers") is a single constraint function—not a rewrite of your algorithm.
+
+## Quick Start
+
+```bash
+# 1. Create and activate virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# 2. Install dependencies
+pip install -e .
+
+# 3. Run the application
+run-app
+
+# 4. Open http://localhost:8080 in your browser
+```
+
+**Requirement:** JDK 17+ must be installed (solverforge-legacy uses JPype to bridge Python and Java).
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_constraints.py
+```
+
+## Project Structure
+
+```
+vm-placement-fast/
+├── src/vm_placement/
+│   ├── domain.py          # Server, VM, and VMPlacementPlan
+│   ├── constraints.py     # Hard and soft placement constraints
+│   ├── solver.py          # SolverForge configuration
+│   ├── demo_data.py       # Sample infrastructure and VMs
+│   ├── rest_api.py        # FastAPI endpoints
+│   └── converters.py      # Domain ↔ REST model conversion
+├── tests/
+│   └── test_constraints.py  # Unit tests for each constraint
+├── static/
+│   ├── index.html         # Web UI with rack visualization
+│   ├── app.js             # Frontend logic
+│   └── config.js          # Advanced settings sliders
+└── pyproject.toml         # Dependencies
+```
+
+## Constraints
+
+### Hard Constraints (must be satisfied)
+
+1. **CPU Capacity**: Server CPU cannot be exceeded by assigned VMs
+2. **Memory Capacity**: Server memory cannot be exceeded by assigned VMs
+3. **Storage Capacity**: Server storage cannot be exceeded by assigned VMs
+4. **Anti-Affinity**: VMs in the same anti-affinity group (e.g., database replicas) must be on different servers
+
+### Soft Constraints (optimize for)
+
+5. **Affinity**: VMs in the same affinity group (e.g., web tier) should be on the same server
+6. **Minimize Servers Used**: Consolidate VMs onto fewer servers to reduce costs
+7. **Balance Utilization**: Distribute load evenly across active servers
+8. **Prioritize Placement**: Higher-priority VMs should be placed first
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/demo-data` | List available datasets |
+| GET | `/demo-data/{id}` | Load demo data |
+| POST | `/demo-data/generate` | Generate custom infrastructure |
+| POST | `/placements` | Submit for optimization |
+| GET | `/placements/{id}` | Get current solution |
+| GET | `/placements/{id}/status` | Get solving status |
+| DELETE | `/placements/{id}` | Stop solving |
+| PUT | `/placements/analyze` | Analyze placement score |
+
+API documentation available at http://localhost:8080/q/swagger-ui
+
+## Advanced Settings
+
+The web UI includes configurable sliders for:
+
+- **Racks**: Number of server racks (1-8)
+- **Servers per Rack**: Servers in each rack (2-10)
+- **VMs**: Number of VMs to place (5-200)
+- **Solver Time**: How long to optimize (5s-2min)
+
+Click "Generate New Data" to create custom scenarios.
+
+## VM Placement Concepts
+
+| Term | Definition |
+|------|------------|
+| **Server** | Physical machine with CPU, memory, and storage capacity |
+| **VM** | Virtual machine requiring resources from a server |
+| **Rack** | Physical grouping of servers in a datacenter |
+| **Affinity** | VMs that should run on the same server |
+| **Anti-Affinity** | VMs that must run on different servers |
+| **Consolidation** | Using fewer servers to reduce power/cooling costs |
+
+## Learn More
+
+- [SolverForge Documentation](https://solverforge.org/docs)

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "vm_placement"
+version = "1.0.0"
+requires-python = ">=3.10"
+dependencies = [
+    'solverforge-legacy == 1.24.1',
+    'fastapi == 0.111.0',
+    'pydantic == 2.7.3',
+    'uvicorn == 0.30.1',
+    'pytest == 8.2.2',
+]
+
+
+[project.scripts]
+run-app = "vm_placement:main"

src/vm_placement/__init__.py

@@ -0,0 +1,16 @@
+import uvicorn
+
+from .rest_api import app as app
+
+
+def main():
+    config = uvicorn.Config("vm_placement:app",
+                            port=8080,
+                            log_level="info",
+                            use_colors=True)
+    server = uvicorn.Server(config)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

src/vm_placement/constraints.py

@@ -0,0 +1,200 @@
+from solverforge_legacy.solver.score import (
+    ConstraintFactory,
+    ConstraintCollectors,
+    Joiners,
+    HardSoftScore,
+    constraint_provider,
+)
+
+from .domain import Server, VM
+
+# Constraint names
+CPU_CAPACITY = "cpuCapacity"
+MEMORY_CAPACITY = "memoryCapacity"
+STORAGE_CAPACITY = "storageCapacity"
+ANTI_AFFINITY = "antiAffinity"
+AFFINITY = "affinity"
+MINIMIZE_SERVERS_USED = "minimizeServersUsed"
+BALANCE_UTILIZATION = "balanceUtilization"
+PRIORITIZE_PLACEMENT = "prioritizePlacement"
+
+
+@constraint_provider
+def define_constraints(factory: ConstraintFactory):
+    return [
+        # Hard constraints
+        cpu_capacity(factory),
+        memory_capacity(factory),
+        storage_capacity(factory),
+        anti_affinity(factory),
+        # Soft constraints
+        affinity(factory),
+        minimize_servers_used(factory),
+        balance_utilization(factory),
+        prioritize_placement(factory),
+    ]
+
+
+##############################################
+# Hard constraints
+##############################################
+
+
+def cpu_capacity(factory: ConstraintFactory):
+    """
+    Hard constraint: Server CPU capacity cannot be exceeded.
+
+    Groups VMs by server and penalizes if total CPU exceeds capacity.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is not None)
+        .group_by(lambda vm: vm.server, ConstraintCollectors.sum(lambda vm: vm.cpu_cores))
+        .filter(lambda server, total_cpu: total_cpu > server.cpu_cores)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda server, total_cpu: total_cpu - server.cpu_cores,
+        )
+        .as_constraint(CPU_CAPACITY)
+    )
+
+
+def memory_capacity(factory: ConstraintFactory):
+    """
+    Hard constraint: Server memory capacity cannot be exceeded.
+
+    Groups VMs by server and penalizes if total memory exceeds capacity.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is not None)
+        .group_by(lambda vm: vm.server, ConstraintCollectors.sum(lambda vm: vm.memory_gb))
+        .filter(lambda server, total_memory: total_memory > server.memory_gb)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda server, total_memory: total_memory - server.memory_gb,
+        )
+        .as_constraint(MEMORY_CAPACITY)
+    )
+
+
+def storage_capacity(factory: ConstraintFactory):
+    """
+    Hard constraint: Server storage capacity cannot be exceeded.
+
+    Groups VMs by server and penalizes if total storage exceeds capacity.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is not None)
+        .group_by(lambda vm: vm.server, ConstraintCollectors.sum(lambda vm: vm.storage_gb))
+        .filter(lambda server, total_storage: total_storage > server.storage_gb)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda server, total_storage: total_storage - server.storage_gb,
+        )
+        .as_constraint(STORAGE_CAPACITY)
+    )
+
+
+def anti_affinity(factory: ConstraintFactory):
+    """
+    Hard constraint: VMs in the same anti-affinity group must be on different servers.
+
+    This is commonly used for database replicas, redundant services, etc.
+    Penalizes each pair of VMs that violate the constraint.
+    """
+    return (
+        factory.for_each_unique_pair(
+            VM,
+            Joiners.equal(lambda vm: vm.anti_affinity_group),
+            Joiners.equal(lambda vm: vm.server),
+        )
+        .filter(lambda vm1, vm2: vm1.anti_affinity_group is not None)
+        .filter(lambda vm1, vm2: vm1.server is not None)
+        .penalize(HardSoftScore.ONE_HARD)
+        .as_constraint(ANTI_AFFINITY)
+    )
+
+
+##############################################
+# Soft constraints
+##############################################
+
+
+def affinity(factory: ConstraintFactory):
+    """
+    Soft constraint: VMs in the same affinity group should be on the same server.
+
+    This is commonly used for tightly coupled services that benefit from
+    low-latency communication. Penalizes each pair of VMs on different servers.
+    """
+    return (
+        factory.for_each_unique_pair(
+            VM,
+            Joiners.equal(lambda vm: vm.affinity_group),
+        )
+        .filter(lambda vm1, vm2: vm1.affinity_group is not None)
+        .filter(lambda vm1, vm2: vm1.server is not None and vm2.server is not None)
+        .filter(lambda vm1, vm2: vm1.server != vm2.server)
+        .penalize(HardSoftScore.ONE_SOFT, lambda vm1, vm2: 100)
+        .as_constraint(AFFINITY)
+    )
+
+
+def minimize_servers_used(factory: ConstraintFactory):
+    """
+    Soft constraint: Minimize the number of servers in use.
+
+    Consolidating VMs onto fewer servers reduces power consumption,
+    cooling costs, and management overhead. Each active server incurs a cost.
+
+    Weight is lower than prioritize_placement to ensure VMs get assigned
+    before optimizing for server consolidation.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is not None)
+        .group_by(lambda vm: vm.server, ConstraintCollectors.count())
+        .penalize(HardSoftScore.ONE_SOFT, lambda server, count: 100)
+        .as_constraint(MINIMIZE_SERVERS_USED)
+    )
+
+
+def balance_utilization(factory: ConstraintFactory):
+    """
+    Soft constraint: Balance utilization across active servers.
+
+    Avoids hotspots by penalizing servers with high utilization.
+    Uses a squared penalty to favor balanced distribution over consolidation
+    when both are possible.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is not None)
+        .group_by(lambda vm: vm.server, ConstraintCollectors.sum(lambda vm: vm.cpu_cores))
+        .penalize(
+            HardSoftScore.ONE_SOFT,
+            lambda server, total_cpu: int((total_cpu / server.cpu_cores) ** 2 * 10) if server.cpu_cores > 0 else 0,
+        )
+        .as_constraint(BALANCE_UTILIZATION)
+    )
+
+
+def prioritize_placement(factory: ConstraintFactory):
+    """
+    Soft constraint: Higher-priority VMs should be placed.
+
+    Penalizes unassigned VMs weighted by their priority. Higher priority VMs
+    incur a larger penalty when unassigned, encouraging the solver to place
+    them first.
+
+    Base penalty of 10000 ensures VMs are always placed before optimizing
+    other soft constraints. Priority adds 0-5000 additional penalty.
+    """
+    return (
+        factory.for_each(VM)
+        .filter(lambda vm: vm.server is None)
+        .penalize(HardSoftScore.ONE_SOFT, lambda vm: 10000 + vm.priority * 1000)
+        .as_constraint(PRIORITIZE_PLACEMENT)
+    )

src/vm_placement/converters.py

@@ -0,0 +1,161 @@
+from . import domain
+
+
+# Conversion functions from domain to API models
+def vm_to_model(vm: domain.VM) -> domain.VMModel:
+    # Handle both Server objects and string IDs
+    server_id = None
+    if vm.server:
+        server_id = vm.server if isinstance(vm.server, str) else vm.server.id
+    return domain.VMModel(
+        id=vm.id,
+        name=vm.name,
+        cpu_cores=vm.cpu_cores,
+        memory_gb=vm.memory_gb,
+        storage_gb=vm.storage_gb,
+        priority=vm.priority,
+        affinity_group=vm.affinity_group,
+        anti_affinity_group=vm.anti_affinity_group,
+        server=server_id,
+    )
+
+
+def server_to_model(server: domain.Server, plan: domain.VMPlacementPlan) -> domain.ServerModel:
+    """Convert a Server to ServerModel, computing VM assignments from the plan."""
+    # Get VMs assigned to this server
+    vms_on_server = [vm for vm in plan.vms if vm.server == server]
+    vm_ids = [vm.id for vm in vms_on_server]
+
+    # Compute utilization
+    used_cpu = sum(vm.cpu_cores for vm in vms_on_server)
+    used_memory = sum(vm.memory_gb for vm in vms_on_server)
+    used_storage = sum(vm.storage_gb for vm in vms_on_server)
+
+    cpu_utilization = used_cpu / server.cpu_cores if server.cpu_cores > 0 else 0.0
+    memory_utilization = used_memory / server.memory_gb if server.memory_gb > 0 else 0.0
+    storage_utilization = used_storage / server.storage_gb if server.storage_gb > 0 else 0.0
+
+    return domain.ServerModel(
+        id=server.id,
+        name=server.name,
+        cpu_cores=server.cpu_cores,
+        memory_gb=server.memory_gb,
+        storage_gb=server.storage_gb,
+        rack=server.rack,
+        vms=vm_ids,
+        used_cpu=used_cpu,
+        used_memory=used_memory,
+        used_storage=used_storage,
+        cpu_utilization=cpu_utilization,
+        memory_utilization=memory_utilization,
+        storage_utilization=storage_utilization,
+    )
+
+
+def plan_to_model(plan: domain.VMPlacementPlan) -> domain.VMPlacementPlanModel:
+    return domain.VMPlacementPlanModel(
+        name=plan.name,
+        servers=[server_to_model(s, plan) for s in plan.servers],
+        vms=[vm_to_model(vm) for vm in plan.vms],
+        score=str(plan.score) if plan.score else None,
+        solver_status=plan.solver_status.name if plan.solver_status else None,
+        total_servers=plan.total_servers,
+        active_servers=plan.active_servers,
+        unassigned_vms=plan.unassigned_vms,
+        total_cpu_utilization=plan.total_cpu_utilization,
+        total_memory_utilization=plan.total_memory_utilization,
+        total_storage_utilization=plan.total_storage_utilization,
+    )
+
+
+# Conversion functions from API models to domain
+def model_to_vm(model: domain.VMModel, server_lookup: dict) -> domain.VM:
+    server = None
+    if model.server:
+        if isinstance(model.server, str):
+            server = server_lookup.get(model.server)
+        else:
+            server = server_lookup.get(model.server.id)
+
+    return domain.VM(
+        id=model.id,
+        name=model.name,
+        cpu_cores=model.cpu_cores,
+        memory_gb=model.memory_gb,
+        storage_gb=model.storage_gb,
+        priority=model.priority,
+        affinity_group=model.affinity_group,
+        anti_affinity_group=model.anti_affinity_group,
+        server=server,
+    )
+
+
+def model_to_server(model: domain.ServerModel) -> domain.Server:
+    """Convert ServerModel to Server (Server no longer has vms list)."""
+    return domain.Server(
+        id=model.id,
+        name=model.name,
+        cpu_cores=model.cpu_cores,
+        memory_gb=model.memory_gb,
+        storage_gb=model.storage_gb,
+        rack=model.rack,
+    )
+
+
+def model_to_plan(model: domain.VMPlacementPlanModel) -> domain.VMPlacementPlan:
+    # Convert servers first
+    servers = []
+    for server_model in model.servers:
+        server = domain.Server(
+            id=server_model.id,
+            name=server_model.name,
+            cpu_cores=server_model.cpu_cores,
+            memory_gb=server_model.memory_gb,
+            storage_gb=server_model.storage_gb,
+            rack=server_model.rack,
+        )
+        servers.append(server)
+
+    # Create server lookup
+    server_lookup = {s.id: s for s in servers}
+
+    # Convert VMs with server references
+    vms = []
+    for vm_model in model.vms:
+        # Get server reference from VM's server field
+        server = None
+        if vm_model.server:
+            server_id = vm_model.server if isinstance(vm_model.server, str) else vm_model.server.id
+            server = server_lookup.get(server_id)
+
+        vm = domain.VM(
+            id=vm_model.id,
+            name=vm_model.name,
+            cpu_cores=vm_model.cpu_cores,
+            memory_gb=vm_model.memory_gb,
+            storage_gb=vm_model.storage_gb,
+            priority=vm_model.priority,
+            affinity_group=vm_model.affinity_group,
+            anti_affinity_group=vm_model.anti_affinity_group,
+            server=server,
+        )
+        vms.append(vm)
+
+    # Handle score
+    score = None
+    if model.score:
+        from solverforge_legacy.solver.score import HardSoftScore
+        score = HardSoftScore.parse(model.score)
+
+    # Handle solver status
+    solver_status = domain.SolverStatus.NOT_SOLVING
+    if model.solver_status:
+        solver_status = domain.SolverStatus[model.solver_status]
+
+    return domain.VMPlacementPlan(
+        name=model.name,
+        servers=servers,
+        vms=vms,
+        score=score,
+        solver_status=solver_status,
+    )

src/vm_placement/demo_data.py

@@ -0,0 +1,449 @@
+from enum import Enum
+import random
+from .domain import Server, VM, VMPlacementPlan
+
+
+class DemoData(Enum):
+    SMALL = "SMALL"
+    MEDIUM = "MEDIUM"
+    LARGE = "LARGE"
+
+
+def generate_custom_data(
+    rack_count: int = 3,
+    servers_per_rack: int = 4,
+    vm_count: int = 20
+) -> VMPlacementPlan:
+    """
+    Generate custom demo data with configurable infrastructure and workload.
+
+    Args:
+        rack_count: Number of racks (1-8)
+        servers_per_rack: Number of servers per rack (2-10)
+        vm_count: Number of VMs to place (5-200)
+    """
+    rack_count = max(1, min(8, rack_count))
+    servers_per_rack = max(2, min(10, servers_per_rack))
+    vm_count = max(5, min(200, vm_count))
+
+    servers = []
+    server_id = 1
+
+    # Generate rack names
+    rack_names = [f"rack-{chr(ord('a') + i)}" for i in range(rack_count)]
+
+    # Server templates: (cpu_cores, memory_gb, storage_gb, name_prefix)
+    server_templates = [
+        (48, 192, 2000, "large"),
+        (32, 128, 1000, "large"),
+        (24, 96, 1000, "medium"),
+        (16, 64, 512, "medium"),
+        (12, 48, 500, "small"),
+        (8, 32, 256, "small"),
+    ]
+
+    for rack_idx, rack_name in enumerate(rack_names):
+        for server_idx in range(servers_per_rack):
+            # Alternate between server sizes for variety
+            template_idx = (rack_idx + server_idx) % len(server_templates)
+            cpu, mem, storage, size = server_templates[template_idx]
+
+            servers.append(Server(
+                id=f"s{server_id}",
+                name=f"srv-{size}-{server_id:02d}",
+                cpu_cores=cpu,
+                memory_gb=mem,
+                storage_gb=storage,
+                rack=rack_name
+            ))
+            server_id += 1
+
+    vms = []
+    vm_id = 1
+
+    # VM templates: (cpu_cores, memory_gb, storage_gb, name_prefix, priority, group_type)
+    # group_type: None, "affinity", "anti-affinity"
+    vm_templates = [
+        # Critical database VMs - anti-affinity for HA
+        (8, 32, 200, "db", 5, "anti-affinity"),
+        # API servers
+        (4, 8, 50, "api", 4, None),
+        # Web tier - affinity for locality
+        (2, 4, 20, "web", 3, "affinity"),
+        # Cache tier - affinity
+        (4, 16, 30, "cache", 3, "affinity"),
+        # Workers
+        (2, 4, 40, "worker", 2, None),
+        # Dev/test - low priority
+        (2, 4, 30, "dev", 1, None),
+    ]
+
+    # Distribute VMs across templates
+    template_weights = [0.08, 0.15, 0.20, 0.10, 0.32, 0.15]  # Proportions
+
+    # Track affinity/anti-affinity group counts
+    affinity_groups = {}
+    anti_affinity_groups = {}
+
+    for i in range(vm_count):
+        # Pick template based on weighted distribution
+        rand_val = random.random()
+        cumulative = 0
+        template_idx = 0
+        for idx, weight in enumerate(template_weights):
+            cumulative += weight
+            if rand_val <= cumulative:
+                template_idx = idx
+                break
+
+        cpu, mem, storage, prefix, priority, group_type = vm_templates[template_idx]
+
+        # Determine group assignment
+        affinity_group = None
+        anti_affinity_group = None
+
+        if group_type == "affinity":
+            group_name = f"{prefix}-tier"
+            affinity_groups[group_name] = affinity_groups.get(group_name, 0) + 1
+            affinity_group = group_name
+        elif group_type == "anti-affinity":
+            # Create multiple anti-affinity clusters (max 3-5 VMs per cluster)
+            cluster_num = anti_affinity_groups.get(prefix, 0) // 4 + 1
+            group_name = f"{prefix}-cluster-{cluster_num}"
+            anti_affinity_groups[prefix] = anti_affinity_groups.get(prefix, 0) + 1
+            anti_affinity_group = group_name
+
+        # Count VMs with this prefix
+        count = sum(1 for v in vms if v.name.startswith(prefix)) + 1
+
+        vms.append(VM(
+            id=f"vm{vm_id}",
+            name=f"{prefix}-{count:02d}",
+            cpu_cores=cpu,
+            memory_gb=mem,
+            storage_gb=storage,
+            priority=priority,
+            affinity_group=affinity_group,
+            anti_affinity_group=anti_affinity_group
+        ))
+        vm_id += 1
+
+    total_servers = rack_count * servers_per_rack
+    return VMPlacementPlan(
+        name=f"CUSTOM ({total_servers} servers, {vm_count} VMs)",
+        servers=servers,
+        vms=vms
+    )
+
+
+def generate_demo_data(demo: DemoData) -> VMPlacementPlan:
+    """Generate demo data for the specified demo type."""
+    if demo == DemoData.SMALL:
+        return _generate_small()
+    elif demo == DemoData.MEDIUM:
+        return _generate_medium()
+    elif demo == DemoData.LARGE:
+        return _generate_large()
+    else:
+        raise ValueError(f"Unknown demo: {demo}")
+
+
+def _generate_small() -> VMPlacementPlan:
+    """
+    Small demo: 5 servers, 20 VMs
+    - 2 large servers (32 cores, 128GB, 1TB)
+    - 3 medium servers (16 cores, 64GB, 512GB)
+    - Mix of small, medium, and large VMs
+    - Includes affinity and anti-affinity groups
+    """
+    servers = [
+        # Large servers
+        Server(id="s1", name="server-large-01", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-a"),
+        Server(id="s2", name="server-large-02", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-b"),
+        # Medium servers
+        Server(id="s3", name="server-medium-01", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-a"),
+        Server(id="s4", name="server-medium-02", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-b"),
+        Server(id="s5", name="server-medium-03", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-a"),
+    ]
+
+    vms = [
+        # Web tier (affinity group - should be together)
+        VM(id="vm1", name="web-01", cpu_cores=2, memory_gb=4, storage_gb=20, priority=3, affinity_group="web-tier"),
+        VM(id="vm2", name="web-02", cpu_cores=2, memory_gb=4, storage_gb=20, priority=3, affinity_group="web-tier"),
+        VM(id="vm3", name="web-03", cpu_cores=2, memory_gb=4, storage_gb=20, priority=3, affinity_group="web-tier"),
+
+        # Database replicas (anti-affinity - must be on different servers)
+        VM(id="vm4", name="db-primary", cpu_cores=8, memory_gb=32, storage_gb=200, priority=5, anti_affinity_group="db-cluster"),
+        VM(id="vm5", name="db-replica-1", cpu_cores=8, memory_gb=32, storage_gb=200, priority=5, anti_affinity_group="db-cluster"),
+        VM(id="vm6", name="db-replica-2", cpu_cores=8, memory_gb=32, storage_gb=200, priority=4, anti_affinity_group="db-cluster"),
+
+        # API servers
+        VM(id="vm7", name="api-01", cpu_cores=4, memory_gb=8, storage_gb=50, priority=4),
+        VM(id="vm8", name="api-02", cpu_cores=4, memory_gb=8, storage_gb=50, priority=4),
+
+        # Cache servers (affinity - benefit from being together)
+        VM(id="vm9", name="cache-01", cpu_cores=4, memory_gb=16, storage_gb=30, priority=3, affinity_group="cache-tier"),
+        VM(id="vm10", name="cache-02", cpu_cores=4, memory_gb=16, storage_gb=30, priority=3, affinity_group="cache-tier"),
+
+        # Worker nodes
+        VM(id="vm11", name="worker-01", cpu_cores=2, memory_gb=4, storage_gb=40, priority=2),
+        VM(id="vm12", name="worker-02", cpu_cores=2, memory_gb=4, storage_gb=40, priority=2),
+        VM(id="vm13", name="worker-03", cpu_cores=2, memory_gb=4, storage_gb=40, priority=2),
+        VM(id="vm14", name="worker-04", cpu_cores=2, memory_gb=4, storage_gb=40, priority=2),
+
+        # Monitoring
+        VM(id="vm15", name="monitoring", cpu_cores=4, memory_gb=8, storage_gb=100, priority=3),
+        VM(id="vm16", name="logging", cpu_cores=4, memory_gb=8, storage_gb=150, priority=3),
+
+        # Dev/test VMs (lower priority)
+        VM(id="vm17", name="dev-01", cpu_cores=2, memory_gb=4, storage_gb=30, priority=1),
+        VM(id="vm18", name="dev-02", cpu_cores=2, memory_gb=4, storage_gb=30, priority=1),
+        VM(id="vm19", name="test-01", cpu_cores=2, memory_gb=4, storage_gb=30, priority=1),
+        VM(id="vm20", name="test-02", cpu_cores=2, memory_gb=4, storage_gb=30, priority=1),
+    ]
+
+    return VMPlacementPlan(name="SMALL", servers=servers, vms=vms)
+
+
+def _generate_medium() -> VMPlacementPlan:
+    """
+    Medium demo: 10 servers, 50 VMs
+    - Realistic small cluster scenario
+    - Multiple affinity and anti-affinity groups
+    """
+    servers = [
+        # Large servers (rack-a)
+        Server(id="s1", name="server-large-01", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-a"),
+        Server(id="s2", name="server-large-02", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-a"),
+        Server(id="s3", name="server-large-03", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-b"),
+        Server(id="s4", name="server-large-04", cpu_cores=32, memory_gb=128, storage_gb=1000, rack="rack-b"),
+        # Medium servers
+        Server(id="s5", name="server-medium-01", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-a"),
+        Server(id="s6", name="server-medium-02", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-a"),
+        Server(id="s7", name="server-medium-03", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-b"),
+        Server(id="s8", name="server-medium-04", cpu_cores=16, memory_gb=64, storage_gb=512, rack="rack-b"),
+        # Small servers
+        Server(id="s9", name="server-small-01", cpu_cores=8, memory_gb=32, storage_gb=256, rack="rack-a"),
+        Server(id="s10", name="server-small-02", cpu_cores=8, memory_gb=32, storage_gb=256, rack="rack-b"),
+    ]
+
+    vms = []
+    vm_id = 1
+
+    # Web tier (6 VMs, affinity)
+    for i in range(6):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"web-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=20,
+            priority=3, affinity_group="web-tier"
+        ))
+        vm_id += 1
+
+    # Database cluster (3 VMs, anti-affinity)
+    for i, name in enumerate(["db-primary", "db-replica-1", "db-replica-2"]):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=name,
+            cpu_cores=8, memory_gb=32, storage_gb=200,
+            priority=5, anti_affinity_group="db-cluster"
+        ))
+        vm_id += 1
+
+    # API servers (8 VMs)
+    for i in range(8):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"api-{i+1:02d}",
+            cpu_cores=4, memory_gb=8, storage_gb=50,
+            priority=4
+        ))
+        vm_id += 1
+
+    # Cache tier (4 VMs, affinity)
+    for i in range(4):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"cache-{i+1:02d}",
+            cpu_cores=4, memory_gb=16, storage_gb=30,
+            priority=3, affinity_group="cache-tier"
+        ))
+        vm_id += 1
+
+    # Worker nodes (12 VMs)
+    for i in range(12):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"worker-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=40,
+            priority=2
+        ))
+        vm_id += 1
+
+    # Analytics cluster (3 VMs, anti-affinity for HA)
+    for i in range(3):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"analytics-{i+1:02d}",
+            cpu_cores=8, memory_gb=24, storage_gb=150,
+            priority=3, anti_affinity_group="analytics-cluster"
+        ))
+        vm_id += 1
+
+    # Monitoring & logging (4 VMs)
+    for name in ["prometheus", "grafana", "elasticsearch", "kibana"]:
+        vms.append(VM(
+            id=f"vm{vm_id}", name=name,
+            cpu_cores=4, memory_gb=8, storage_gb=100,
+            priority=3
+        ))
+        vm_id += 1
+
+    # CI/CD (2 VMs)
+    for name in ["jenkins", "gitlab-runner"]:
+        vms.append(VM(
+            id=f"vm{vm_id}", name=name,
+            cpu_cores=4, memory_gb=8, storage_gb=80,
+            priority=2
+        ))
+        vm_id += 1
+
+    # Dev/test VMs (6 VMs, lower priority)
+    for i in range(6):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"dev-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=30,
+            priority=1
+        ))
+        vm_id += 1
+
+    return VMPlacementPlan(name="MEDIUM", servers=servers, vms=vms)
+
+
+def _generate_large() -> VMPlacementPlan:
+    """
+    Large demo: 20 servers, 100 VMs
+    - Stress test scenario
+    - Multiple racks for anti-affinity
+    """
+    servers = []
+    server_id = 1
+    racks = ["rack-a", "rack-b", "rack-c", "rack-d"]
+
+    # Large servers (8)
+    for i in range(8):
+        servers.append(Server(
+            id=f"s{server_id}", name=f"server-large-{i+1:02d}",
+            cpu_cores=48, memory_gb=192, storage_gb=2000,
+            rack=racks[i % len(racks)]
+        ))
+        server_id += 1
+
+    # Medium servers (8)
+    for i in range(8):
+        servers.append(Server(
+            id=f"s{server_id}", name=f"server-medium-{i+1:02d}",
+            cpu_cores=24, memory_gb=96, storage_gb=1000,
+            rack=racks[i % len(racks)]
+        ))
+        server_id += 1
+
+    # Small servers (4)
+    for i in range(4):
+        servers.append(Server(
+            id=f"s{server_id}", name=f"server-small-{i+1:02d}",
+            cpu_cores=12, memory_gb=48, storage_gb=500,
+            rack=racks[i % len(racks)]
+        ))
+        server_id += 1
+
+    vms = []
+    vm_id = 1
+
+    # Web tier (12 VMs, affinity)
+    for i in range(12):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"web-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=20,
+            priority=3, affinity_group="web-tier"
+        ))
+        vm_id += 1
+
+    # Database clusters (2 clusters, 3 VMs each, anti-affinity)
+    for cluster in range(2):
+        for i in range(3):
+            role = "primary" if i == 0 else f"replica-{i}"
+            vms.append(VM(
+                id=f"vm{vm_id}", name=f"db-cluster{cluster+1}-{role}",
+                cpu_cores=8, memory_gb=32, storage_gb=300,
+                priority=5, anti_affinity_group=f"db-cluster-{cluster+1}"
+            ))
+            vm_id += 1
+
+    # API servers (16 VMs)
+    for i in range(16):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"api-{i+1:02d}",
+            cpu_cores=4, memory_gb=8, storage_gb=50,
+            priority=4
+        ))
+        vm_id += 1
+
+    # Cache tier (8 VMs, affinity)
+    for i in range(8):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"cache-{i+1:02d}",
+            cpu_cores=4, memory_gb=24, storage_gb=30,
+            priority=3, affinity_group="cache-tier"
+        ))
+        vm_id += 1
+
+    # Worker nodes (24 VMs)
+    for i in range(24):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"worker-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=40,
+            priority=2
+        ))
+        vm_id += 1
+
+    # Message queue cluster (3 VMs, anti-affinity)
+    for i in range(3):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"kafka-{i+1:02d}",
+            cpu_cores=4, memory_gb=16, storage_gb=200,
+            priority=4, anti_affinity_group="kafka-cluster"
+        ))
+        vm_id += 1
+
+    # Search cluster (5 VMs, anti-affinity)
+    for i in range(5):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"elasticsearch-{i+1:02d}",
+            cpu_cores=6, memory_gb=24, storage_gb=250,
+            priority=3, anti_affinity_group="search-cluster"
+        ))
+        vm_id += 1
+
+    # Monitoring stack (6 VMs)
+    for name in ["prometheus", "grafana", "alertmanager", "thanos-query", "thanos-store", "thanos-compact"]:
+        vms.append(VM(
+            id=f"vm{vm_id}", name=name,
+            cpu_cores=4, memory_gb=8, storage_gb=100,
+            priority=3
+        ))
+        vm_id += 1
+
+    # CI/CD (4 VMs)
+    for name in ["jenkins-master", "jenkins-agent-1", "jenkins-agent-2", "artifact-repo"]:
+        vms.append(VM(
+            id=f"vm{vm_id}", name=name,
+            cpu_cores=4, memory_gb=8, storage_gb=120,
+            priority=2
+        ))
+        vm_id += 1
+
+    # Dev/test VMs (10 VMs, lower priority)
+    for i in range(10):
+        vms.append(VM(
+            id=f"vm{vm_id}", name=f"dev-{i+1:02d}",
+            cpu_cores=2, memory_gb=4, storage_gb=30,
+            priority=1
+        ))
+        vm_id += 1
+
+    return VMPlacementPlan(name="LARGE", servers=servers, vms=vms)

src/vm_placement/domain.py

@@ -0,0 +1,206 @@
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.score import HardSoftScore
+from solverforge_legacy.solver.domain import (
+    planning_entity,
+    planning_solution,
+    PlanningId,
+    PlanningScore,
+    PlanningVariable,
+    PlanningEntityCollectionProperty,
+    ProblemFactCollectionProperty,
+    ValueRangeProvider,
+)
+
+from typing import Annotated, Optional, List, Union
+from dataclasses import dataclass, field
+from .json_serialization import (
+    JsonDomainBase,
+    IdSerializer,
+    IdListSerializer,
+    VMListValidator,
+    ServerValidator,
+)
+from pydantic import Field
+
+
+@dataclass
+class Server:
+    """
+    A physical server that can host virtual machines.
+
+    Servers have capacity limits for CPU cores, memory (GB), and storage (GB).
+    This is a problem fact - it doesn't change during solving.
+    """
+
+    id: Annotated[str, PlanningId]
+    name: str
+    cpu_cores: int
+    memory_gb: int
+    storage_gb: int
+    rack: Optional[str] = None
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f"Server({self.id}, {self.name})"
+
+    def __hash__(self):
+        return hash(self.id)
+
+    def __eq__(self, other):
+        if not isinstance(other, Server):
+            return False
+        return self.id == other.id
+
+
+@planning_entity
+@dataclass
+class VM:
+    """
+    A virtual machine that needs to be placed on a server.
+
+    VMs have resource requirements (CPU, memory, storage) and optional
+    affinity/anti-affinity constraints for placement.
+    The server field is the planning variable that the solver optimizes.
+    """
+
+    id: Annotated[str, PlanningId]
+    name: str
+    cpu_cores: int
+    memory_gb: int
+    storage_gb: int
+    priority: int = 1
+    affinity_group: Optional[str] = None
+    anti_affinity_group: Optional[str] = None
+    server: Annotated[Optional[Server], PlanningVariable] = None
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f"VM({self.id}, {self.name})"
+
+
+@planning_solution
+@dataclass
+class VMPlacementPlan:
+    """
+    The planning solution containing all servers and VMs.
+
+    The solver will assign VMs to servers while respecting capacity constraints,
+    affinity/anti-affinity rules, and optimizing for consolidation and balance.
+    """
+
+    name: str
+    servers: Annotated[list[Server], ProblemFactCollectionProperty, ValueRangeProvider]
+    vms: Annotated[list[VM], PlanningEntityCollectionProperty]
+    score: Annotated[Optional[HardSoftScore], PlanningScore] = None
+    solver_status: SolverStatus = SolverStatus.NOT_SOLVING
+
+    def get_vms_on_server(self, server: Server) -> list:
+        """Get all VMs assigned to a specific server."""
+        return [vm for vm in self.vms if vm.server == server]
+
+    def get_server_used_cpu(self, server: Server) -> int:
+        """Get total CPU cores used on a server."""
+        return sum(vm.cpu_cores for vm in self.vms if vm.server == server)
+
+    def get_server_used_memory(self, server: Server) -> int:
+        """Get total memory (GB) used on a server."""
+        return sum(vm.memory_gb for vm in self.vms if vm.server == server)
+
+    def get_server_used_storage(self, server: Server) -> int:
+        """Get total storage (GB) used on a server."""
+        return sum(vm.storage_gb for vm in self.vms if vm.server == server)
+
+    @property
+    def total_servers(self) -> int:
+        return len(self.servers)
+
+    @property
+    def active_servers(self) -> int:
+        active_server_ids = set(vm.server.id for vm in self.vms if vm.server is not None)
+        return len(active_server_ids)
+
+    @property
+    def unassigned_vms(self) -> int:
+        return sum(1 for vm in self.vms if vm.server is None)
+
+    @property
+    def total_cpu_utilization(self) -> float:
+        total_capacity = sum(s.cpu_cores for s in self.servers)
+        total_used = sum(vm.cpu_cores for vm in self.vms if vm.server is not None)
+        if total_capacity == 0:
+            return 0.0
+        return total_used / total_capacity
+
+    @property
+    def total_memory_utilization(self) -> float:
+        total_capacity = sum(s.memory_gb for s in self.servers)
+        total_used = sum(vm.memory_gb for vm in self.vms if vm.server is not None)
+        if total_capacity == 0:
+            return 0.0
+        return total_used / total_capacity
+
+    @property
+    def total_storage_utilization(self) -> float:
+        total_capacity = sum(s.storage_gb for s in self.servers)
+        total_used = sum(vm.storage_gb for vm in self.vms if vm.server is not None)
+        if total_capacity == 0:
+            return 0.0
+        return total_used / total_capacity
+
+    def __str__(self):
+        return f"VMPlacementPlan(name={self.name}, servers={len(self.servers)}, vms={len(self.vms)})"
+
+
+# Pydantic REST models for API (used for deserialization and context)
+class VMModel(JsonDomainBase):
+    id: str
+    name: str
+    cpu_cores: int = Field(..., alias="cpuCores")
+    memory_gb: int = Field(..., alias="memoryGb")
+    storage_gb: int = Field(..., alias="storageGb")
+    priority: int = 1
+    affinity_group: Optional[str] = Field(None, alias="affinityGroup")
+    anti_affinity_group: Optional[str] = Field(None, alias="antiAffinityGroup")
+    server: Annotated[
+        Union[str, "ServerModel", None],
+        IdSerializer,
+        ServerValidator,
+    ] = None
+
+
+class ServerModel(JsonDomainBase):
+    id: str
+    name: str
+    cpu_cores: int = Field(..., alias="cpuCores")
+    memory_gb: int = Field(..., alias="memoryGb")
+    storage_gb: int = Field(..., alias="storageGb")
+    rack: Optional[str] = None
+    vms: Annotated[
+        List[Union[str, VMModel]],
+        IdListSerializer,
+        VMListValidator,
+    ] = Field(default_factory=list)
+    used_cpu: int = Field(0, alias="usedCpu")
+    used_memory: int = Field(0, alias="usedMemory")
+    used_storage: int = Field(0, alias="usedStorage")
+    cpu_utilization: float = Field(0.0, alias="cpuUtilization")
+    memory_utilization: float = Field(0.0, alias="memoryUtilization")
+    storage_utilization: float = Field(0.0, alias="storageUtilization")
+
+
+class VMPlacementPlanModel(JsonDomainBase):
+    name: str
+    servers: List[ServerModel]
+    vms: List[VMModel]
+    score: Optional[str] = None
+    solver_status: Optional[str] = Field(None, alias="solverStatus")
+    total_servers: int = Field(0, alias="totalServers")
+    active_servers: int = Field(0, alias="activeServers")
+    unassigned_vms: int = Field(0, alias="unassignedVms")
+    total_cpu_utilization: float = Field(0.0, alias="totalCpuUtilization")
+    total_memory_utilization: float = Field(0.0, alias="totalMemoryUtilization")
+    total_storage_utilization: float = Field(0.0, alias="totalStorageUtilization")

src/vm_placement/json_serialization.py

@@ -0,0 +1,81 @@
+from solverforge_legacy.solver.score import HardSoftScore
+
+from typing import Any
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    PlainSerializer,
+    BeforeValidator,
+    ValidationInfo,
+)
+from pydantic.alias_generators import to_camel
+
+
+class JsonDomainBase(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def make_id_item_validator(key: str):
+    def validator(v: Any, info: ValidationInfo) -> Any:
+        if v is None:
+            return None
+
+        if not isinstance(v, str) or not info.context:
+            return v
+
+        return info.context.get(key)[v]
+
+    return BeforeValidator(validator)
+
+
+def make_id_list_item_validator(key: str):
+    def validator(v: Any, info: ValidationInfo) -> Any:
+        if v is None:
+            return None
+
+        if isinstance(v, (list, tuple)):
+            out = []
+            for item in v:
+                if not isinstance(item, str) or not info.context:
+                    return v
+                out.append(info.context.get(key)[item])
+            return out
+
+        return v
+
+    return BeforeValidator(validator)
+
+
+ScoreSerializer = PlainSerializer(
+    lambda score: str(score) if score is not None else None, return_type=str | None
+)
+IdSerializer = PlainSerializer(
+    lambda item: item if isinstance(item, str) else (item.id if item is not None else None),
+    return_type=str | None
+)
+IdListSerializer = PlainSerializer(
+    lambda items: [item if isinstance(item, str) else item.id for item in items],
+    return_type=list
+)
+
+VMListValidator = make_id_list_item_validator("vms")
+VMValidator = make_id_item_validator("vms")
+ServerValidator = make_id_item_validator("servers")
+
+
+def validate_score(v: Any, info: ValidationInfo) -> Any:
+    if isinstance(v, HardSoftScore) or v is None:
+        return v
+    if isinstance(v, str):
+        # Handle "None" string or empty string as null
+        if v in ("None", "null", ""):
+            return None
+        return HardSoftScore.parse(v)
+    raise ValueError('"score" should be a string')
+
+
+ScoreValidator = BeforeValidator(validate_score)

src/vm_placement/rest_api.py

@@ -0,0 +1,150 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.staticfiles import StaticFiles
+from uuid import uuid4
+from typing import Dict, List
+from dataclasses import asdict
+from enum import Enum
+import logging
+
+from .domain import VMPlacementPlan, VMPlacementPlanModel
+from .converters import plan_to_model, model_to_plan
+from .demo_data import generate_demo_data, generate_custom_data, DemoData
+from .solver import solver_manager, solution_manager
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(docs_url='/q/swagger-ui')
+
+data_sets: Dict[str, VMPlacementPlan] = {}
+
+
+class ConstraintMatchDTO(BaseModel):
+    name: str
+    score: str
+    justification: str
+
+
+class ConstraintAnalysisDTO(BaseModel):
+    name: str
+    weight: str
+    score: str
+    matches: List[ConstraintMatchDTO]
+
+
+@app.get("/demo-data")
+async def get_demo_data():
+    """Get available demo data sets."""
+    return [demo.name for demo in DemoData]
+
+
+@app.get("/demo-data/{demo_name}", response_model=VMPlacementPlanModel)
+async def get_demo_data_by_name(demo_name: str) -> VMPlacementPlanModel:
+    """Get a specific demo data set."""
+    try:
+        demo_data = DemoData[demo_name]
+        domain_plan = generate_demo_data(demo_data)
+        return plan_to_model(domain_plan)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"Demo data '{demo_name}' not found")
+
+
+class CustomDataRequest(BaseModel):
+    rack_count: int = Field(default=3, ge=1, le=8, description="Number of racks")
+    servers_per_rack: int = Field(default=4, ge=2, le=10, description="Servers per rack")
+    vm_count: int = Field(default=20, ge=5, le=200, description="Number of VMs")
+
+
+@app.post("/demo-data/generate", response_model=VMPlacementPlanModel)
+async def generate_custom_demo_data(request: CustomDataRequest) -> VMPlacementPlanModel:
+    """Generate custom demo data with configurable infrastructure and workload."""
+    domain_plan = generate_custom_data(
+        rack_count=request.rack_count,
+        servers_per_rack=request.servers_per_rack,
+        vm_count=request.vm_count
+    )
+    return plan_to_model(domain_plan)
+
+
+@app.get("/placements/{problem_id}", response_model=VMPlacementPlanModel, response_model_exclude_none=True)
+async def get_placement(problem_id: str) -> VMPlacementPlanModel:
+    """Get the current VM placement solution for a given job ID."""
+    placement = data_sets.get(problem_id)
+    if not placement:
+        raise HTTPException(status_code=404, detail="Placement plan not found")
+    placement.solver_status = solver_manager.get_solver_status(problem_id)
+    return plan_to_model(placement)
+
+
+@app.post("/placements")
+async def solve_placement(plan_model: VMPlacementPlanModel) -> str:
+    """Start solving a VM placement problem. Returns a job ID."""
+    job_id = str(uuid4())
+    domain_plan = model_to_plan(plan_model)
+    data_sets[job_id] = domain_plan
+    solver_manager.solve_and_listen(
+        job_id,
+        domain_plan,
+        lambda solution: data_sets.update({job_id: solution})
+    )
+    return job_id
+
+
+@app.put("/placements/analyze")
+async def analyze_placement(plan_model: VMPlacementPlanModel) -> dict:
+    """Analyze constraints for a given VM placement solution."""
+    domain_plan = model_to_plan(plan_model)
+    analysis = solution_manager.analyze(domain_plan)
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            ConstraintMatchDTO(
+                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(ConstraintAnalysisDTO(
+            name=str(getattr(constraint, 'constraint_name', "")),
+            weight=str(getattr(constraint, 'weight', "0hard/0soft")),
+            score=str(getattr(constraint, 'score', "0hard/0soft")),
+            matches=matches
+        ))
+    return {"constraints": [c.model_dump() for c in constraints]}
+
+
+@app.get("/placements")
+async def list_placements() -> List[str]:
+    """List the job IDs of all submitted placement problems."""
+    return list(data_sets.keys())
+
+
+@app.get("/placements/{problem_id}/status")
+async def get_placement_status(problem_id: str) -> dict:
+    """Get the placement status and score for a given job ID."""
+    placement = data_sets.get(problem_id)
+    if not placement:
+        raise HTTPException(status_code=404, detail="Placement plan not found")
+    solver_status = solver_manager.get_solver_status(problem_id)
+    return {
+        "name": placement.name,
+        "score": str(placement.score) if placement.score else None,
+        "solverStatus": solver_status.name if solver_status else None,
+        "activeServers": placement.active_servers,
+        "unassignedVms": placement.unassigned_vms,
+    }
+
+
+@app.delete("/placements/{problem_id}", response_model=VMPlacementPlanModel)
+async def stop_solving(problem_id: str) -> VMPlacementPlanModel:
+    """Terminate solving for a given job ID. Returns the best solution so far."""
+    solver_manager.terminate_early(problem_id)
+    placement = data_sets.get(problem_id)
+    if not placement:
+        raise HTTPException(status_code=404, detail="Placement plan not found")
+    placement.solver_status = solver_manager.get_solver_status(problem_id)
+    return plan_to_model(placement)
+
+
+app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/vm_placement/solver.py

@@ -0,0 +1,23 @@
+from solverforge_legacy.solver import SolverManager, SolutionManager
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import VM, VMPlacementPlan
+from .constraints import define_constraints
+
+
+solver_config = SolverConfig(
+    solution_class=VMPlacementPlan,
+    entity_class_list=[VM],
+    score_director_factory_config=ScoreDirectorFactoryConfig(
+        constraint_provider_function=define_constraints
+    ),
+    termination_config=TerminationConfig(spent_limit=Duration(seconds=30)),
+)
+
+solver_manager = SolverManager.create(solver_config)
+solution_manager = SolutionManager.create(solver_manager)

static/app.js

@@ -0,0 +1,974 @@
+// VM Placement Optimizer - Frontend Application with Real-Time Animations
+
+let autoRefreshIntervalId = null;
+let demoDataId = null;
+let placementId = null;
+let loadedPlacement = null;
+
+// Animation state tracking
+let vmPositionCache = {}; // { vmId: serverId | null }
+let isFirstRender = true;
+let previousScore = null;
+let serverLookup = {}; // For quick server access during animations
+
+$(document).ready(function () {
+    let initialized = false;
+
+    function safeInitialize() {
+        if (!initialized) {
+            initialized = true;
+            initializeApp();
+        }
+    }
+
+    $(window).on('load', safeInitialize);
+    setTimeout(safeInitialize, 100);
+});
+
+function initializeApp() {
+    replaceQuickstartSolverForgeAutoHeaderFooter();
+
+    $("#solveButton").click(function () {
+        solve();
+    });
+    $("#stopSolvingButton").click(function () {
+        stopSolving();
+    });
+    $("#analyzeButton").click(function () {
+        analyze();
+    });
+
+    // View toggle
+    $('input[name="viewToggle"]').change(function() {
+        if ($('#rackView').is(':checked')) {
+            $('#rackViewContainer').show();
+            $('#cardViewContainer').hide();
+        } else {
+            $('#rackViewContainer').hide();
+            $('#cardViewContainer').show();
+        }
+    });
+
+    setupAjax();
+    fetchDemoData();
+}
+
+function setupAjax() {
+    $.ajaxSetup({
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json,text/plain',
+        }
+    });
+    jQuery.each(["put", "delete"], function (i, method) {
+        jQuery[method] = function (url, data, callback, type) {
+            if (jQuery.isFunction(data)) {
+                type = type || callback;
+                callback = data;
+                data = undefined;
+            }
+            return jQuery.ajax({
+                url: url,
+                type: method,
+                dataType: type,
+                data: data,
+                success: callback
+            });
+        };
+    });
+}
+
+function fetchDemoData() {
+    $.get("/demo-data", function (data) {
+        data.forEach(item => {
+            $("#testDataButton").append($('<a id="' + item + 'TestData" class="dropdown-item" href="#">' + item + '</a>'));
+            $("#" + item + "TestData").click(function () {
+                switchDataDropDownItemActive(item);
+                placementId = null;
+                demoDataId = item;
+                // Reset animation state for new dataset
+                isFirstRender = true;
+                vmPositionCache = {};
+                previousScore = null;
+                refreshPlacement();
+            });
+        });
+        if (data.length > 0) {
+            demoDataId = data[0];
+            switchDataDropDownItemActive(demoDataId);
+            refreshPlacement();
+        }
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        let $demo = $("#demo");
+        $demo.empty();
+        $demo.html("<h1><p align=\"center\">No test data available</p></h1>");
+    });
+}
+
+function switchDataDropDownItemActive(newItem) {
+    const activeCssClass = "active";
+    $("#testDataButton > a." + activeCssClass).removeClass(activeCssClass);
+    $("#" + newItem + "TestData").addClass(activeCssClass);
+}
+
+function refreshPlacement() {
+    let path = "/placements/" + placementId;
+    if (placementId === null) {
+        if (demoDataId === null) {
+            showSimpleError("Please select a test data set.");
+            return;
+        }
+        path = "/demo-data/" + demoDataId;
+    }
+    $.getJSON(path, function (placement) {
+        loadedPlacement = placement;
+        renderPlacement(placement);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Getting the placement has failed.", xhr);
+        refreshSolvingButtons(false);
+    });
+}
+
+function renderPlacement(placement) {
+    if (!placement) {
+        console.error('No placement data provided');
+        return;
+    }
+
+    const isSolving = placement.solverStatus != null && placement.solverStatus !== "NOT_SOLVING";
+    refreshSolvingButtons(isSolving);
+
+    // Update score with animation
+    const newScore = placement.score == null ? "?" : placement.score;
+    const scoreEl = $("#score");
+    if (previousScore !== newScore) {
+        scoreEl.text("Score: " + newScore);
+        if (previousScore !== null && newScore !== "?") {
+            scoreEl.addClass("updated");
+            setTimeout(() => scoreEl.removeClass("updated"), 300);
+        }
+        previousScore = newScore;
+    }
+
+    // Update summary cards with change detection
+    updateSummaryCard("#totalServers", placement.servers ? placement.servers.length : 0);
+    updateSummaryCard("#activeServers", placement.activeServers || 0);
+    updateSummaryCard("#totalVms", placement.vms ? placement.vms.length : 0);
+    updateSummaryCard("#unassignedVms", placement.unassignedVms || 0);
+    updateSummaryCard("#cpuUtil", Math.round((placement.totalCpuUtilization || 0) * 100) + "%");
+    updateSummaryCard("#memUtil", Math.round((placement.totalMemoryUtilization || 0) * 100) + "%");
+
+    // Update unassigned card styling
+    const unassignedCard = $("#unassignedCard");
+    const unassignedVms = placement.unassignedVms || 0;
+    unassignedCard.removeClass("warning danger");
+    if (unassignedVms > 0) {
+        unassignedCard.addClass(unassignedVms > 5 ? "danger" : "warning");
+    }
+
+    if (!placement.servers || !placement.vms) {
+        return;
+    }
+
+    // Create VM and server lookups
+    const vmById = {};
+    placement.vms.forEach(vm => vmById[vm.id] = vm);
+
+    serverLookup = {};
+    placement.servers.forEach(s => serverLookup[s.id] = s);
+
+    if (isFirstRender) {
+        // Full render on first load
+        renderRackView(placement, vmById);
+        renderCardView(placement, vmById);
+        renderUnassignedVMs(placement.vms);
+        vmPositionCache = buildPositionCache(placement);
+        isFirstRender = false;
+        return;
+    }
+
+    // Incremental animated update
+    const newPositions = buildPositionCache(placement);
+    const changes = diffPositions(vmPositionCache, newPositions);
+
+    if (changes.length > 0) {
+        console.log(`Detected ${changes.length} VM position changes:`, changes.slice(0, 5));
+        animateVmChanges(changes, placement, vmById);
+    }
+
+    // Always update utilization bars smoothly
+    updateUtilizationBars(placement);
+
+    // Update unassigned list
+    updateUnassignedList(placement.vms, vmById);
+
+    vmPositionCache = newPositions;
+}
+
+function updateSummaryCard(selector, newValue) {
+    const el = $(selector);
+    const oldValue = el.text();
+    if (oldValue !== String(newValue)) {
+        el.text(newValue);
+        el.addClass("changed");
+        setTimeout(() => el.removeClass("changed"), 300);
+    }
+}
+
+function buildPositionCache(placement) {
+    const cache = {};
+    placement.vms.forEach(vm => {
+        cache[vm.id] = vm.server || null;
+    });
+    // Debug: log sample of cache
+    const sample = Object.entries(cache).slice(0, 3);
+    console.log('Position cache sample:', sample);
+    return cache;
+}
+
+function diffPositions(oldCache, newCache) {
+    const changes = [];
+    for (const vmId in newCache) {
+        const oldServer = oldCache[vmId];
+        const newServer = newCache[vmId];
+        if (oldServer !== newServer) {
+            changes.push({ vmId, from: oldServer, to: newServer });
+        }
+    }
+    return changes;
+}
+
+function animateVmChanges(changes, placement, vmById) {
+    changes.forEach(({ vmId, from, to }) => {
+        const vm = vmById[vmId];
+        if (!vm) return;
+
+        // Get source and target elements
+        let sourceEl, targetEl;
+        let sourceChipEl = null; // The actual chip element to hide during animation
+
+        if (from) {
+            sourceEl = $(`#server-blade-${from} .vm-chips`);
+            sourceChipEl = $(`#server-blade-${from} #vm-chip-${vmId}`);
+            // Highlight sending server
+            $(`#server-blade-${from}`).addClass('sending');
+            setTimeout(() => $(`#server-blade-${from}`).removeClass('sending'), 200);
+        } else {
+            // VM is coming from unassigned list
+            sourceEl = $(`#unassigned-${vmId}`);
+            sourceChipEl = sourceEl;
+        }
+
+        if (to) {
+            targetEl = $(`#server-blade-${to} .vm-chips`);
+            // Highlight receiving server
+            $(`#server-blade-${to}`).addClass('receiving');
+            setTimeout(() => $(`#server-blade-${to}`).removeClass('receiving'), 300);
+        } else {
+            targetEl = $('#unassignedList');
+        }
+
+        // If elements not found, just update DOM directly
+        if (!sourceEl.length || !targetEl.length) {
+            console.log(`Animation fallback: sourceEl=${sourceEl.length}, targetEl=${targetEl.length} for VM ${vmId}`);
+            updateVmPosition(vmId, from, to, vm);
+            return;
+        }
+
+        // Create flying clone
+        const flyingChip = createVmChip(vm);
+        flyingChip.addClass('flying-vm');
+
+        // Get positions
+        const sourceRect = sourceEl[0].getBoundingClientRect();
+        const targetRect = targetEl[0].getBoundingClientRect();
+
+        // Position at source
+        flyingChip.css({
+            left: sourceRect.left + 'px',
+            top: sourceRect.top + 'px',
+            transform: 'translate(0, 0)'
+        });
+
+        $('body').append(flyingChip);
+
+        // Hide original element during animation
+        if (sourceChipEl && sourceChipEl.length) {
+            sourceChipEl.css('opacity', '0');
+        }
+
+        // Trigger fly animation (use double RAF for reliable animation start)
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                flyingChip.addClass('animate');
+                flyingChip.css({
+                    transform: `translate(${targetRect.left - sourceRect.left}px, ${targetRect.top - sourceRect.top}px)`
+                });
+            });
+        });
+
+        // Clean up and update DOM after animation
+        setTimeout(() => {
+            flyingChip.remove();
+            updateVmPosition(vmId, from, to, vm);
+        }, 220); // Slightly longer than animation duration to ensure completion
+    });
+}
+
+function updateVmPosition(vmId, from, to, vm) {
+    // Remove from source
+    if (from) {
+        $(`#server-blade-${from} #vm-chip-${vmId}`).remove();
+    } else {
+        $(`#unassigned-${vmId}`).remove();
+    }
+
+    // Add to target
+    if (to) {
+        let vmChipsContainer = $(`#server-blade-${to} .vm-chips`);
+        if (!vmChipsContainer.length) {
+            // Create vm-chips container if it doesn't exist
+            vmChipsContainer = $('<div class="vm-chips"></div>');
+            $(`#server-blade-${to}`).append(vmChipsContainer);
+        }
+        const newChip = createVmChip(vm);
+        newChip.attr('id', `vm-chip-${vm.id}`);
+        vmChipsContainer.append(newChip);
+
+        // Update server blade state (empty/not empty)
+        $(`#server-blade-${to}`).removeClass('empty');
+    }
+
+    // Update source server empty state
+    if (from) {
+        const sourceChips = $(`#server-blade-${from} .vm-chips`).children();
+        if (sourceChips.length === 0) {
+            $(`#server-blade-${from}`).addClass('empty');
+        }
+    }
+}
+
+function updateUtilizationBars(placement) {
+    placement.servers.forEach(server => {
+        const cpuBar = $(`#util-${server.id}-cpu`);
+        const memBar = $(`#util-${server.id}-mem`);
+        const stoBar = $(`#util-${server.id}-sto`);
+
+        const updates = [
+            { bar: cpuBar, util: server.cpuUtilization || 0 },
+            { bar: memBar, util: server.memoryUtilization || 0 },
+            { bar: stoBar, util: server.storageUtilization || 0 }
+        ];
+
+        updates.forEach(({ bar, util }) => {
+            if (bar.length) {
+                const newPct = Math.min(util * 100, 100);
+                const oldPct = parseFloat(bar[0].style.width) || 0;
+
+                bar.css('width', newPct + '%');
+                bar.removeClass('low medium high over').addClass(getUtilClass(util));
+
+                if (Math.abs(oldPct - newPct) > 1) {
+                    bar.addClass('changed');
+                    setTimeout(() => bar.removeClass('changed'), 300);
+                }
+            }
+        });
+
+        // Update server blade empty/overcommitted state
+        const blade = $(`#server-blade-${server.id}`);
+        const hasVms = server.vms && server.vms.length > 0;
+        const isOvercommitted = (server.cpuUtilization || 0) > 1 ||
+                                (server.memoryUtilization || 0) > 1 ||
+                                (server.storageUtilization || 0) > 1;
+
+        blade.toggleClass('empty', !hasVms);
+        blade.toggleClass('overcommitted', isOvercommitted);
+    });
+}
+
+function updateUnassignedList(vms, vmById) {
+    const container = $("#unassignedList");
+    const unassigned = vms.filter(vm => !vm.server);
+
+    if (unassigned.length === 0) {
+        if (!container.find('.all-assigned').length) {
+            container.empty();
+            container.append(`
+                <div class="all-assigned">
+                    <i class="fas fa-check-circle"></i>
+                    <strong>All VMs assigned!</strong>
+                </div>
+            `);
+        }
+        return;
+    }
+
+    // Remove "all assigned" message if present
+    container.find('.all-assigned').remove();
+
+    // Update existing or add new unassigned VMs
+    unassigned.sort((a, b) => (b.priority || 1) - (a.priority || 1));
+
+    unassigned.forEach(vm => {
+        if (!$(`#unassigned-${vm.id}`).length) {
+            const vmDiv = createUnassignedVmElement(vm);
+            container.append(vmDiv);
+        }
+    });
+}
+
+function createUnassignedVmElement(vm) {
+    return $(`
+        <div id="unassigned-${vm.id}" class="unassigned-vm">
+            <div class="name">
+                ${vm.name}
+                ${vm.affinityGroup ? `<span class="constraint-marker affinity">${vm.affinityGroup}</span>` : ''}
+                ${vm.antiAffinityGroup ? `<span class="constraint-marker anti-affinity">${vm.antiAffinityGroup}</span>` : ''}
+            </div>
+            <div class="details">
+                <i class="fas fa-microchip"></i> ${vm.cpuCores}c
+                <i class="fas fa-memory ms-2"></i> ${vm.memoryGb}GB
+                <i class="fas fa-hdd ms-2"></i> ${vm.storageGb}GB
+                <span class="ms-2 badge bg-${getPriorityBadgeClass(vm.priority)}">P${vm.priority || 1}</span>
+            </div>
+        </div>
+    `);
+}
+
+function renderRackView(placement, vmById) {
+    const container = $("#rackViewContainer");
+    container.empty();
+
+    // Group servers by rack
+    const rackGroups = {};
+    placement.servers.forEach(server => {
+        const rack = server.rack || "Unracked";
+        if (!rackGroups[rack]) {
+            rackGroups[rack] = [];
+        }
+        rackGroups[rack].push(server);
+    });
+
+    // Sort racks alphabetically
+    const sortedRacks = Object.keys(rackGroups).sort();
+
+    sortedRacks.forEach(rackName => {
+        const servers = rackGroups[rackName];
+        servers.sort((a, b) => a.name.localeCompare(b.name));
+
+        const rackDiv = $('<div class="rack"></div>');
+        const rackHeader = $(`
+            <div class="rack-header">
+                <i class="fas fa-server"></i>
+                <span>${rackName}</span>
+                <span class="ms-auto badge bg-secondary">${servers.length} servers</span>
+            </div>
+        `);
+        rackDiv.append(rackHeader);
+
+        servers.forEach(server => {
+            const blade = createServerBlade(server, vmById);
+            rackDiv.append(blade);
+        });
+
+        container.append(rackDiv);
+    });
+}
+
+function createServerBlade(server, vmById) {
+    const cpuUtil = server.cpuUtilization || 0;
+    const memUtil = server.memoryUtilization || 0;
+    const storageUtil = server.storageUtilization || 0;
+    const isEmpty = !server.vms || server.vms.length === 0;
+    const isOvercommitted = cpuUtil > 1 || memUtil > 1 || storageUtil > 1;
+
+    let bladeClass = "server-blade";
+    if (isEmpty) bladeClass += " empty";
+    if (isOvercommitted) bladeClass += " overcommitted";
+
+    const blade = $(`<div id="server-blade-${server.id}" class="${bladeClass}"></div>`);
+
+    // Header
+    const header = $(`
+        <div class="server-blade-header">
+            <span class="server-name">${server.name}</span>
+            <span class="server-specs">${server.cpuCores}c / ${server.memoryGb}GB / ${server.storageGb}GB</span>
+        </div>
+    `);
+    blade.append(header);
+
+    // Utilization bars with IDs for animation
+    const utilBars = $('<div class="utilization-mini"></div>');
+    utilBars.append(createMiniUtilBar(cpuUtil, "CPU", `util-${server.id}-cpu`));
+    utilBars.append(createMiniUtilBar(memUtil, "MEM", `util-${server.id}-mem`));
+    utilBars.append(createMiniUtilBar(storageUtil, "STO", `util-${server.id}-sto`));
+    blade.append(utilBars);
+
+    // VM chips with IDs for animation
+    const vmChips = $('<div class="vm-chips"></div>');
+    if (server.vms && server.vms.length > 0) {
+        server.vms.forEach(vmId => {
+            const vm = vmById[vmId];
+            if (vm) {
+                const chip = createVmChip(vm);
+                chip.attr('id', `vm-chip-${vm.id}`);
+                vmChips.append(chip);
+            }
+        });
+    }
+    blade.append(vmChips);
+
+    // Click handler for details - pass server ID to get fresh data
+    blade.click(function(e) {
+        if (!$(e.target).hasClass('vm-chip')) {
+            showServerDetails(server.id);
+        }
+    });
+
+    return blade;
+}
+
+function createMiniUtilBar(value, label, id) {
+    const percentage = Math.min(value * 100, 100);
+    const utilClass = getUtilClass(value);
+
+    return $(`
+        <div class="util-mini-bar" title="${label}: ${Math.round(value * 100)}%">
+            <div id="${id}" class="util-mini-fill ${utilClass}" style="width: ${percentage}%"></div>
+        </div>
+    `);
+}
+
+function createVmChip(vm) {
+    const priority = vm.priority || 1;
+    let chipClass = `vm-chip priority-${priority}`;
+    if (vm.affinityGroup) chipClass += " affinity";
+    if (vm.antiAffinityGroup) chipClass += " anti-affinity";
+
+    let tooltip = vm.name;
+    tooltip += `\nCPU: ${vm.cpuCores} cores`;
+    tooltip += `\nMemory: ${vm.memoryGb} GB`;
+    tooltip += `\nStorage: ${vm.storageGb} GB`;
+    tooltip += `\nPriority: ${priority}`;
+    if (vm.affinityGroup) tooltip += `\nAffinity: ${vm.affinityGroup}`;
+    if (vm.antiAffinityGroup) tooltip += `\nAnti-Affinity: ${vm.antiAffinityGroup}`;
+
+    return $(`<span class="${chipClass}" title="${tooltip}">${vm.name}</span>`);
+}
+
+function renderCardView(placement, vmById) {
+    const container = $("#cardViewContainer");
+    container.empty();
+
+    const sortedServers = [...placement.servers].sort((a, b) => {
+        const aVms = a.vms ? a.vms.length : 0;
+        const bVms = b.vms ? b.vms.length : 0;
+        if (bVms !== aVms) return bVms - aVms;
+        return a.name.localeCompare(b.name);
+    });
+
+    sortedServers.forEach(server => {
+        const card = createServerCard(server, vmById);
+        container.append(card);
+    });
+}
+
+function createServerCard(server, vmById) {
+    const cpuUtil = server.cpuUtilization || 0;
+    const memUtil = server.memoryUtilization || 0;
+    const storageUtil = server.storageUtilization || 0;
+    const isEmpty = !server.vms || server.vms.length === 0;
+
+    const cardWrapper = $('<div class="col-md-6 col-lg-4"></div>');
+    const card = $(`
+        <div class="card h-100 ${isEmpty ? 'opacity-50' : ''}">
+            <div class="card-header d-flex justify-content-between align-items-center">
+                <strong>${server.name}</strong>
+                ${server.rack ? `<span class="badge bg-secondary">${server.rack}</span>` : ''}
+            </div>
+            <div class="card-body">
+                <div class="mb-3">
+                    ${createUtilRow("CPU", cpuUtil, server.cpuCores + " cores")}
+                    ${createUtilRow("Memory", memUtil, server.memoryGb + " GB")}
+                    ${createUtilRow("Storage", storageUtil, server.storageGb + " GB")}
+                </div>
+                <div class="vm-chips">
+                    ${(server.vms || []).map(vmId => {
+                        const vm = vmById[vmId];
+                        if (vm) {
+                            const priority = vm.priority || 1;
+                            let chipClass = `vm-chip priority-${priority}`;
+                            if (vm.affinityGroup) chipClass += " affinity";
+                            if (vm.antiAffinityGroup) chipClass += " anti-affinity";
+                            return `<span class="${chipClass}" title="${vm.name}">${vm.name}</span>`;
+                        }
+                        return '';
+                    }).join('')}
+                </div>
+            </div>
+        </div>
+    `);
+    cardWrapper.append(card);
+    return cardWrapper;
+}
+
+function createUtilRow(label, value, capacity) {
+    const percentage = Math.min(value * 100, 100);
+    const displayPercentage = Math.round(value * 100);
+    const utilClass = getUtilClass(value);
+
+    const bgClass = {
+        'low': 'bg-success',
+        'medium': 'bg-warning',
+        'high': 'bg-danger',
+        'over': 'bg-danger'
+    }[utilClass];
+
+    return `
+        <div class="mb-2">
+            <div class="d-flex justify-content-between small">
+                <span>${label}</span>
+                <span class="text-muted">${capacity} (${displayPercentage}%)</span>
+            </div>
+            <div class="progress" style="height: 6px;">
+                <div class="progress-bar ${bgClass}" style="width: ${percentage}%"></div>
+            </div>
+        </div>
+    `;
+}
+
+function renderUnassignedVMs(vms) {
+    const container = $("#unassignedList");
+    container.empty();
+
+    const unassigned = vms.filter(vm => !vm.server);
+
+    if (unassigned.length === 0) {
+        container.append(`
+            <div class="all-assigned">
+                <i class="fas fa-check-circle"></i>
+                <strong>All VMs assigned!</strong>
+            </div>
+        `);
+        return;
+    }
+
+    unassigned.sort((a, b) => (b.priority || 1) - (a.priority || 1));
+
+    unassigned.forEach(vm => {
+        const vmDiv = createUnassignedVmElement(vm);
+        container.append(vmDiv);
+    });
+}
+
+function getPriorityBadgeClass(priority) {
+    switch(priority) {
+        case 5: return "danger";
+        case 4: return "primary";
+        case 3: return "success";
+        case 2: return "secondary";
+        default: return "light text-dark";
+    }
+}
+
+function showServerDetails(serverId) {
+    // Always get fresh data from loadedPlacement
+    if (!loadedPlacement || !loadedPlacement.servers) {
+        console.error('No placement data available');
+        return;
+    }
+
+    const server = loadedPlacement.servers.find(s => s.id === serverId);
+    if (!server) {
+        console.error('Server not found:', serverId);
+        return;
+    }
+
+    // Build VM lookup from current placement
+    const vmById = {};
+    if (loadedPlacement.vms) {
+        loadedPlacement.vms.forEach(vm => vmById[vm.id] = vm);
+    }
+
+    const modal = new bootstrap.Modal("#serverDetailModal");
+    const content = $("#serverDetailModalContent");
+    $("#serverDetailModalLabel").html(`<i class="fas fa-server me-2"></i>${server.name}`);
+
+    const cpuUtil = server.cpuUtilization || 0;
+    const memUtil = server.memoryUtilization || 0;
+    const storageUtil = server.storageUtilization || 0;
+
+    content.html(`
+        <div class="mb-3">
+            <h6>Specifications</h6>
+            <table class="table table-sm">
+                <tr><td>Rack</td><td>${server.rack || 'Unracked'}</td></tr>
+                <tr><td>CPU Cores</td><td>${server.cpuCores}</td></tr>
+                <tr><td>Memory</td><td>${server.memoryGb} GB</td></tr>
+                <tr><td>Storage</td><td>${server.storageGb} GB</td></tr>
+            </table>
+        </div>
+        <div class="mb-3">
+            <h6>Utilization</h6>
+            ${createUtilRow("CPU", cpuUtil, `${server.usedCpu || 0}/${server.cpuCores} cores`)}
+            ${createUtilRow("Memory", memUtil, `${server.usedMemory || 0}/${server.memoryGb} GB`)}
+            ${createUtilRow("Storage", storageUtil, `${server.usedStorage || 0}/${server.storageGb} GB`)}
+        </div>
+        <div>
+            <h6>Assigned VMs (${server.vms ? server.vms.length : 0})</h6>
+            ${server.vms && server.vms.length > 0 ? `
+                <table class="table table-sm">
+                    <thead>
+                        <tr>
+                            <th>Name</th>
+                            <th>CPU</th>
+                            <th>Memory</th>
+                            <th>Storage</th>
+                            <th>Priority</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        ${server.vms.map(vmId => {
+                            const vm = vmById[vmId];
+                            if (vm) {
+                                return `
+                                    <tr>
+                                        <td>${vm.name}</td>
+                                        <td>${vm.cpuCores}</td>
+                                        <td>${vm.memoryGb} GB</td>
+                                        <td>${vm.storageGb} GB</td>
+                                        <td><span class="badge bg-${getPriorityBadgeClass(vm.priority)}">P${vm.priority || 1}</span></td>
+                                    </tr>
+                                `;
+                            }
+                            return '';
+                        }).join('')}
+                    </tbody>
+                </table>
+            ` : '<p class="text-muted">No VMs assigned</p>'}
+        </div>
+    `);
+
+    modal.show();
+}
+
+function getUtilClass(value) {
+    if (value > 1) return 'over';
+    if (value > 0.8) return 'high';
+    if (value > 0.5) return 'medium';
+    return 'low';
+}
+
+function solve() {
+    if (!loadedPlacement) {
+        showSimpleError("No placement data loaded. Please wait for the data to load or refresh the page.");
+        return;
+    }
+
+    // Reset animation state for solving - capture current positions before solving modifies them
+    vmPositionCache = buildPositionCache(loadedPlacement);
+    console.log('Solve started. Initial position cache size:', Object.keys(vmPositionCache).length);
+
+    $.post("/placements", JSON.stringify(loadedPlacement), function (data) {
+        placementId = data;
+        refreshSolvingButtons(true);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Start solving failed.", xhr);
+        refreshSolvingButtons(false);
+    }, "text");
+}
+
+function stopSolving() {
+    $.delete(`/placements/${placementId}`, function () {
+        refreshSolvingButtons(false);
+        // Do a final full render to ensure accuracy
+        isFirstRender = true;
+        refreshPlacement();
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Stop solving failed.", xhr);
+    });
+}
+
+function analyze() {
+    const modal = new bootstrap.Modal("#scoreAnalysisModal");
+    modal.show();
+
+    const scoreAnalysisModalContent = $("#scoreAnalysisModalContent");
+    scoreAnalysisModalContent.empty();
+
+    if (!loadedPlacement || loadedPlacement.score == null) {
+        scoreAnalysisModalContent.text("No score to analyze yet, please first press the 'Solve' button.");
+        return;
+    }
+
+    $('#scoreAnalysisScoreLabel').text(`(${loadedPlacement.score})`);
+
+    $.put("/placements/analyze", JSON.stringify(loadedPlacement), function (scoreAnalysis) {
+        let constraints = scoreAnalysis.constraints;
+
+        constraints.sort((a, b) => {
+            let aComponents = getScoreComponents(a.score);
+            let bComponents = getScoreComponents(b.score);
+            if (aComponents.hard < 0 && bComponents.hard > 0) return -1;
+            if (aComponents.hard > 0 && bComponents.soft < 0) return 1;
+            if (Math.abs(aComponents.hard) > Math.abs(bComponents.hard)) {
+                return -1;
+            } else {
+                if (Math.abs(aComponents.soft) > Math.abs(bComponents.soft)) {
+                    return -1;
+                }
+                return Math.abs(bComponents.soft) - Math.abs(aComponents.soft);
+            }
+        });
+
+        constraints = constraints.map((e) => {
+            let components = getScoreComponents(e.weight);
+            e.type = components.hard !== 0 ? 'hard' : 'soft';
+            e.weight = components[e.type];
+            let scores = getScoreComponents(e.score);
+            e.implicitScore = scores.hard !== 0 ? scores.hard : scores.soft;
+            return e;
+        });
+
+        scoreAnalysisModalContent.empty();
+
+        const analysisTable = $(`<table class="table"/>`).css({textAlign: 'center'});
+        const analysisTHead = $(`<thead/>`).append($(`<tr/>`)
+            .append($(`<th></th>`))
+            .append($(`<th>Constraint</th>`).css({textAlign: 'left'}))
+            .append($(`<th>Type</th>`))
+            .append($(`<th># Matches</th>`))
+            .append($(`<th>Weight</th>`))
+            .append($(`<th>Score</th>`)));
+        analysisTable.append(analysisTHead);
+
+        const analysisTBody = $(`<tbody/>`);
+        $.each(constraints, (index, constraintAnalysis) => {
+            let icon = constraintAnalysis.type === "hard" && constraintAnalysis.implicitScore < 0
+                ? '<span class="fas fa-exclamation-triangle text-danger"></span>'
+                : '';
+            if (!icon) {
+                icon = constraintAnalysis.matches.length === 0
+                    ? '<span class="fas fa-check-circle text-success"></span>'
+                    : '';
+            }
+
+            let row = $(`<tr/>`);
+            row.append($(`<td/>`).html(icon))
+                .append($(`<td/>`).text(constraintAnalysis.name).css({textAlign: 'left'}))
+                .append($(`<td/>`).html(`<span class="badge bg-${constraintAnalysis.type === 'hard' ? 'danger' : 'warning'}">${constraintAnalysis.type}</span>`))
+                .append($(`<td/>`).html(`<b>${constraintAnalysis.matches.length}</b>`))
+                .append($(`<td/>`).text(constraintAnalysis.weight))
+                .append($(`<td/>`).text(constraintAnalysis.implicitScore));
+            analysisTBody.append(row);
+        });
+        analysisTable.append(analysisTBody);
+        scoreAnalysisModalContent.append(analysisTable);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Analyze failed.", xhr);
+    }, "text");
+}
+
+function getScoreComponents(score) {
+    let components = {hard: 0, soft: 0};
+    if (!score) return components;
+
+    $.each([...score.matchAll(/(-?\d*\.?\d+)(hard|soft)/g)], (i, parts) => {
+        components[parts[2]] = parseFloat(parts[1]);
+    });
+
+    return components;
+}
+
+function refreshSolvingButtons(solving) {
+    if (solving) {
+        $("#solveButton").hide();
+        $("#stopSolvingButton").show();
+        $("#solvingSpinner").addClass("active");
+        // Add solving pulse animation to summary card values
+        $(".summary-card .value").addClass("solving-pulse");
+        if (autoRefreshIntervalId == null) {
+            // 250ms polling for smooth real-time animations
+            autoRefreshIntervalId = setInterval(refreshPlacement, 250);
+        }
+    } else {
+        $("#solveButton").show();
+        $("#stopSolvingButton").hide();
+        $("#solvingSpinner").removeClass("active");
+        // Remove solving pulse animation
+        $(".summary-card .value").removeClass("solving-pulse");
+        if (autoRefreshIntervalId != null) {
+            clearInterval(autoRefreshIntervalId);
+            autoRefreshIntervalId = null;
+        }
+    }
+}
+
+function replaceQuickstartSolverForgeAutoHeaderFooter() {
+    const solverforgeHeader = $("header#solverforge-auto-header");
+    if (solverforgeHeader != null) {
+        solverforgeHeader.css("background-color", "#ffffff");
+        solverforgeHeader.append(
+            $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg shadow-sm mb-3" style="background-color: #ffffff;">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge logo" width="400">
+          </a>
+          <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>
+          <div class="collapse navbar-collapse" id="navbarNav">
+            <ul class="nav nav-pills">
+              <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>
+              <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>
+              <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>
+          <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"></div>
+              </div>
+          </div>
+        </nav>
+      </div>`));
+    }
+
+    const solverforgeFooter = $("footer#solverforge-auto-footer");
+    if (solverforgeFooter != null) {
+        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-legacy">Code</a></div>
+                   <div class="vr"></div>
+                   <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+                 </div>
+               </div>
+             </footer>`));
+    }
+}
+
+function copyTextToClipboard(elementId) {
+    const element = document.getElementById(elementId);
+    if (element) {
+        navigator.clipboard.writeText(element.textContent).then(() => {
+            // Optional: show feedback
+        }).catch(err => {
+            console.error('Failed to copy text: ', err);
+        });
+    }
+}

static/config.js

@@ -0,0 +1,163 @@
+/**
+ * VM Placement Configuration Module
+ *
+ * Provides configurable infrastructure and workload settings for the VM placement
+ * quickstart, including sliders for racks, servers, VMs, and solver time.
+ */
+
+// =============================================================================
+// Configuration State
+// =============================================================================
+
+let currentConfig = {
+    rackCount: 3,
+    serversPerRack: 4,
+    vmCount: 20,
+    solverTime: 30
+};
+
+// =============================================================================
+// Initialization
+// =============================================================================
+
+/**
+ * Initialize configuration UI and event handlers.
+ * Called automatically when the script loads.
+ */
+function initConfig() {
+    // Rack count slider
+    $("#rackCountSlider").on("input", function() {
+        currentConfig.rackCount = parseInt(this.value);
+        $("#rackCountValue").text(this.value);
+        updateConfigSummary();
+    });
+
+    // Servers per rack slider
+    $("#serversPerRackSlider").on("input", function() {
+        currentConfig.serversPerRack = parseInt(this.value);
+        $("#serversPerRackValue").text(this.value);
+        updateConfigSummary();
+    });
+
+    // VM count slider
+    $("#vmCountSlider").on("input", function() {
+        currentConfig.vmCount = parseInt(this.value);
+        $("#vmCountValue").text(this.value);
+        updateConfigSummary();
+    });
+
+    // Solver time slider
+    $("#solverTimeSlider").on("input", function() {
+        currentConfig.solverTime = parseInt(this.value);
+        $("#solverTimeValue").text(formatSolverTime(this.value));
+    });
+
+    // Generate button
+    $("#generateDataBtn").click(function() {
+        generateCustomData();
+    });
+
+    // Initialize summary
+    updateConfigSummary();
+}
+
+// =============================================================================
+// UI Updates
+// =============================================================================
+
+function updateConfigSummary() {
+    const totalServers = currentConfig.rackCount * currentConfig.serversPerRack;
+    $("#configSummary").text(
+        `${totalServers} servers across ${currentConfig.rackCount} rack${currentConfig.rackCount > 1 ? 's' : ''}, ` +
+        `${currentConfig.vmCount} VMs to place`
+    );
+}
+
+function formatSolverTime(seconds) {
+    if (seconds >= 60) {
+        const mins = Math.floor(seconds / 60);
+        const secs = seconds % 60;
+        return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+    }
+    return `${seconds}s`;
+}
+
+// =============================================================================
+// Data Generation
+// =============================================================================
+
+function generateCustomData() {
+    const btn = $("#generateDataBtn");
+    const originalHtml = btn.html();
+
+    // Show loading state
+    btn.prop("disabled", true);
+    btn.html('<i class="fas fa-spinner fa-spin me-1"></i> Generating...');
+
+    $.ajax({
+        url: "/demo-data/generate",
+        type: "POST",
+        data: JSON.stringify({
+            rack_count: currentConfig.rackCount,
+            servers_per_rack: currentConfig.serversPerRack,
+            vm_count: currentConfig.vmCount
+        }),
+        contentType: "application/json"
+    })
+    .done(function(placement) {
+        // Reset animation state for new data
+        isFirstRender = true;
+        vmPositionCache = {};
+        previousScore = null;
+        placementId = null;
+
+        // Store and render new data
+        loadedPlacement = placement;
+        renderPlacement(placement);
+
+        // Flash success
+        btn.html('<i class="fas fa-check me-1"></i> Generated!');
+        btn.removeClass("btn-primary").addClass("btn-success");
+
+        setTimeout(() => {
+            btn.html(originalHtml);
+            btn.removeClass("btn-success").addClass("btn-primary");
+            btn.prop("disabled", false);
+        }, 1500);
+    })
+    .fail(function(xhr) {
+        showError("Failed to generate custom data", xhr);
+        btn.html(originalHtml);
+        btn.prop("disabled", false);
+    });
+}
+
+// =============================================================================
+// Solver Time Integration
+// =============================================================================
+
+/**
+ * Get the current solver time setting.
+ * Can be used by app.js to configure solver termination.
+ */
+function getSolverTime() {
+    return currentConfig.solverTime;
+}
+
+/**
+ * Get the current configuration.
+ */
+function getCurrentConfig() {
+    return { ...currentConfig };
+}
+
+// Export for use in app.js
+window.currentConfig = currentConfig;
+window.getSolverTime = getSolverTime;
+window.getCurrentConfig = getCurrentConfig;
+window.initConfig = initConfig;
+
+// Initialize when DOM is ready
+$(document).ready(function() {
+    initConfig();
+});

static/index.html

@@ -0,0 +1,701 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <title>VM Placement - SolverForge for Python</title>
+    <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="/webjars/solverforge/css/solverforge-webui.css">
+    <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
+    <style>
+        /* Solving spinner */
+        #solvingSpinner {
+            display: none;
+            width: 1.25rem;
+            height: 1.25rem;
+            border: 2px solid #10b981;
+            border-top-color: transparent;
+            border-radius: 50%;
+            animation: spin 0.75s linear infinite;
+            vertical-align: middle;
+        }
+        #solvingSpinner.active {
+            display: inline-block;
+        }
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
+
+        /* Rack visualization */
+        .rack-container {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 1.5rem;
+            padding: 1rem;
+        }
+        .rack {
+            background: linear-gradient(180deg, #1a1a2e 0%, #16213e 100%);
+            border-radius: 8px;
+            padding: 1rem;
+            min-width: 280px;
+            flex: 1;
+            max-width: 400px;
+            box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+        }
+        .rack-header {
+            color: #10b981;
+            font-weight: bold;
+            font-size: 0.9rem;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+            margin-bottom: 0.75rem;
+            padding-bottom: 0.5rem;
+            border-bottom: 2px solid #10b981;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        .rack-header i {
+            font-size: 1rem;
+        }
+        .server-blade {
+            background: linear-gradient(90deg, #2d3748 0%, #1a202c 100%);
+            border: 1px solid #4a5568;
+            border-radius: 4px;
+            padding: 0.75rem;
+            margin-bottom: 0.5rem;
+            transition: all 0.3s ease;
+            cursor: pointer;
+        }
+        .server-blade:hover {
+            border-color: #10b981;
+            box-shadow: 0 0 10px rgba(16, 185, 129, 0.3);
+            transform: translateX(4px);
+        }
+        .server-blade.empty {
+            opacity: 0.5;
+        }
+        .server-blade.overcommitted {
+            border-color: #ef4444;
+            box-shadow: 0 0 8px rgba(239, 68, 68, 0.4);
+        }
+        .server-blade-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 0.5rem;
+        }
+        .server-name {
+            color: #e2e8f0;
+            font-weight: 600;
+            font-size: 0.85rem;
+        }
+        .server-specs {
+            color: #718096;
+            font-size: 0.7rem;
+        }
+        .utilization-mini {
+            display: flex;
+            gap: 0.25rem;
+            margin-bottom: 0.5rem;
+        }
+        .util-mini-bar {
+            flex: 1;
+            height: 6px;
+            background: #4a5568;
+            border-radius: 3px;
+            overflow: hidden;
+            position: relative;
+        }
+        .util-mini-fill {
+            height: 100%;
+            border-radius: 3px;
+            transition: width 0.5s ease, background 0.3s ease;
+        }
+        .util-mini-fill.low { background: linear-gradient(90deg, #10b981, #34d399); }
+        .util-mini-fill.medium { background: linear-gradient(90deg, #f59e0b, #fbbf24); }
+        .util-mini-fill.high { background: linear-gradient(90deg, #ef4444, #f87171); }
+        .util-mini-fill.over { background: linear-gradient(90deg, #991b1b, #dc2626); }
+        .util-mini-label {
+            position: absolute;
+            right: 2px;
+            top: -1px;
+            font-size: 0.5rem;
+            color: #fff;
+            text-shadow: 0 0 2px rgba(0,0,0,0.8);
+        }
+        .vm-chips {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 4px;
+        }
+        .vm-chip {
+            font-size: 0.65rem;
+            padding: 2px 6px;
+            border-radius: 3px;
+            color: white;
+            font-weight: 500;
+            transition: transform 0.2s ease;
+            cursor: default;
+        }
+        .vm-chip:hover {
+            transform: scale(1.1);
+            z-index: 10;
+        }
+        .vm-chip.priority-5 { background: linear-gradient(135deg, #7c3aed, #a855f7); }
+        .vm-chip.priority-4 { background: linear-gradient(135deg, #2563eb, #3b82f6); }
+        .vm-chip.priority-3 { background: linear-gradient(135deg, #059669, #10b981); }
+        .vm-chip.priority-2 { background: linear-gradient(135deg, #4b5563, #6b7280); }
+        .vm-chip.priority-1 { background: linear-gradient(135deg, #9ca3af, #d1d5db); color: #1f2937; }
+        .vm-chip.affinity {
+            box-shadow: 0 0 0 2px #f59e0b;
+        }
+        .vm-chip.anti-affinity {
+            box-shadow: 0 0 0 2px #ef4444;
+        }
+
+        /* Summary cards */
+        .summary-card {
+            background: white;
+            border-radius: 12px;
+            padding: 1.25rem;
+            text-align: center;
+            box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+            transition: transform 0.2s ease, box-shadow 0.2s ease;
+        }
+        .summary-card:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+        }
+        .summary-card .value {
+            font-size: 2rem;
+            font-weight: 700;
+            color: #1f2937;
+            line-height: 1.2;
+        }
+        .summary-card .label {
+            font-size: 0.8rem;
+            color: #6b7280;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+        }
+        .summary-card.highlight .value {
+            color: #10b981;
+        }
+        .summary-card.warning .value {
+            color: #f59e0b;
+        }
+        .summary-card.danger .value {
+            color: #ef4444;
+        }
+
+        /* Unassigned VMs panel */
+        .unassigned-panel {
+            background: white;
+            border-radius: 12px;
+            padding: 1rem;
+            box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+            max-height: 400px;
+            overflow-y: auto;
+        }
+        .unassigned-vm {
+            background: linear-gradient(135deg, #fef3c7, #fde68a);
+            border-left: 4px solid #f59e0b;
+            padding: 0.75rem;
+            margin-bottom: 0.5rem;
+            border-radius: 0 8px 8px 0;
+            transition: transform 0.2s ease;
+        }
+        .unassigned-vm:hover {
+            transform: translateX(4px);
+        }
+        .unassigned-vm .name {
+            font-weight: 600;
+            color: #92400e;
+        }
+        .unassigned-vm .details {
+            font-size: 0.75rem;
+            color: #78716c;
+            margin-top: 0.25rem;
+        }
+        .all-assigned {
+            background: linear-gradient(135deg, #d1fae5, #a7f3d0);
+            border-left: 4px solid #10b981;
+            padding: 1rem;
+            border-radius: 0 8px 8px 0;
+            color: #065f46;
+            text-align: center;
+        }
+        .all-assigned i {
+            font-size: 1.5rem;
+            margin-bottom: 0.5rem;
+            display: block;
+        }
+
+        /* Legend */
+        .legend {
+            background: #f9fafb;
+            border-radius: 8px;
+            padding: 1rem;
+            margin-top: 1rem;
+        }
+        .legend h6 {
+            font-size: 0.8rem;
+            color: #6b7280;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            margin-bottom: 0.75rem;
+        }
+        .legend-item {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            font-size: 0.75rem;
+            margin-bottom: 0.25rem;
+        }
+        .legend-color {
+            width: 16px;
+            height: 16px;
+            border-radius: 4px;
+        }
+
+        /* Constraint markers */
+        .constraint-marker {
+            font-size: 0.6rem;
+            padding: 1px 4px;
+            border-radius: 2px;
+            margin-left: 4px;
+        }
+        .constraint-marker.affinity {
+            background: #fef3c7;
+            color: #92400e;
+        }
+        .constraint-marker.anti-affinity {
+            background: #fee2e2;
+            color: #991b1b;
+        }
+
+        /* View toggle */
+        .view-toggle {
+            margin-bottom: 1rem;
+        }
+        .view-toggle .btn-check:checked + .btn {
+            background-color: #10b981;
+            border-color: #10b981;
+        }
+
+        /* Responsive adjustments */
+        @media (max-width: 768px) {
+            .rack {
+                max-width: 100%;
+            }
+        }
+
+        /* Flying VM animation */
+        .flying-vm {
+            position: fixed;
+            z-index: 9999;
+            pointer-events: none;
+            transition: none;
+        }
+        .flying-vm.animate {
+            transition: transform 200ms ease-in-out, opacity 200ms ease;
+        }
+
+        /* Utilization bar pulse on change */
+        @keyframes utilPulse {
+            0%, 100% { box-shadow: none; }
+            50% { box-shadow: 0 0 8px 2px rgba(16, 185, 129, 0.6); }
+        }
+        .util-mini-fill.changed {
+            animation: utilPulse 300ms ease;
+        }
+
+        /* Server highlight when receiving VM */
+        @keyframes serverReceive {
+            0%, 100% { box-shadow: inset 0 0 0 0 rgba(16, 185, 129, 0); }
+            50% { box-shadow: inset 0 0 20px 5px rgba(16, 185, 129, 0.3); }
+        }
+        .server-blade.receiving {
+            animation: serverReceive 300ms ease;
+        }
+
+        /* Server highlight when losing VM */
+        @keyframes serverSend {
+            0%, 100% { box-shadow: inset 0 0 0 0 rgba(239, 68, 68, 0); }
+            50% { box-shadow: inset 0 0 15px 3px rgba(239, 68, 68, 0.2); }
+        }
+        .server-blade.sending {
+            animation: serverSend 200ms ease;
+        }
+
+        /* Score update flash */
+        @keyframes scoreFlash {
+            0%, 100% { background: transparent; }
+            50% { background: rgba(16, 185, 129, 0.2); }
+        }
+        .score.updated {
+            animation: scoreFlash 300ms ease;
+            border-radius: 4px;
+            padding: 2px 8px;
+        }
+
+        /* Summary card value change */
+        @keyframes valueChange {
+            0%, 100% { transform: scale(1); }
+            50% { transform: scale(1.1); }
+        }
+        .summary-card .value.changed {
+            animation: valueChange 300ms ease;
+        }
+
+        /* Progress animation during solving */
+        @keyframes pulse {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0.6; }
+        }
+        .solving-pulse {
+            animation: pulse 1.5s ease-in-out infinite;
+        }
+
+        /* Advanced settings panel */
+        .settings-card {
+            background: white;
+            border-radius: 12px;
+            box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+        }
+        .settings-card .card-body {
+            padding: 1.25rem;
+        }
+        .form-range::-webkit-slider-thumb {
+            background: #10b981;
+        }
+        .form-range::-moz-range-thumb {
+            background: #10b981;
+        }
+        .config-value {
+            font-weight: 600;
+            color: #10b981;
+        }
+        .preset-description {
+            font-size: 0.85rem;
+            color: #64748b;
+        }
+    </style>
+</head>
+<body>
+
+<header id="solverforge-auto-header">
+    <!-- Filled in by app.js -->
+</header>
+
+<div class="tab-content">
+    <div id="demo" class="tab-pane fade show active container-fluid">
+        <div class="sticky-top d-flex justify-content-center align-items-center" aria-live="polite" aria-atomic="true">
+            <div id="notificationPanel" style="position: absolute; top: .5rem;"></div>
+        </div>
+
+        <h1>VM Placement Optimizer</h1>
+        <p>Optimize virtual machine placement across servers to maximize resource utilization while respecting constraints.</p>
+
+        <div class="mb-4">
+            <button id="solveButton" type="button" class="btn btn-success">
+                <i class="fas fa-play"></i> Solve
+            </button>
+            <button id="stopSolvingButton" type="button" class="btn btn-danger" style="display: none;">
+                <i class="fas fa-stop"></i> Stop solving
+            </button>
+            <span id="solvingSpinner" class="ms-2"></span>
+            <span id="score" class="score ms-2 align-middle fw-bold">Score: ?</span>
+            <button id="analyzeButton" type="button" class="ms-2 btn btn-secondary">
+                <i class="fas fa-question"></i>
+            </button>
+
+            <div class="float-end">
+                <button class="btn btn-outline-secondary btn-sm me-2" type="button"
+                        data-bs-toggle="collapse" data-bs-target="#advancedSettings"
+                        aria-expanded="false" aria-controls="advancedSettings">
+                    <i class="fas fa-cog"></i> Advanced
+                </button>
+                <div class="btn-group view-toggle me-2" role="group" aria-label="View toggle">
+                    <input type="radio" class="btn-check" name="viewToggle" id="rackView" autocomplete="off" checked>
+                    <label class="btn btn-outline-secondary btn-sm" for="rackView">
+                        <i class="fas fa-server"></i> Rack View
+                    </label>
+                    <input type="radio" class="btn-check" name="viewToggle" id="cardView" autocomplete="off">
+                    <label class="btn btn-outline-secondary btn-sm" for="cardView">
+                        <i class="fas fa-th-large"></i> Card View
+                    </label>
+                </div>
+            </div>
+        </div>
+
+        <!-- Advanced Settings Panel -->
+        <div class="collapse mb-4" id="advancedSettings">
+            <div class="settings-card">
+                <div class="card-body">
+                    <div class="row g-4">
+                        <!-- Infrastructure Settings -->
+                        <div class="col-md-6">
+                            <h6 class="text-muted mb-3"><i class="fas fa-server me-2"></i>Infrastructure</h6>
+                            <div class="row g-3">
+                                <div class="col-6">
+                                    <label class="form-label">
+                                        Racks: <span id="rackCountValue" class="config-value">3</span>
+                                    </label>
+                                    <input type="range" class="form-range" id="rackCountSlider"
+                                           min="1" max="8" step="1" value="3">
+                                    <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                                        <span>1</span>
+                                        <span>8</span>
+                                    </div>
+                                </div>
+                                <div class="col-6">
+                                    <label class="form-label">
+                                        Servers/Rack: <span id="serversPerRackValue" class="config-value">4</span>
+                                    </label>
+                                    <input type="range" class="form-range" id="serversPerRackSlider"
+                                           min="2" max="10" step="1" value="4">
+                                    <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                                        <span>2</span>
+                                        <span>10</span>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Workload Settings -->
+                        <div class="col-md-6">
+                            <h6 class="text-muted mb-3"><i class="fas fa-cubes me-2"></i>Workload</h6>
+                            <div class="row g-3">
+                                <div class="col-6">
+                                    <label class="form-label">
+                                        VMs: <span id="vmCountValue" class="config-value">20</span>
+                                    </label>
+                                    <input type="range" class="form-range" id="vmCountSlider"
+                                           min="5" max="200" step="5" value="20">
+                                    <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                                        <span>5</span>
+                                        <span>200</span>
+                                    </div>
+                                </div>
+                                <div class="col-6">
+                                    <label class="form-label">
+                                        Solver Time: <span id="solverTimeValue" class="config-value">30s</span>
+                                    </label>
+                                    <input type="range" class="form-range" id="solverTimeSlider"
+                                           min="5" max="120" step="5" value="30">
+                                    <div class="d-flex justify-content-between text-muted" style="font-size: 0.7rem;">
+                                        <span>5s</span>
+                                        <span>2min</span>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Action buttons -->
+                    <div class="mt-3 d-flex justify-content-between align-items-center">
+                        <div class="preset-description">
+                            <i class="fas fa-info-circle me-1"></i>
+                            <span id="configSummary">12 servers across 3 racks, 20 VMs to place</span>
+                        </div>
+                        <button id="generateDataBtn" class="btn btn-primary btn-sm">
+                            <i class="fas fa-sync-alt me-1"></i> Generate New Data
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Summary Cards -->
+        <div class="row mb-4 g-3" id="summaryCards">
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card">
+                    <div class="value" id="totalServers">-</div>
+                    <div class="label">Total Servers</div>
+                </div>
+            </div>
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card highlight">
+                    <div class="value" id="activeServers">-</div>
+                    <div class="label">Active Servers</div>
+                </div>
+            </div>
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card">
+                    <div class="value" id="totalVms">-</div>
+                    <div class="label">Total VMs</div>
+                </div>
+            </div>
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card" id="unassignedCard">
+                    <div class="value" id="unassignedVms">-</div>
+                    <div class="label">Unassigned</div>
+                </div>
+            </div>
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card">
+                    <div class="value" id="cpuUtil">-</div>
+                    <div class="label">CPU Util</div>
+                </div>
+            </div>
+            <div class="col-6 col-md-4 col-lg-2">
+                <div class="summary-card">
+                    <div class="value" id="memUtil">-</div>
+                    <div class="label">Memory Util</div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Main Content -->
+        <div class="row">
+            <!-- Rack/Card View -->
+            <div class="col-lg-9">
+                <div id="rackViewContainer" class="rack-container">
+                    <p class="text-muted">Select a dataset to see server rack visualization</p>
+                </div>
+                <div id="cardViewContainer" class="row g-3" style="display: none;">
+                    <p class="text-muted">Select a dataset to see server cards</p>
+                </div>
+            </div>
+
+            <!-- Sidebar -->
+            <div class="col-lg-3">
+                <div class="unassigned-panel mb-3">
+                    <h5 class="mb-3"><i class="fas fa-exclamation-triangle text-warning me-2"></i>Unassigned VMs</h5>
+                    <div id="unassignedList">
+                        <p class="text-muted small">No data loaded</p>
+                    </div>
+                </div>
+
+                <div class="legend">
+                    <h6><i class="fas fa-palette me-1"></i>Priority Legend</h6>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: linear-gradient(135deg, #7c3aed, #a855f7);"></div>
+                        <span>Critical (5)</span>
+                    </div>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: linear-gradient(135deg, #2563eb, #3b82f6);"></div>
+                        <span>High (4)</span>
+                    </div>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: linear-gradient(135deg, #059669, #10b981);"></div>
+                        <span>Medium (3)</span>
+                    </div>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: linear-gradient(135deg, #4b5563, #6b7280);"></div>
+                        <span>Low (2)</span>
+                    </div>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: linear-gradient(135deg, #9ca3af, #d1d5db);"></div>
+                        <span>Lowest (1)</span>
+                    </div>
+                    <hr class="my-2">
+                    <h6><i class="fas fa-link me-1"></i>Constraints</h6>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: #fef3c7; box-shadow: 0 0 0 2px #f59e0b;"></div>
+                        <span>Affinity Group</span>
+                    </div>
+                    <div class="legend-item">
+                        <div class="legend-color" style="background: #fee2e2; box-shadow: 0 0 0 2px #ef4444;"></div>
+                        <span>Anti-Affinity Group</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <div id="rest" class="tab-pane fade container-fluid">
+        <h1>REST API Guide</h1>
+
+        <h2>VM Placement solver integration via cURL</h2>
+
+        <h3>1. Download demo data</h3>
+        <pre>
+            <button class="btn btn-outline-dark btn-sm float-end" onclick="copyTextToClipboard('curl1')">Copy</button>
+            <code id="curl1">curl -X GET -H 'Accept:application/json' http://localhost:8080/demo-data/SMALL -o sample.json</code>
+        </pre>
+
+        <h3>2. Post the sample data for solving</h3>
+        <p>The POST operation returns a <code>jobId</code> that should be used in subsequent commands.</p>
+        <pre>
+            <button class="btn btn-outline-dark btn-sm float-end" onclick="copyTextToClipboard('curl2')">Copy</button>
+            <code id="curl2">curl -X POST -H 'Content-Type:application/json' http://localhost:8080/placements -d@sample.json</code>
+        </pre>
+
+        <h3>3. Get the current status and score</h3>
+        <pre>
+            <button class="btn btn-outline-dark btn-sm float-end" onclick="copyTextToClipboard('curl3')">Copy</button>
+            <code id="curl3">curl -X GET -H 'Accept:application/json' http://localhost:8080/placements/{jobId}/status</code>
+        </pre>
+
+        <h3>4. Get the complete solution</h3>
+        <pre>
+            <button class="btn btn-outline-dark btn-sm float-end" onclick="copyTextToClipboard('curl4')">Copy</button>
+            <code id="curl4">curl -X GET -H 'Accept:application/json' http://localhost:8080/placements/{jobId}</code>
+        </pre>
+
+        <h3>5. Terminate solving early</h3>
+        <pre>
+            <button class="btn btn-outline-dark btn-sm float-end" onclick="copyTextToClipboard('curl5')">Copy</button>
+            <code id="curl5">curl -X DELETE -H 'Accept:application/json' http://localhost:8080/placements/{jobId}</code>
+        </pre>
+    </div>
+
+    <div id="openapi" class="tab-pane fade container-fluid">
+        <h1>REST API Reference</h1>
+        <div class="ratio ratio-1x1">
+            <iframe src="/q/swagger-ui" style="overflow:hidden;" scrolling="no"></iframe>
+        </div>
+    </div>
+</div>
+
+<!-- Score Analysis Modal -->
+<div class="modal fade" id="scoreAnalysisModal" tabindex="-1" aria-labelledby="scoreAnalysisModalLabel" aria-hidden="true">
+    <div class="modal-dialog modal-lg modal-dialog-scrollable">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title" id="scoreAnalysisModalLabel">Score Analysis <span id="scoreAnalysisScoreLabel"></span></h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body" id="scoreAnalysisModalContent">
+                <!-- Filled in by app.js -->
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!-- Server Detail Modal -->
+<div class="modal fade" id="serverDetailModal" tabindex="-1" aria-labelledby="serverDetailModalLabel" aria-hidden="true">
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title" id="serverDetailModalLabel"><i class="fas fa-server me-2"></i>Server Details</h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body" id="serverDetailModalContent">
+                <!-- Filled in by app.js -->
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<footer id="solverforge-auto-footer"></footer>
+
+<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="/webjars/solverforge/js/solverforge-webui.js"></script>
+<script src="/app.js"></script>
+<script src="/config.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,68 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-green-1-rgb: #10b981;
+    --ts-green-2-rgb: #059669;
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --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);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.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);
+}
+.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-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);
+}
+.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,142 @@
+function replaceSolverForgeAutoHeaderFooter() {
+  const solverforgeHeader = $("header#solverforge-auto-header");
+  if (solverforgeHeader != null) {
+    solverforgeHeader.addClass("bg-black")
+    solverforgeHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/solverforge/img/solverforge-horizontal-white.svg" alt="SolverForge logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const solverforgeFooter = $("footer#solverforge-auto-footer");
+  if (solverforgeFooter != null) {
+    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-legacy">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+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');
+}
+
+function showError(title, xhr) {
+  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;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  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
+// ****************************************************************************
+
+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");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+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 {
+    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);
+}
+
+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;
+}

tests/test_constraints.py

@@ -0,0 +1,347 @@
+from solverforge_legacy.solver.test import ConstraintVerifier
+
+from vm_placement.domain import Server, VM, VMPlacementPlan
+from vm_placement.constraints import (
+    define_constraints,
+    cpu_capacity,
+    memory_capacity,
+    storage_capacity,
+    anti_affinity,
+    affinity,
+    minimize_servers_used,
+    balance_utilization,
+    prioritize_placement,
+)
+
+# VM is the only planning entity (Server is a problem fact)
+constraint_verifier = ConstraintVerifier.build(
+    define_constraints, VMPlacementPlan, VM
+)
+
+
+def assign(server: Server, *vms: VM):
+    """Helper to assign VMs to a server."""
+    for vm in vms:
+        vm.server = server
+
+
+##############################################
+# CPU Capacity Tests
+##############################################
+
+
+def test_cpu_capacity_not_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=8, storage_gb=50)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=8, memory_gb=16, storage_gb=100)
+    assign(server, vm1, vm2)
+
+    (
+        constraint_verifier.verify_that(cpu_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+def test_cpu_capacity_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=12, memory_gb=8, storage_gb=50)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=8, memory_gb=16, storage_gb=100)
+    assign(server, vm1, vm2)
+
+    # 12 + 8 = 20 cores, capacity = 16, excess = 4
+    (
+        constraint_verifier.verify_that(cpu_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(4)
+    )
+
+
+##############################################
+# Memory Capacity Tests
+##############################################
+
+
+def test_memory_capacity_not_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=32, storage_gb=50)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=4, memory_gb=16, storage_gb=100)
+    assign(server, vm1, vm2)
+
+    (
+        constraint_verifier.verify_that(memory_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+def test_memory_capacity_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=48, storage_gb=50)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=4, memory_gb=32, storage_gb=100)
+    assign(server, vm1, vm2)
+
+    # 48 + 32 = 80 GB, capacity = 64, excess = 16
+    (
+        constraint_verifier.verify_that(memory_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(16)
+    )
+
+
+##############################################
+# Storage Capacity Tests
+##############################################
+
+
+def test_storage_capacity_not_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=8, storage_gb=200)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=4, memory_gb=16, storage_gb=250)
+    assign(server, vm1, vm2)
+
+    (
+        constraint_verifier.verify_that(storage_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+def test_storage_capacity_exceeded():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=8, storage_gb=300)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=4, memory_gb=16, storage_gb=300)
+    assign(server, vm1, vm2)
+
+    # 300 + 300 = 600 GB, capacity = 500, excess = 100
+    (
+        constraint_verifier.verify_that(storage_capacity)
+        .given(server, vm1, vm2)
+        .penalizes_by(100)
+    )
+
+
+##############################################
+# Anti-Affinity Tests
+##############################################
+
+
+def test_anti_affinity_satisfied():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(
+        id="vm1", name="DB-Primary", cpu_cores=4, memory_gb=8, storage_gb=50,
+        anti_affinity_group="db-replicas"
+    )
+    vm2 = VM(
+        id="vm2", name="DB-Replica", cpu_cores=4, memory_gb=8, storage_gb=50,
+        anti_affinity_group="db-replicas"
+    )
+    assign(server1, vm1)
+    assign(server2, vm2)
+
+    (
+        constraint_verifier.verify_that(anti_affinity)
+        .given(server1, server2, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+def test_anti_affinity_violated():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(
+        id="vm1", name="DB-Primary", cpu_cores=4, memory_gb=8, storage_gb=50,
+        anti_affinity_group="db-replicas"
+    )
+    vm2 = VM(
+        id="vm2", name="DB-Replica", cpu_cores=4, memory_gb=8, storage_gb=50,
+        anti_affinity_group="db-replicas"
+    )
+    assign(server, vm1, vm2)
+
+    # Both VMs on same server with same anti-affinity group = 1 violation
+    (
+        constraint_verifier.verify_that(anti_affinity)
+        .given(server, vm1, vm2)
+        .penalizes_by(1)
+    )
+
+
+def test_anti_affinity_no_group():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=8, storage_gb=50)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=4, memory_gb=8, storage_gb=50)
+    assign(server, vm1, vm2)
+
+    # No anti-affinity group, so no penalty
+    (
+        constraint_verifier.verify_that(anti_affinity)
+        .given(server, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+##############################################
+# Affinity Tests
+##############################################
+
+
+def test_affinity_satisfied():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(
+        id="vm1", name="WebApp1", cpu_cores=2, memory_gb=4, storage_gb=20,
+        affinity_group="web-tier"
+    )
+    vm2 = VM(
+        id="vm2", name="WebApp2", cpu_cores=2, memory_gb=4, storage_gb=20,
+        affinity_group="web-tier"
+    )
+    assign(server, vm1, vm2)
+
+    (
+        constraint_verifier.verify_that(affinity)
+        .given(server, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+def test_affinity_violated():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(
+        id="vm1", name="WebApp1", cpu_cores=2, memory_gb=4, storage_gb=20,
+        affinity_group="web-tier"
+    )
+    vm2 = VM(
+        id="vm2", name="WebApp2", cpu_cores=2, memory_gb=4, storage_gb=20,
+        affinity_group="web-tier"
+    )
+    assign(server1, vm1)
+    assign(server2, vm2)
+
+    # VMs on different servers with same affinity group = penalty of 100
+    (
+        constraint_verifier.verify_that(affinity)
+        .given(server1, server2, vm1, vm2)
+        .penalizes_by(100)
+    )
+
+
+def test_affinity_no_group():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=2, memory_gb=4, storage_gb=20)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=2, memory_gb=4, storage_gb=20)
+    assign(server1, vm1)
+    assign(server2, vm2)
+
+    # No affinity group, so no penalty
+    (
+        constraint_verifier.verify_that(affinity)
+        .given(server1, server2, vm1, vm2)
+        .penalizes_by(0)
+    )
+
+
+##############################################
+# Minimize Servers Used Tests
+##############################################
+
+
+def test_minimize_servers_no_active():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+
+    (
+        constraint_verifier.verify_that(minimize_servers_used)
+        .given(server1, server2)
+        .penalizes_by(0)
+    )
+
+
+def test_minimize_servers_one_active():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=2, memory_gb=4, storage_gb=20)
+    assign(server1, vm1)
+
+    # 1 active server = 100 penalty
+    (
+        constraint_verifier.verify_that(minimize_servers_used)
+        .given(server1, server2, vm1)
+        .penalizes_by(100)
+    )
+
+
+def test_minimize_servers_two_active():
+    server1 = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    server2 = Server(id="s2", name="Server2", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=2, memory_gb=4, storage_gb=20)
+    vm2 = VM(id="vm2", name="VM2", cpu_cores=2, memory_gb=4, storage_gb=20)
+    assign(server1, vm1)
+    assign(server2, vm2)
+
+    # 2 active servers = 200 penalty
+    (
+        constraint_verifier.verify_that(minimize_servers_used)
+        .given(server1, server2, vm1, vm2)
+        .penalizes_by(200)
+    )
+
+
+##############################################
+# Balance Utilization Tests
+##############################################
+
+
+def test_balance_utilization_empty():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+
+    (
+        constraint_verifier.verify_that(balance_utilization)
+        .given(server)
+        .penalizes_by(0)
+    )
+
+
+def test_balance_utilization_50_percent():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=8, memory_gb=32, storage_gb=250)
+    assign(server, vm1)
+
+    # 50% utilization = 0.5, squared = 0.25, * 10 = 2.5, int = 2
+    (
+        constraint_verifier.verify_that(balance_utilization)
+        .given(server, vm1)
+        .penalizes_by(2)
+    )
+
+
+def test_balance_utilization_100_percent():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    assign(server, vm1)
+
+    # 100% utilization = 1.0, squared = 1.0, * 10 = 10
+    (
+        constraint_verifier.verify_that(balance_utilization)
+        .given(server, vm1)
+        .penalizes_by(10)
+    )
+
+
+##############################################
+# Prioritize Placement Tests
+##############################################
+
+
+def test_prioritize_placement_assigned():
+    server = Server(id="s1", name="Server1", cpu_cores=16, memory_gb=64, storage_gb=500)
+    vm1 = VM(id="vm1", name="VM1", cpu_cores=4, memory_gb=8, storage_gb=50, priority=5)
+    assign(server, vm1)
+
+    (
+        constraint_verifier.verify_that(prioritize_placement)
+        .given(server, vm1)
+        .penalizes_by(0)
+    )