cameleer-server/docs/superpowers/specs/2026-04-23-checkpoints-table-redesign-design.md

Checkpoints table redesign + deployment audit gap closure

Date: 2026-04-23 Status: Spec — pending implementation Affects: App deployment page, deployments backend, audit log

Context

The Checkpoints disclosure on the unified app deployment page (ui/src/pages/AppsTab/AppDeploymentPage/Checkpoints.tsx) currently renders past deployments as a cramped row list — a Badge, a "12m ago" label, and a Restore button. It hides the operator information that matters most when reasoning about a checkpoint: who deployed it, the JAR filename (not just the version number), the deployment outcome, and access to the logs and config snapshot the deployment ran with.

Investigating this also surfaced a gap in the audit log: DeploymentController.deploy / stop / promote make zero auditService.log(...) calls. Container deployments — the most consequential operations the server performs — leave no audit trail today. Closing this gap is in scope because it's prerequisite to the "Deployed by" column.

Goals

1. Replace the cramped checkpoints list with a real table (DS DataTable) showing version, JAR filename, deployer, time, strategy, and outcome.
2. Capture and display "who deployed" — backend gains a created_by column on deployments, populated from SecurityContextHolder.
3. Audit deploy / stop / promote operations under a new AuditCategory.DEPLOYMENT value.
4. Provide an in-page detail view (side drawer) where the operator can review the deployment's logs and config snapshot before deciding to restore, with an optional diff against the current live config.
5. Cap the visible checkpoint list at the environment's JAR retention count, since older entries cannot be restored.

Out of scope

• Sortable column headers (default newest-first is enough)
• Deep-linking via ?checkpoint=<id> query param
• "Remember last drawer tab" preference
• Bulk actions on checkpoints
• Promoting SideDrawer into @cameleer/design-system (wait for a second consumer)

Backend changes

Audit category

Add DEPLOYMENT to cameleer-server-core/src/main/java/com/cameleer/server/core/admin/AuditCategory.java:

public enum AuditCategory {
    INFRA, AUTH, USER_MGMT, CONFIG, RBAC, AGENT,
    OUTBOUND_CONNECTION_CHANGE, OUTBOUND_HTTP_TRUST_CHANGE,
    ALERT_RULE_CHANGE, ALERT_SILENCE_CHANGE,
    DEPLOYMENT
}

The AuditCategory.valueOf(...) lookup in AuditLogController picks this up automatically. The Admin → Audit page filter dropdown gets one new option in ui/src/pages/Admin/AuditLogPage.tsx.

Audit calls in DeploymentController

Add AuditService injection and write audit rows on every successful and failed lifecycle operation. Action codes:

Method	Action	Target	Details
deploy	deploy_app	deployment.id().toString()	{ appSlug, envSlug, appVersionId, jarFilename, version }
stop	stop_deployment	deploymentId.toString()	{ appSlug, envSlug }
promote	promote_deployment	deploymentId.toString()	{ sourceEnv, targetEnv, appSlug, appVersionId }

Each try branch writes AuditResult.SUCCESS; catch (IllegalArgumentException) writes AuditResult.FAILURE with the exception message in details before returning the existing 404. Pattern matches OutboundConnectionAdminController.

Flyway migration V2__add_deployment_created_by.sql

ALTER TABLE deployments ADD COLUMN created_by TEXT REFERENCES users(user_id);
CREATE INDEX idx_deployments_created_by ON deployments (created_by);

Nullable — existing rows stay NULL (rendered as — in UI). New rows always populated. No backfill: pre-V2 history is unrecoverable, and the column starts paying off from the next deploy onward.

Service signature change

DeploymentService.createDeployment(appId, appVersionId, envId, createdBy) and promote(targetAppId, sourceVersionId, targetEnvId, createdBy) both gain a trailing String createdBy parameter. PostgresDeploymentRepository writes it to the new column.

DeploymentController resolves createdBy via the existing user-id convention: strip "user:" prefix from SecurityContextHolder.getContext().getAuthentication().getName(). Same helper pattern as AlertRuleController / OutboundConnectionAdminController.

