admin-page-for-nextjs-sites

name	admin-page-for-nextjs-sites
description	Design cohesive Next.js SaaS admin cockpits. Use when building or expanding `/admin` and `/api/admin` with unified IA, permissions, audit, analytics, ops, moderation, billing, and user-management.

Admin Page for Next.js Sites

Use When

• Building a new Next.js admin console.
• Expanding /admin without duplicating capability.
• Merging multiple admin systems into one cockpit.
• Hardening privileged flows (refunds, moderation, impersonation, retries).

THE EXACT PROMPTS

1) Build/Expand

Design and implement a cohesive admin cockpit for this Next.js SaaS codebase.

Requirements:
1. Inventory `/admin` pages, APIs, permissions, data sources, jobs.
2. Build a harmonized IA (Overview, Users, Billing, Support, Moderation, Content, Analytics, Experiments, Operations, Compliance, Health).
3. Integrate non-duplicative features via shared primitives (shell, filters, tables, permissions, audit, response envelope).
4. Implement vertical slices with explicit acceptance criteria and no parallel systems.
5. Add tests for high-risk mutations and operator flows.

Output:
- route map, API/contracts plan, data model deltas
- phased rollout plan + concrete code changes

2) Consolidation/Audit

Audit this Next.js admin system for fragmentation, risk, and missing operator workflows.

Return:
1. Overlapping capabilities to merge.
2. High-risk endpoints missing permission + audit controls.
3. Read-only dashboards that should become action queues.
4. Missing operational controls (job retries, provider health, stale-data indicators).
5. Prioritized remediation slices with acceptance criteria.

3) Security + Audit Deep Dive

Use references/CASS-PROMPT-ARCHETYPES.md (Archetype 6).

4) Admin API Integrity Sweep

Use references/CASS-PROMPT-ARCHETYPES.md (Archetype 5).

5) Moderation Queue Slice Prompt

Use references/CASS-PROMPT-ARCHETYPES.md (Archetype 3).

6) Cross-Repo Pattern Mining Prompt

Use references/CASS-PROMPT-ARCHETYPES.md (Archetype 2).

7) World-Class Enhancement Plan Prompt

Use references/CASS-PROMPT-ARCHETYPES.md (Archetype 7).

Cass Grounding Loop (Use Before Large Admin Work)

cass status --json && cass index --json
cass search "*" --workspace /data/projects/<repo> --aggregate agent,date --limit 1 --json
cass search "admin" --workspace /data/projects/<repo> --fields minimal --limit 80 --json \
  | jq '[.hits[] | select(.line_number <= 3)]'
# Follow best hits:
cass view <source_path> -n <line> -C 20

• Treat repeated prompt families as operating playbooks.
• Reuse real prompt skeletons, then generalize names/paths/constraints.
• Prefer prompts with explicit deliverables, acceptance criteria, and bug-report format.

Quick Start

rg --files src/app | rg '/admin|api/admin'
rg -n "requireAdmin|isAdmin|permission|audit|role" src
rg -n "job|queue|retry|webhook|health" src/app src/lib src/services
# Build EXISTING/PARTIAL/MISSING map via FEATURE-CATALOG
# Start with shell + permissions + audit + query patterns

Workflow (Harmonization)

1. Mine cass first: collect 3-5 relevant prompt archetypes; adapt, do not invent blindly.
2. Map state: pages/APIs/mutations/permissions; tag EXISTING|PARTIAL|MISSING.
3. Define IA once: one route tree, grouped nav, no parallel sections.
4. Shared primitives: AdminShell, filters/date range, cards/toolbars, table primitives.
5. Unified contracts: response envelope, error codes, validation.
6. Permissions: domain-action keys (users.read, billing.adjust, ops.retry) at page/API boundaries.
7. Audit high-risk actions: actor/action/target/reason/before-after/request-context.
8. Operator workflows first: queues + transitions, not chart-only pages.
9. Observability: jobs, failed queues + retry, provider health, freshness timestamps.
10. Vertical slices: Foundation -> Users -> Billing/Ops -> Support/Moderation -> Analytics/Experiments -> Content/Comms.
11. Harden before breadth: integration/E2E for dangerous flows.

Hard Invariants

• One admin shell (single nav + context).
• One permission registry (no ad-hoc inline checks).
• One audit pipeline (all privileged mutations).
• One query-key strategy (central keys + TanStack hooks).
• One mutation contract (validated input, deterministic responses).
• One ops model (status, retries, last error for async jobs).

Deliverables

• Unified route map.
• Permission matrix by domain/action.
• Admin API contract map (read + mutation).
• Audit event taxonomy.
• Phased rollout with acceptance criteria.
• Test plan for high-risk flows.

Anti-Patterns

• Many dashboards, few actions.
• Duplicate capability under different section names.
• UI-only auth checks without API enforcement.
• Privileged mutations without reason + audit.
• Ad-hoc fetches instead of shared query hooks.
• Breadth expansion before foundation hardening.

References

• Feature inventory: FEATURE-CATALOG.md
• Architecture blueprint: IMPLEMENTATION-BLUEPRINT.md
• Phased rollout: PHASED-ROLL-OUT.md
• Build/review checklist: CHECKLIST.md
• Copy-paste templates: TEMPLATES.md
• Failure modes: FAILURE-MODES.md
• Operator UX standards: OPERATOR-UX-STANDARDS.md
• Cass prompt archetypes: CASS-PROMPT-ARCHETYPES.md

Reference Index

Need	Open
Capability map	FEATURE-CATALOG.md
Architecture	IMPLEMENTATION-BLUEPRINT.md
Rollout	PHASED-ROLL-OUT.md
Quality gates	CHECKLIST.md
Templates	TEMPLATES.md
Failures	FAILURE-MODES.md
Operator UX	OPERATOR-UX-STANDARDS.md
Cass archetypes	CASS-PROMPT-ARCHETYPES.md