Add admin sample data loading for testing (Runn-style explore)

- seed_demo service wipes portal data (keeps users) and loads a curated IT dataset
- Admin API: GET /admin/seed-demo/status, POST /admin/seed-demo?replace=true
- Insights empty state and Manage → Users panel with Load/Reload sample data
- ENABLE_DEMO_DATA env guard; SPEC.md updated

Co-authored-by: Cursor <cursoragent@cursor.com>

SPEC.md

@@ -129,6 +129,20 @@ role; user management requires `admin`.
 | GET    | `/api/v1/reports/project-allocation?start&end`  | Allocations broken out by project                          |
 | GET    | `/api/v1/users`                                 | List portal users                                          |
 | POST   | `/api/v1/users`                                 | Create a user                                              |
+| GET    | `/api/v1/admin/seed-demo/status`                | Whether portal DB is empty (admin only)                    |
+| POST   | `/api/v1/admin/seed-demo?replace=true`          | Wipe portal data (except users) and load sample IT dataset |
+
+Set `ENABLE_DEMO_DATA=false` on the office Linux box to hide and disable these endpoints in production.
+
+### Sample / demo data (testing)
+
+Admin-only fictional dataset for exploring the portal (similar to Runn’s trial explore flow):
+
+- **9 people**, **5 projects**, roles, teams, tags, skills, allocations (including one overallocated person), leaves, and public holidays
+- **Insights** (empty portal): “Load sample data” button with confirmation
+- **Manage → Users**: “Load sample data” / “Reload sample data”
+- **Hugging Face Spaces**: database is ephemeral — reload sample data after each deploy
+- **Office Podman** (`portal-data` volume): data persists; reload only when you choose to reset demo data
 
 ---
 
@@ -169,8 +183,8 @@ podman run -d --replace -p 8080:80 -v portal-data:/data --name portal \
 ```
 
 Open `http://localhost:8080` and sign in with the admin credentials. The portal
-starts empty — add your IT team from the **People** page and create projects
-from the **Projects** page to begin scheduling.
+starts empty — use **Insights → Load sample data** (admin) or add data manually
+from **Manage → People** and **Manage → Projects**.
 
 ---
 

backend/main.py

@@ -7,7 +7,7 @@ from sqlalchemy.orm import Session
 
 from auth import ensure_default_admin, get_current_user
 from database import get_db, run_migrations
-from routers import allocations, leaves, people, projects, reports, taxonomy, users
+from routers import admin, allocations, leaves, people, projects, reports, taxonomy, users
 
 
 @asynccontextmanager
@@ -63,3 +63,4 @@ app.include_router(leaves.router)
 app.include_router(reports.router)
 app.include_router(taxonomy.router)
 app.include_router(users.router)
+app.include_router(admin.router)

backend/routers/admin.py

@@ -0,0 +1,51 @@
+import os
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from auth import require_admin
+from database import get_db
+from models import Person, Project
+from services.seed_demo import clear_portal_data, portal_has_data, seed_demo_data
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+def _demo_enabled() -> bool:
+    return os.getenv("ENABLE_DEMO_DATA", "true").lower() in {"1", "true", "yes"}
+
+
+def _require_demo_enabled() -> None:
+    if not _demo_enabled():
+        raise HTTPException(status_code=404, detail="Demo data endpoints are disabled")
+
+
+@router.get("/seed-demo/status", dependencies=[Depends(require_admin)])
+def demo_data_status(db: Session = Depends(get_db)) -> dict:
+    _require_demo_enabled()
+    people_count = db.scalar(select(func.count(Person.id))) or 0
+    projects_count = db.scalar(select(func.count(Project.id))) or 0
+    return {
+        "is_empty": people_count == 0 and projects_count == 0,
+        "people_count": int(people_count),
+        "projects_count": int(projects_count),
+    }
+
+
+@router.post("/seed-demo", dependencies=[Depends(require_admin)])
+def seed_demo(
+    replace: bool = Query(False, description="Wipe portal data (except users) before seeding"),
+    db: Session = Depends(get_db),
+) -> dict:
+    _require_demo_enabled()
+
+    if portal_has_data(db) and not replace:
+        raise HTTPException(
+            status_code=409,
+            detail="Portal already has data. Confirm replace=true to wipe and load sample data.",
+        )
+
+    clear_portal_data(db)
+    counts = seed_demo_data(db)
+    return {"replaced": True, "counts": counts}