DTO change

com.cameleer.server.core.runtime.Deployment record gains createdBy: String. UI Deployment interface in ui/src/api/queries/admin/apps.ts gains createdBy: string | null.

Log filter for the drawer

LogQueryController.GET /api/v1/environments/{envSlug}/logs accepts a new multi-value query param instanceIds (comma-split, OR-joined). Translates to WHERE instance_id IN (...) against the existing LowCardinality(String) index on logs.instance_id (already part of the ORDER BY key).

LogSearchRequest gains instanceIds: List<String> (null-normalized). Service layer adds the IN (...) clause when non-null and non-empty.

The drawer client computes the instance_id list from Deployment.replicaStates: for each replica, instance_id = "{envSlug}-{appSlug}-{replicaIndex}-{generation}" where generation is the first 8 chars of deployment.id. This is the documented format from .claude/rules/docker-orchestration.md — pure client-side derivation, no extra server endpoint.

Drawer infrastructure

The design system provides Modal but no drawer. Building a project-local component is preferred over submitting to DS first (single consumer; easier to iterate locally).

File: ui/src/components/SideDrawer.tsx + SideDrawer.module.css (~120 LOC total).

API:

<SideDrawer
  open={!!selectedCheckpoint}
  onClose={() => setSelectedCheckpoint(null)}
  title={`Deployment v${version} · ${jarFilename}`}
  size="lg"   // 'md'=560px, 'lg'=720px, 'xl'=900px
  footer={<Button onClick={handleRestore}>Restore this checkpoint</Button>}
>
  {/* scrollable body */}
</SideDrawer>

Behavior:

• React portal to document.body (mirrors DS Modal).
• Slides in from right via transform: translateX(100% → 0) over 240ms ease-out.
• Click-blocking transparent backdrop (no dim — the parent table stays readable). Clicking outside closes.
• ESC closes.
• Focus trap on open; focus restored to trigger on close.
• Sticky header (title + close ×) and optional sticky footer.
• Body uses overflow-y: auto.
• All colors via DS CSS variables (--bg, --border, --shadow-lg).

Unsaved-changes interaction: Opening the drawer is unrestricted. The drawer is read-only — only Restore mutates form state, and Restore already triggers the existing unsaved-changes guard via useUnsavedChangesBlocker.

Checkpoints table

File: ui/src/pages/AppsTab/AppDeploymentPage/CheckpointsTable.tsx — replaces Checkpoints.tsx.

Columns (left to right):

Column	Source	Notes
Version	versionMap.get(d.appVersionId).version	Badge "v6" with auto-color (matches existing pattern)
JAR	versionMap.get(d.appVersionId).jarFilename	Monospace; truncate with tooltip on overflow
Deployed by	d.createdBy	Bare username; OIDC users show oidc:<sub> truncated with tooltip; null shows — muted
Deployed	d.deployedAt	Relative ("12m ago") + ISO subline
Strategy	d.deploymentStrategy	Small pill: "blue/green" or "rolling"
Outcome	d.status	Tinted pill: STOPPED (slate), DEGRADED (amber)
(chevron)	—	Visual affordance for "row click opens drawer"

Interaction:

• Row click opens CheckpointDetailDrawer (no separate "View" button).
• No per-row Restore button — Restore lives inside the drawer to force review before action.
• Pruned-JAR rows (!versionMap.has(d.appVersionId)) render at 55% opacity with a strikethrough on the filename and an amber "archived — JAR pruned" hint. Row stays clickable; Restore inside the drawer is disabled with tooltip.
• Currently-running deployment is excluded (already represented by StatusCard above).

Empty state: When zero checkpoints, render a single full-width muted row: "No past deployments yet."

Pagination

Visible cap = Environment.jarRetentionCount rows (newest first). Anything older has likely been pruned and is not restorable, so it's hidden by default.

• total ≤ jarRetentionCount → render all, no expander.
• total > jarRetentionCount → render newest jarRetentionCount rows + an expander row: "Show older (N) — archived, postmortem only". Expanding renders the full list (older rows already styled as archived).
• jarRetentionCount === 0 (unlimited or unconfigured) → fall back to a default cap of 10.

