RankFlow AI — Admin Dashboard UI Specifications

Version: 1.1.0
Route Prefix: /admin
Auth Required: ADMIN role only
Layout: Admin shell with sidebar navigation
Status: Post-Pivot (Directory Model)

---

1. Layout Architecture#

┌─────────────────────────────────────────────────────────────┐
│  Admin Shell (src/app/(admin)/layout.tsx)                    │
│  ┌──────────┐  ┌─────────────────────────────────────────┐  │
│  │ Sidebar  │  │  Header Bar                             │  │
│  │          │  │  ─────────────────────────────────────  │  │
│  │ • KPI    │  │                                       │  │
│  │ • Clients│  │  Main Content Area                    │  │
│  │ • Directory│  │  (page-specific)                      │  │
│  │ • Profiles│  │                                       │  │
│  │ • Social │  │                                       │  │
│  │ • Jobs   │  │                                       │  │
│  │ • Content│  │                                       │  │
│  │ • Billing│  │                                       │  │
│  │ • Reports│  │                                       │  │
│  └──────────┘  └─────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Shell Components#

---

2. Route Map#

---

3. Page Specifications#

3.1 /admin — KPI Overview#

Purpose: System-wide health dashboard for the admin

Layout: Full-width grid of stat cards + charts

Sections:

Data Requirements:

interface AdminKPIs {
  totalClients: number;
  activeClients: number;
  trialClients: number;
  churnedClients: number;
  mrr: number;              // Monthly recurring revenue (INR)
  arr: number;              // Annual recurring revenue (INR)
  activeJobs: number;
  failedJobs24h: number;
  citationHealth: number;     // % verified citations
  apiCosts7d: {
    claude: number;
    openai: number;
    dataforseo: number;
    serpapi: number;
    hyperbrowser: number;
    firecrawl: number;
  };
  recentActivity: AuditLogEntry[];
}

---

3.2 /admin/clients — Client List#

Purpose: CRUD management of all practices

Layout: Data table with filters + action bar

Table Columns:

Actions per Row:

• View → /admin/clients/[id]
• Edit → Inline modal
• Suspend → Confirmation dialog
• Delete → Confirmation dialog (soft delete)

Bulk Actions:

• Change tier
• Export CSV
• Send email

---

3.3 /admin/clients/[id] — Client Detail#

Purpose: Deep-dive into a single practice

Layout: Tabbed interface

Tabs:

Overview Card:

┌────────────────────────────────────────┐
│  [Logo]  Practice Name                 │
│          Type: Clinic | Tier: Premium  │
│          Status: ACTIVE                │
│          Members: 3 | Locations: 2      │
│                                        │
│  [Edit] [Impersonate] [Suspend]       │
└────────────────────────────────────────┘

---

3.4 /admin/directory — Directory Overview#

Purpose: High-level view of the directory health, coverage, and approval queue

Layout: Stat cards + approval queue + charts

Stat Cards (top row):

Approval Queue (middle section):

Charts (bottom section):

Filters:

• City dropdown
• Specialty dropdown
• Status multi-select (DRAFT, PENDING_REVIEW, PUBLISHED, PAUSED, ARCHIVED)
• Date range

---

3.5 /admin/directory-profiles — Profile Management#

Purpose: Manage all directory profiles in a single table

Layout: Data table with filters, bulk actions, and inline editing

Table Columns:

Filters:

• Status multi-select
• City dropdown
• Specialty dropdown
• Compliance status
• Date range
• Search (profile name)

Bulk Actions:

• Publish selected
• Unpublish selected
• Refresh content (triggers AI rewrite)
• Export CSV
• Delete (soft delete)

Actions per Row:

• Edit → /admin/directory-profiles/[id] (edit tab)
• Preview → /admin/directory-profiles/[id] (preview tab)
• Publish → Confirmation + ISR revalidation
• Unpublish → Confirmation + ISR revalidation

---

3.6 /admin/directory-profiles/[id] — Profile Detail#

Purpose: Deep-dive into a single directory profile with preview, editing, and publishing tools

Layout: Tabbed interface with live preview

Tabs:

Preview Tab:

