RankFlow AI Mock Application — Parallel Execution Plan

Status: Active grounding document
Version: 1.0.0
Last updated: 2026-06-21
Coordinator: Primary Codex agent
Canonical implemented screen: /dashboard

1. Outcome#

Build one deployable Next.js mock application that validates the complete RankFlow customer and operator journey before production API work begins.

The mock must let a stakeholder click through:

1. Clinic onboarding.
2. AI-assisted profile generation.
3. Medical approval or rejection.
4. Directory profile publication.
5. Google Business Profile and citation operations.
6. Monthly visibility reporting.
7. Admin review and exception handling.

The mock is a product-contract exercise, not a disposable collection of screens. Screen states define fixture requirements; fixture requirements define mock API shapes; the mock API is never allowed to invent fields that no approved screen consumes.

2. Non-Negotiable Source Order#

When two documents disagree, agents must use this precedence order and record the conflict in the task handoff:

1. The two approved dashboard images:
   • public/images/homepage/homepage-results-dashboard-rise.png
   • public/images/homepage/homepage-citation-dashboard-rise-v2.png
2. docs/visual-dna.md and docs/brand/tokens/design-tokens.json.
3. docs/specs/frontend/frontend-spec-01-design-system.md.
4. The canonical /dashboard implementation created by task RF-UI-001.
5. Screen specifications under docs/specs/frontend/, docs/specs/user-dashboard-ui.md, and docs/specs/admin-dashboard-ui.md.
6. Product flow and content documents: docs/homepage-content.md, docs/homepage-build-plan.md, docs/directory-profile-plan.md, and docs/directory-website-architecture.md.
7. Backend specifications under docs/specs/.
8. Agent assumptions.

An agent may not replace a higher-precedence decision with a familiar library default.

3. Locked Product Decisions#

4. Canonical UI Contract#

The /dashboard visibility screen is the reference implementation for every application surface.

4.1 Visual Rules#

4.2 Component Rules#

• Reuse DashboardShell, DashboardSidebar, DashboardHeader, DashboardCard, metric-card, status-row, and chart primitives from the canonical screen.
• New dashboard cards may vary their internal layout but may not introduce a new radius, shadow, font weight, border color, or icon family.
• Data-dense pages use an overview band, a primary work surface, and an optional right detail rail, matching the citation reference.
• Empty, loading, error, rejected, pending-approval, published, processing, and needs-action states must be designed explicitly.
• Mobile collapses the sidebar to a compact header and turns multi-column grids into one reading order; it must not scale down desktop content until illegible.

4.3 Visual Acceptance#

• Desktop comparison viewport: 1536 × 1024.
• Tablet QA: 1024 × 768.
• Mobile QA: 390 × 844.
• No horizontal overflow at any target viewport.
• Reference-level layout tolerance: primary columns within 16px, card gaps within 4px, component radii exact, palette exact.
• A screenshot is required for every completed route before its task is marked done.

5. Architecture and Ownership#

src/
  app/
    dashboard/               client application routes
    admin/                   operator application routes
    clinics/[city]/[slug]/   public directory routes
    onboarding/              customer setup flow
  components/
    dashboard/               canonical shell and dashboard primitives
    admin/                   admin-only compositions
    directory/               public profile/search compositions
    onboarding/              setup and approval compositions
  features/
    approval/                state and transition rules
    citations/               citation operations rules
    directory-profile/       profile lifecycle rules
    search/                  deterministic mock search
  lib/mock/
    fixtures/                JSON-compatible source records
    repositories/            in-memory persistence boundary
    api/                     typed mock API facade
  shared/
    contracts/               types and schemas shared by UI and mock API

Until these folders exist, agents must place work in the closest existing src/app, src/components, or src/lib boundary and avoid unrelated restructuring.

6. Dependency Graph#

flowchart LR
  A[RF-PLAN-001 Grounding plan] --> B[RF-UI-001 Canonical dashboard]
  B --> C1[Client screen contracts]
  B --> C2[Admin screen contracts]
  B --> C3[Public directory contracts]
  B --> C4[Onboarding and approval contracts]
  C1 --> D[Typed fixture contract]
  C2 --> D
  C3 --> D
  C4 --> D
  D --> E[In-memory repositories]
  E --> F[Mock API facade]
  F --> G[Route integration]
  G --> H[End-to-end flows]
  H --> I[Visual, accessibility, and regression QA]

The hard gate is deliberate: no mock API implementation begins before the consuming screen contracts and typed fixture contract are approved.

7. Task Ledger#

Status values: BLOCKED, READY, IN PROGRESS, REVIEW, DONE.

Wave 0 — Grounding and Canonical Screen#

Wave 1 — Screen Contracts#

These tasks may execute in parallel after RF-UI-002. Each owns only its route/component folders.

Wave 2 — Screen-Derived Data Contract and Fixtures#

Fixture edge cases must include: incomplete NAP, citation processing, citation needs action, rejected medical copy, approval requested, no reviews, low review score, no ranking history, partial analytics, unpublished profile, and multi-location clinic.

Wave 3 — In-Memory Domain and Mock API#

The mock facade may mirror future tRPC procedure names, but must not introduce a network server solely for the prototype.

Wave 4 — Route Integration and Clickable Flows#

Wave 5 — Quality, Documentation, and Demo Readiness#

8. Parallel-Agent Operating Rules#

1. The coordinator assigns one task ID and explicit file ownership per agent.
2. An agent reads this plan, the task's listed references, and the canonical dashboard before editing.
3. No two agents edit the same file in the same wave.
4. Shared contracts are coordinator-owned until RF-DATA-202 is approved.
5. Agents return changed files, verification commands, screenshots, assumptions, and unresolved conflicts.
6. The coordinator performs integration and marks status; agents do not self-declare global completion.
7. At most three implementation agents run beside the coordinator so review keeps pace with output.
8. A blocked agent returns the nearest valid artifact instead of creating speculative API or data structures.

Required Agent Handoff#

TASK: <task ID and title>
FILES OWNED: <exclusive paths>
READ FIRST: <source documents>
INPUT CONTRACT: <types/components/assets already approved>
OUTPUT CONTRACT: <routes/components/tests/screenshots required>
DO NOT CHANGE: <shared files and higher-precedence decisions>
ACCEPTANCE: <task-specific checks>
VERIFY: <exact commands>

9. Definition of Done Per Screen#

• Route renders without console errors.
• Uses the canonical shell and tokens.
• All specified lifecycle states exist and can be reached.
• UI values come through one typed ViewModel boundary, not scattered literals.
• All buttons and controls have a visible or intentionally mocked outcome.
• Loading, empty, error, permission, and success states are covered where applicable.
• Keyboard navigation and visible focus work.
• Desktop, tablet, and mobile screenshots are attached.
• Typecheck and build pass.
• Architecture/changelog are updated if the route introduces a new boundary.

10. Verification Commands#

codegraph sync
npm run typecheck
npm run build
npm audit --audit-level=moderate

Add the project test runner and browser test commands as soon as RF-QA-501 introduces them.

11. Current Next Action#

Finish RF-UI-002: review the tablet breakpoint and provide human visual approval for /dashboard. Then change all Wave 1 screen tasks from BLOCKED to READY and launch agents with exclusive file ownership.