jarRetentionCount comes from useEnvironments() (already in the env-store).

Drawer detail view

File: ui/src/pages/AppsTab/AppDeploymentPage/CheckpointDetailDrawer/index.tsx plus three panel files: LogsPanel.tsx, ConfigPanel.tsx, ComparePanel.tsx.

Header:

• Version badge + JAR filename + outcome pill.
• Meta line: "Deployed by {createdBy} · {relative} ({ISO}) · Strategy: {strategy} · {N} replicas · ran for {duration}".
• Close × top-right.

Tabs (DS Tabs):

• Logs — default on open
• Config — read-only render of the live config sub-tabs, with a view-mode toggle for "Snapshot" vs "Diff vs current"

Logs panel

Reuses useInfiniteApplicationLogs with the new instanceIds filter. The hook signature gets an optional instanceIds: string[] parameter that flows through to the LogQueryController query string.

Filters (in addition to instanceIds):

• Existing source/level multi-select pills
• New replica filter dropdown: "all (N)" / "0" / "1" / ... / "N-1" — narrows to a single replica when troubleshooting blue-green or rolling deploys.

Default sort: newest first (matches operator mental model when investigating a stopped deployment).

Total line count displayed in the filter bar.

Config panel

Renders the five existing live config sub-tabs (Monitoring, Resources, Variables, SensitiveKeys, Deployment) read-only, hydrated from deployedConfigSnapshot.