backend/services/seed_demo.py

@@ -0,0 +1,303 @@
+"""Demo / sample dataset for portal testing (admin-triggered only)."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.orm import Session
+
+from models import (
+    Allocation,
+    Leave,
+    Milestone,
+    Person,
+    PersonSkill,
+    Project,
+    Role,
+    Skill,
+    Tag,
+    Team,
+    person_tags,
+    project_tags,
+)
+
+AVATAR_COLORS = [
+    "#7c3aed",
+    "#6366f1",
+    "#0ea5e9",
+    "#16a34a",
+    "#f97316",
+    "#a855f7",
+    "#facc15",
+    "#ef4444",
+]
+
+
+def portal_has_data(db: Session) -> bool:
+    people = db.scalar(select(func.count(Person.id))) or 0
+    projects = db.scalar(select(func.count(Project.id))) or 0
+    return people > 0 or projects > 0
+
+
+def clear_portal_data(db: Session) -> None:
+    db.execute(delete(Allocation))
+    db.execute(delete(Leave))
+    db.execute(delete(Milestone))
+    db.execute(delete(PersonSkill))
+    db.execute(delete(person_tags))
+    db.execute(delete(project_tags))
+    db.execute(delete(Person))
+    db.execute(delete(Project))
+    db.execute(delete(Skill))
+    db.execute(delete(Tag))
+    db.execute(delete(Team))
+    db.execute(delete(Role))
+    db.flush()
+
+
+def seed_demo_data(db: Session) -> dict[str, int]:
+    today = date.today()
+    month_start = today.replace(day=1)
+    quarter_end = month_start + timedelta(days=90)
+
+    roles = {
+        name: Role(name=name)
+        for name in ("Developer", "DevOps Engineer", "Project Manager")
+    }
+    db.add_all(roles.values())
+    db.flush()
+
+    teams = {
+        name: Team(name=name)
+        for name in ("SOM Dev", "RMS Dev", "Platform", "Helpdesk")
+    }
+    db.add_all(teams.values())
+    db.flush()
+
+    tags = {
+        "remote": Tag(name="remote", color="#0ea5e9"),
+        "on-call": Tag(name="on-call", color="#f97316"),
+        "priority": Tag(name="priority", color="#dc2626"),
+    }
+    db.add_all(tags.values())
+    db.flush()
+
+    skills = {}
+    for name, category in (
+        ("ADF", "Data"),
+        ("Kubernetes", "Infrastructure"),
+        ("React", "Frontend"),
+        ("FastAPI", "Backend"),
+        ("SAP", "ERP"),
+        ("Networking", "Infrastructure"),
+        ("Project Management", "Soft skills"),
+    ):
+        skills[name] = Skill(name=name, category=category)
+    db.add_all(skills.values())
+    db.flush()
+
+    people_specs = [
+        ("Alex Morgan", "alex.morgan@example.com", "Developer", "SOM Dev", ["remote"], ["ADF", "React"], 40),
+        ("Jordan Lee", "jordan.lee@example.com", "Developer", "SOM Dev", ["priority"], ["Kubernetes", "FastAPI"], 40),
+        ("Sam Taylor", "sam.taylor@example.com", "DevOps Engineer", "Platform", ["on-call"], ["Kubernetes", "Networking"], 40),
+        ("Riley Chen", "riley.chen@example.com", "Developer", "RMS Dev", [], ["React", "FastAPI"], 40),
+        ("Morgan Patel", "morgan.patel@example.com", "Developer", "RMS Dev", ["remote"], ["SAP", "ADF"], 40),
+        ("Casey Brooks", "casey.brooks@example.com", "Project Manager", "Helpdesk", [], ["Project Management"], 40),
+        ("Jamie Ortiz", "jamie.ortiz@example.com", "DevOps Engineer", "Platform", ["on-call", "priority"], ["Networking", "Kubernetes"], 40),
+        ("Taylor Kim", "taylor.kim@example.com", "Developer", "RMS Dev", ["remote"], ["React", "ADF"], 40),
+        # Intentionally overallocated in demo allocations below
+        ("Priya Nair", "priya.nair@example.com", "Developer", "SOM Dev", ["priority"], ["FastAPI", "React"], 40),
+    ]
+
+    people: list[Person] = []
+    for index, (name, email, role_name, team_name, tag_names, skill_names, capacity) in enumerate(
+        people_specs
+    ):
+        person = Person(
+            name=name,
+            email=email,
+            role_id=roles[role_name].id,
+            team_id=teams[team_name].id,
+            weekly_capacity_hrs=capacity,
+            start_date=month_start - timedelta(days=60),
+            avatar_color=AVATAR_COLORS[index % len(AVATAR_COLORS)],
+        )
+        person.tags = [tags[t] for t in tag_names]
+        db.add(person)
+        people.append(person)
+
+    db.flush()
+
+    for person, (_, _, _, _, _, skill_names, _) in zip(people, people_specs):
+        for skill_name in skill_names:
+            db.add(
+                PersonSkill(
+                    person_id=person.id,
+                    skill_id=skills[skill_name].id,
+                    proficiency="intermediate",
+                )
+            )
+
+    project_specs = [
+        (
+            "Core Platform Upgrade",
+            "infrastructure",
+            "active",
+            "#0ea5e9",
+            ["priority"],
+            "Platform hardening and observability rollout.",
+            0,
+        ),
+        (
+            "Internal Portal v2",
+            "development",
+            "active",
+            "#7c3aed",
+            ["remote"],
+            "Resource portal enhancements for IT planning.",
+            0,
+        ),
+        (
+            "ERP Integration",
+            "development",
+            "planning",
+            "#16a34a",
+            [],
+            "SAP connector and data sync initiative.",
+            4,
+        ),
+        (
+            "Helpdesk Automation",
+            "support",
+            "active",
+            "#f97316",
+            ["on-call"],
+            "Ticket routing and self-service improvements.",
+            5,
+        ),
+        (
+            "Network Refresh",
+            "infrastructure",
+            "on_hold",
+            "#0f766e",
+            ["priority"],
+            "Switching and Wi-Fi refresh for offices.",
+            2,
+        ),
+    ]
+
+    projects: list[Project] = []
+    for name, ptype, status, color, tag_names, description, owner_index in project_specs:
+        project = Project(
+            name=name,
+            description=description,
+            status=status,
+            type=ptype,
+            start_date=month_start,
+            end_date=quarter_end,
+            color=color,
+            owner_id=people[owner_index].id if owner_index < len(people) else None,
+        )
+        project.tags = [tags[t] for t in tag_names]
+        db.add(project)
+        projects.append(project)
+
+    db.flush()
+
+    milestone_specs = [
+        (0, "Discovery complete", 21, False),
+        (0, "Go-live", 75, False),
+        (1, "UI parity review", 28, True),
+        (1, "Beta release", 56, False),
+        (2, "Requirements signed off", 14, False),
+        (3, "Pilot launch", 42, False),
+        (4, "Vendor selection", 35, False),
+    ]
+    for project_index, mname, offset_days, completed in milestone_specs:
+        db.add(
+            Milestone(
+                project_id=projects[project_index].id,
+                name=mname,
+                due_date=month_start + timedelta(days=offset_days),
+                is_completed=completed,
+            )
+        )
+
+    allocation_specs = [
+        (people[0].id, projects[0].id, 50, 0, 56),
+        (people[1].id, projects[1].id, 60, 0, 70),
+        (people[2].id, projects[0].id, 40, 14, 42),
+        (people[3].id, projects[3].id, 70, 0, 84),
+        (people[4].id, projects[2].id, 30, 21, 49),
+        (people[5].id, projects[1].id, 25, 0, 28),
+        (people[6].id, projects[4].id, 55, 7, 63),
+        (people[7].id, projects[3].id, 45, 0, 56),
+        # Priya: overlapping high allocations for overallocated report
+        (people[8].id, projects[0].id, 80, 0, 56),
+        (people[8].id, projects[1].id, 70, 0, 56),
+        (people[8].id, projects[2].id, 50, 0, 56),
+    ]
+
+    for person_id, project_id, pct, start_offset, end_offset in allocation_specs:
+        db.add(
+            Allocation(
+                person_id=person_id,
+                project_id=project_id,
+                start_date=month_start + timedelta(days=start_offset),
+                end_date=month_start + timedelta(days=end_offset),
+                allocation_pct=pct,
+            )
+        )
+
+    leave_specs = [
+        (people[0].id, "annual", 10, 12, "Short break"),
+        (people[3].id, "sick", 5, 5, "Sick day"),
+        (people[5].id, "annual", 45, 49, "Planned leave"),
+    ]
+    for person_id, leave_type, start_off, end_off, note in leave_specs:
+        start = month_start + timedelta(days=start_off)
+        end = month_start + timedelta(days=end_off)
+        db.add(
+            Leave(
+                person_id=person_id,
+                leave_type=leave_type,
+                start_date=start,
+                end_date=end,
+                note=note,
+                approved=True,
+            )
+        )
+
+    holiday_specs = [
+        ("New Year", 1, 1),
+        ("Company Day", 45, 45),
+        ("Summer shutdown", 120, 121),
+    ]
+    for note, start_off, end_off in holiday_specs:
+        start = month_start + timedelta(days=start_off)
+        end = month_start + timedelta(days=end_off)
+        db.add(
+            Leave(
+                person_id=None,
+                leave_type="public_holiday",
+                start_date=start,
+                end_date=end,
+                note=note,
+                approved=True,
+            )
+        )
+
+    db.commit()
+
+    return {
+        "roles": len(roles),
+        "teams": len(teams),
+        "tags": len(tags),
+        "skills": len(skills),
+        "people": len(people),
+        "projects": len(projects),
+        "milestones": len(milestone_specs),
+        "allocations": len(allocation_specs),
+        "leaves": len(leave_specs) + len(holiday_specs),
+    }

frontend/src/api/admin.ts

@@ -0,0 +1,28 @@
+import { api } from "./client";
+
+export interface DemoDataStatus {
+  is_empty: boolean;
+  people_count: number;
+  projects_count: number;
+}
+
+export interface DemoSeedResult {
+  replaced: boolean;
+  counts: {
+    roles: number;
+    teams: number;
+    tags: number;
+    skills: number;
+    people: number;
+    projects: number;
+    milestones: number;
+    allocations: number;
+    leaves: number;
+  };
+}
+
+export const getDemoDataStatus = async () =>
+  (await api.get<DemoDataStatus>("/admin/seed-demo/status")).data;
+
+export const seedDemoData = async (replace: boolean) =>
+  (await api.post<DemoSeedResult>("/admin/seed-demo", null, { params: { replace } })).data;

frontend/src/hooks/useDemoData.ts

@@ -0,0 +1,44 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import { getDemoDataStatus, seedDemoData } from "../api/admin";
+import { toastFromError, useToast } from "../components/ui/Toast";
+
+export const DEMO_CONFIRM_MESSAGE =
+  "This will delete all people, projects, allocations, roles, teams, tags, skills, and holidays. Portal login users are kept. Continue?";
+
+export function useDemoDataStatus(enabled = true) {
+  return useQuery({
+    queryKey: ["demo-data-status"],
+    queryFn: getDemoDataStatus,
+    enabled,
+  });
+}
+
+export function useSeedDemoData() {
+  const queryClient = useQueryClient();
+  const { push } = useToast();
+
+  return useMutation({
+    mutationFn: (replace: boolean) => seedDemoData(replace),
+    onSuccess: (result) => {
+      const { counts } = result;
+      push(
+        `Sample data loaded: ${counts.people} people, ${counts.projects} projects`,
+        "success",
+      );
+      queryClient.invalidateQueries();
+    },
+    onError: (error) => push(toastFromError(error, "Could not load sample data"), "error"),
+  });
+}
+
+export function useLoadDemoData(options?: { onSuccess?: () => void }) {
+  const seedMutation = useSeedDemoData();
+
+  const load = (replace = true) => {
+    if (!window.confirm(DEMO_CONFIRM_MESSAGE)) return;
+    seedMutation.mutate(replace, { onSuccess: options?.onSuccess });
+  };
+
+  return { load, isPending: seedMutation.isPending };
+}

frontend/src/pages/Dashboard.tsx

@@ -1,12 +1,18 @@
 import { BarChart3 } from "lucide-react";
 import { Link } from "react-router-dom";
 
+import { useAuth } from "../auth";
 import { EmptyState } from "../components/ui/EmptyState";
+import { useLoadDemoData } from "../hooks/useDemoData";
 import { useDashboard } from "../hooks/usePortalData";
 import { ManagePageHeader } from "./manage/_shared";
 
 export function DashboardPage() {
+  const { user } = useAuth();
   const { data, isLoading, isError } = useDashboard();
+  const { load: loadDemoData, isPending: isSeeding } = useLoadDemoData();
+  const isAdmin = user?.role === "admin";
+  const isEmpty = !isLoading && data && data.active_people === 0 && data.active_projects === 0;
 
   return (
     <section>
@@ -93,13 +99,35 @@ export function DashboardPage() {
         </>
       )}
 
-      {!isLoading && data && data.active_people === 0 && data.active_projects === 0 ? (
-        <article className="panel banner">
-          <h3>Welcome — your portal is empty.</h3>
-          <p>
-            Add your IT team in <Link to="/manage/people">Manage → People</Link> and create your first
-            project in <Link to="/manage/projects"> Manage → Projects</Link> to start planning capacity.
-          </p>
+      {isEmpty ? (
+        <article className="panel banner demo-sample-banner">
+          {isAdmin ? (
+            <>
+              <h3>Explore the portal with sample data</h3>
+              <p>
+                Load a fictional IT team, projects, allocations, and holidays to try the planner,
+                schedule, and reports. Useful after a fresh deploy or on Hugging Face where the database
+                resets. Login users are not removed.
+              </p>
+              <button
+                className="primary-button"
+                disabled={isSeeding}
+                onClick={() => loadDemoData(true)}
+                type="button"
+              >
+                {isSeeding ? "Loading sample data…" : "Load sample data"}
+              </button>
+            </>
+          ) : (
+            <>
+              <h3>Welcome — your portal is empty.</h3>
+              <p>
+                Ask an admin to load sample data, or add your IT team in{" "}
+                <Link to="/manage/people">Manage → People</Link> and projects in{" "}
+                <Link to="/manage/projects">Manage → Projects</Link>.
+              </p>
+            </>
+          )}
         </article>
       ) : null}
     </section>

frontend/src/pages/manage/UsersSection.tsx

@@ -7,6 +7,7 @@ import { useAuth } from "../../auth";
 import { EmptyState } from "../../components/ui/EmptyState";
 import { Modal } from "../../components/ui/Modal";
 import { toastFromError, useToast } from "../../components/ui/Toast";
+import { useDemoDataStatus, useLoadDemoData } from "../../hooks/useDemoData";
 import { useUsers } from "../../hooks/usePortalData";
 import { ManagePageHeader, ManageToolbar } from "./_shared";
 
@@ -19,6 +20,8 @@ export function UsersSection() {
   const [creating, setCreating] = useState(false);
   const [form, setForm] = useState({ username: "", password: "", role: "viewer" });
   const isAdmin = user?.role === "admin";
+  const { data: demoStatus } = useDemoDataStatus(isAdmin);
+  const { load: loadDemoData, isPending: isSeeding } = useLoadDemoData();
 
   const createMutation = useMutation({
     mutationFn: createUser,
@@ -102,6 +105,27 @@ export function UsersSection() {
         )}
       </article>
 
+      <article className="panel demo-sample-panel">
+        <h3>Sample data for testing</h3>
+        <p className="muted-text">
+          Load a demo IT org (people, projects, roles, teams, tags, skills, allocations, holidays).
+          Portal login users are kept. On Hugging Face, use this after each deploy when the database is
+          empty.
+        </p>
+        <button
+          className="primary-button"
+          disabled={isSeeding}
+          onClick={() => loadDemoData(true)}
+          type="button"
+        >
+          {isSeeding
+            ? "Loading…"
+            : demoStatus?.is_empty
+              ? "Load sample data"
+              : "Reload sample data"}
+        </button>
+      </article>
+
       <Modal
         open={creating}
         onClose={() => setCreating(false)}

frontend/src/styles.css

@@ -2124,6 +2124,27 @@ th {
   width: auto;
 }
 
+.demo-sample-banner {
+  display: grid;
+  gap: 12px;
+}
+
+.demo-sample-banner .primary-button {
+  justify-self: start;
+  width: auto;
+}
+
+.demo-sample-panel {
+  display: grid;
+  gap: 10px;
+  margin-top: 16px;
+}
+
+.demo-sample-panel .primary-button {
+  justify-self: start;
+  width: auto;
+}
+
 /* Skills page — Runn-style SKILLS / PEOPLE tabs */
 .skills-subnav {
   background: white;