Kordant/tasks/landing-pages-and-admin/02-admin-routes-dashboard.md

02. Admin Routes With Controls And Services Dashboard

meta: id: landing-pages-and-admin-02 feature: landing-pages-and-admin priority: P1 depends_on: [] tags: [implementation, routes, admin, dashboard, auth]

objective:

• Create admin-only routes at /admin with authentication guards, a main dashboard showing service health and metrics, and a blog management interface for creating/editing blog posts and marking featured posts.

deliverables:

• /web/src/routes/(admin)/index.tsx — Admin dashboard overview
• /web/src/routes/(admin)/blog.tsx — Blog post list and management
• /web/src/routes/(admin)/blog/new.tsx — Create new blog post
• /web/src/routes/(admin)/blog/[slug].tsx — Edit existing blog post
• /web/src/routes/(admin)/services.tsx — Services health/status dashboard
• /web/src/routes/(admin)/users.tsx — User management overview
• Admin layout wrapper with sidebar navigation
• tRPC router endpoints for admin CRUD operations
• Role-based access guard middleware

steps:

• Create (admin) route group directory at /web/src/routes/(admin)/
• Build admin layout component with sidebar navigation (Dashboard, Blog, Services, Users)
• Implement role-based access guard:
  • Check user has role of family_admin or support in database
  • Redirect unauthorized users to /dashboard with error toast
  • Use existing Clerk auth + database role check
• Create admin dashboard page (/admin):
  • Summary cards: total users, active subscriptions, blog posts count, alerts this week
  • Services status overview (DarkWatch, VoicePrint, SpamShield, HomeTitle, RemoveBrokers)
  • Recent activity feed (new signups, recent alerts, recent blog views)
• Create blog management pages:
  • List view: table of all blog posts with slug, title, author, date, status, featured toggle
  • New post form: title, slug (auto-generated), excerpt, content (markdown editor), author, cover image URL, tags, published toggle, featured toggle
  • Edit post form: same fields pre-populated from database
  • Featured post toggle: only one post can be featured at a time
• Create services dashboard page:
  • Health status indicators for each service
  • Metrics per service (usage counts, error rates, response times)
  • Ability to toggle service maintenance mode
• Create users management page:
  • Searchable/filterable user table
  • User details: name, email, role, subscription tier, join date
  • Role management (change user role)
• Wire up tRPC endpoints:
  • admin.blog.list — fetch all blog posts with pagination
  • admin.blog.create — create new blog post
  • admin.blog.update — update existing blog post
  • admin.blog.delete — soft delete blog post
  • admin.blog.toggleFeatured — set/unset featured post
  • admin.dashboard.stats — fetch dashboard statistics
  • admin.services.status — fetch service health data
  • admin.users.list — fetch user list with filters
  • admin.users.updateRole — update user role
• Add admin guard middleware/procedure decorator to tRPC router

tests:

• Unit: Admin guard correctly blocks non-admin users
• Unit: Blog form validation (required fields, unique slug, single featured post)
• Integration: Admin routes accessible only by users with admin/support roles
• Integration: Blog CRUD operations persist correctly to database
• Integration: Featured post toggle enforces single-featured constraint

acceptance_criteria:

• Navigating to /admin redirects to /login if not authenticated
• Navigating to /admin redirects to /dashboard if authenticated but not admin
• Admin dashboard shows summary cards with real data from database
• Blog list page shows all posts from database (not hardcoded)
• Creating a blog post via admin form saves to blogPosts table
• Editing a blog post updates the database record
• Featured post toggle marks one post as featured and unmarks any previously featured post
• Services dashboard shows health status for each product service
• Users page shows searchable list with role management
• Admin sidebar navigation works correctly across all admin pages

validation:

• cd /Users/mike/Code/Kordant/web && pnpm dev then navigate to /admin
• Test with non-admin user: should redirect to /dashboard
• Test with admin user: should show dashboard
• Create a test blog post and verify it appears in the database
• Toggle featured post and verify only one is featured at a time
• Check tRPC endpoints return correct data

notes:

• Database schema already has blogPosts table in marketing.ts with fields: id, slug, title, excerpt, content, authorName, coverImageUrl, tags, published, publishedAt, viewCount
• Need to add featured boolean column to blogPosts table
• User roles defined in schema: ["user", "family_admin", "family_member", "support"]
• Admin access should be granted to family_admin and support roles
• Use existing Clerk auth integration for session management
• Consider using a rich text editor or markdown editor for blog content (e.g., TipTap, Slate, or simple textarea)
• Admin route group (admin) follows SolidStart convention for route grouping
• Reference existing dashboard layout pattern in /web/src/components/dashboard/Sidebar.tsx for sidebar styling