Each sub-tab component (ui/src/pages/AppsTab/AppDeploymentPage/ConfigTabs/*) gains an optional readOnly?: boolean prop. When readOnly is set:

• All inputs disabled (disabled attribute + visual styling)
• Save / edit buttons hidden
• Live banners (LiveBanner) hidden — these are not applicable to a frozen snapshot

If a sub-tab currently mixes derived state with form state in a way that makes a clean readOnly toggle awkward, refactor that sub-tab as part of this work. Don't proceed with leaky read-only behavior.

View-mode toggle: "Snapshot" / "Diff vs current". Default = Snapshot (full read-only render). Diff mode shows differences only — both old and new values per changed field, with red/green left borders, grouped by sub-tab. Each sub-tab pill shows a change-count badge (e.g. "Resources (2)"); sub-tabs with zero differences are dimmed and render a muted "No differences in this section" message when clicked.

Diff base = current live config, pulled via the existing useApplicationConfig hook the live form already uses. Algorithm: deep-equal field-level walk between snapshot and current.

The toggle is hidden entirely when JAR is pruned (the missing JAR makes "current vs snapshot" comparison incomplete and misleading).

Footer: Sticky. Single primary button "Restore this checkpoint" + helper text "Restoring hydrates the form — you'll still need to Redeploy."

When JAR is pruned: button disabled with tooltip "JAR was pruned by the environment retention policy".

Restore behavior is unchanged from today: closes the drawer + hydrates the form via the existing onRestore(deploymentId) callback. No backend call; the eventual Redeploy generates the next deploy_app audit row.

Authorization

DeploymentController and AppController are already class-level @PreAuthorize("hasAnyRole('OPERATOR', 'ADMIN')"), so the deployment page is operator-gated. The new instanceIds filter on LogQueryController (which is VIEWER+) widens nothing — viewers can already query the same logs by application + environment; the filter just narrows.

Real-time updates

When a new deployment lands, the previous "current" becomes a checkpoint. TanStack Query already polls deployments via the existing useDeployments(appSlug, envSlug) hook; the new table consumes the same data — auto-refresh comes for free.

Tests

Backend integration tests:

Test	What it asserts
V2MigrationIT	created_by column exists, FK valid, index exists
DeploymentServiceCreatedByIT	createDeployment(...createdBy) persists the value
DeploymentControllerAuditIT	All three lifecycle actions write the expected audit row (action, category, target, details, actor, result) including FAILURE branches
LogQueryControllerInstanceIdsFilterIT	?instanceIds=a,b,c returns only matching rows; empty/missing param preserves prior behavior

UI component tests:

Test	What it asserts
SideDrawer.test.tsx	open/close, ESC closes, backdrop click closes, focus trap
CheckpointsTable.test.tsx	row click opens drawer; pruned-JAR row dimmed + clickable; empty state
CheckpointDetailDrawer.test.tsx	renders correct logs (mocked instance_id list); Restore disabled when JAR pruned
ConfigPanel.test.tsx	snapshot mode renders all fields read-only; diff mode counts differences correctly per sub-tab; "no differences" message when section unchanged; toggle hidden when JAR pruned

Files touched

Backend:

• New: cameleer-server-app/src/main/resources/db/migration/V2__add_deployment_created_by.sql
• Modified: cameleer-server-core/src/main/java/com/cameleer/server/core/admin/AuditCategory.java (add DEPLOYMENT)
• Modified: cameleer-server-core/src/main/java/com/cameleer/server/core/runtime/Deployment.java (record field)
• Modified: cameleer-server-core/src/main/java/com/cameleer/server/core/runtime/DeploymentService.java (signature + impl)
• Modified: cameleer-server-app/src/main/java/com/cameleer/server/app/storage/PostgresDeploymentRepository.java (insert + map)
• Modified: cameleer-server-app/src/main/java/com/cameleer/server/app/controller/DeploymentController.java (audit calls + createdBy resolution)
• Modified: cameleer-server-app/src/main/java/com/cameleer/server/app/controller/LogQueryController.java (instanceIds param)
• Modified: cameleer-server-core/src/main/java/com/cameleer/server/core/search/LogSearchRequest.java (instanceIds field)
• Regenerate: cameleer-server-app/src/main/resources/openapi.json (controller change → SPA types)

UI:

• New: ui/src/components/SideDrawer.tsx + SideDrawer.module.css
• New: ui/src/pages/AppsTab/AppDeploymentPage/CheckpointsTable.tsx
• New: ui/src/pages/AppsTab/AppDeploymentPage/CheckpointDetailDrawer/{index,LogsPanel,ConfigPanel}.tsx (Compare is a view-mode inside ConfigPanel, not a separate file)
• Modified: ui/src/pages/AppsTab/AppDeploymentPage/IdentitySection.tsx (swap Checkpoints → CheckpointsTable)
• Deleted: ui/src/pages/AppsTab/AppDeploymentPage/Checkpoints.tsx
• Modified: ui/src/pages/AppsTab/AppDeploymentPage/ConfigTabs/{Monitoring,Resources,Variables,SensitiveKeys,Deployment}Tab.tsx (add readOnly? prop)
• Modified: ui/src/api/queries/logs.ts (useInfiniteApplicationLogs accepts instanceIds)
• Modified: ui/src/api/queries/admin/apps.ts (Deployment.createdBy field)
• Modified: ui/src/api/schema.d.ts + ui/src/api/openapi.json (regenerated)
• Modified: ui/src/pages/Admin/AuditLogPage.tsx (one new category in filter dropdown)

Docs / rules:

• Modified: .claude/rules/app-classes.md (DeploymentController audit calls + LogQueryController instanceIds param)
• Modified: .claude/rules/ui.md (CheckpointsTable + SideDrawer pattern)
• Modified: .claude/rules/core-classes.md (AuditCategory.DEPLOYMENT, Deployment.createdBy)

Rollout

Two phases, ideally two PRs:

1. Backend phase — V2 migration, AuditCategory.DEPLOYMENT, audit calls in DeploymentController, created_by plumbing through DeploymentService / record / repository, LogQueryController instanceIds param. Ships independently because the column is nullable, the audit category is picked up automatically, and the new log filter is opt-in.
2. UI phase — SideDrawer, CheckpointsTable, CheckpointDetailDrawer, readOnly? props on the five config sub-tabs, audit-page dropdown entry. Depends on the backend PR being merged + the OpenAPI schema regenerated.

Splitting in this order means production gets the audit trail and created_by capture immediately, even before the new UI lands, so the audit gap is closed as quickly as possible.