┌────────────────────────────────────────────────────────────┐
│  👁️ Live Preview                                           │
│  https://indiandoctors.in/clinics/kochi/dr-smith-dental   │
│  [ Open in New Tab ]  [ Copy Public URL ]                │
│                                                            │
│  ┌────────────────────────────────────────────────────┐  │
│  │  [Live iframe or screenshot of the profile page]    │  │
│  │  Hero, Bio, Services, Reviews, FAQ, Map, Contact    │  │
│  └────────────────────────────────────────────────────┘  │
│                                                            │
│  [ ✅ Publish ]  [ ⏸️ Unpublish ]  [ 🔄 Revalidate ISR ] │
│  [ 📝 Edit Content ]  [ 📋 Request Approval ]            │
└────────────────────────────────────────────────────────────┘

Edit Tab:

SEO Tab:

GBP Tab:

Analytics Tab:

History Tab:

ISR Revalidation Button:

A prominent action button on the Preview tab that triggers Next.js ISR revalidation for this profile's route:

// Action: Revalidate ISR
await fetch('/api/revalidate', {
  method: 'POST',
  body: JSON.stringify({ citySlug, slug }),
});

Content Compliance Check Status:

A persistent status indicator on the Edit tab showing whether the current content passes MCI compliance checks:

If failed, the specific violations are listed with inline suggestions.

---

3.7 /admin/social-connections — Social Accounts#

Purpose: Overview of all connected social accounts across clients

Table Columns:

---

3.8 /admin/jobs — Job Monitor#

Purpose: Real-time monitoring of the job queue

Layout: Stat cards + live-updating data table

Stat Cards (top row):

Table Columns:

Filters:

• Status multi-select
• Practice dropdown
• Skill dropdown
• Date range

Auto-refresh: Every 10 seconds

---

3.9 /admin/content — AI Content Review#

Purpose: Review and manage AI-generated content across all clients

Layout: Split view — list left, preview right

List Columns:

Preview Panel:

• Rendered content (HTML)
• SEO score
• Readability score
• Compliance check status (Pass / Warning / Fail)
• Approve / Reject / Edit buttons

Prompt Management Tab:

• List all prompt templates
• Edit system prompt
• Edit user prompt template
• A/B test variants
• Performance scores

---

3.10 /admin/billing — Billing Overview#

Purpose: Subscription and payment management

Layout: Revenue cards + tables

Revenue Cards:

Tables:

1. Subscriptions: Practice, tier, status, next billing, amount
2. Invoices: Invoice ID, practice, amount, status, paid date
3. Failed Charges: Practice, amount, failure reason, retry count

---

3.11 /admin/reports — System Reports#

Purpose: Historical analytics and exportable reports

Available Reports:

---

4. Component Hierarchy#

AdminLayout
├── AdminShell
│   ├── AdminSidebar
│   │   ├── NavGroup "Overview"
│   │   │   └── NavItem "KPI Dashboard" → /admin
│   │   ├── NavGroup "Clients"
│   │   │   ├── NavItem "All Clients" → /admin/clients
│   │   │   └── NavItem "Social Accounts" → /admin/social-connections
│   │   ├── NavGroup "Directory"
│   │   │   ├── NavItem "Directory Overview" → /admin/directory
│   │   │   └── NavItem "Directory Profiles" → /admin/directory-profiles
│   │   ├── NavGroup "Operations"
│   │   │   ├── NavItem "Job Monitor" → /admin/jobs
│   │   │   └── NavItem "Content Review" → /admin/content
│   │   └── NavGroup "Finance"
│   │       ├── NavItem "Billing" → /admin/billing
│   │       └── NavItem "Reports" → /admin/reports
│   ├── AdminHeader
│   │   ├── Breadcrumbs
│   │   ├── GlobalSearch
│   │   ├── NotificationBell
│   │   └── UserMenu
│   └── PageContent
│       ├── (page-specific components)
│       └── DataTable / Form / Chart

Reusable Admin Components#

---

5. Data Requirements#

tRPC Queries per Page#

---

6. Access Control#

Role Gate#

// src/app/(admin)/layout.tsx
export default async function AdminLayout({ children }) {
  const session = await getServerSession();
  if (session?.user?.role !== "ADMIN") {
    redirect("/dashboard");
  }
  return <AdminShell>{children}</AdminShell>;
}

API Protection#

All admin endpoints use adminProcedure which enforces:

1. User is authenticated
2. User role === "ADMIN"
3. Returns 403 FORBIDDEN otherwise

Impersonation#

Admin can "impersonate" a client to see their dashboard:

• Sets x-practice-id header
• Temporarily gains practiceProcedure access
• Audit log records impersonation

---

7. Responsive Behavior#

Mobile Adaptations#

• Sidebar becomes drawer
• Data tables become card lists
• Filters collapse into sheet
• Charts stack vertically

---

End of Admin Dashboard UI Specifications