CROP Admin Documentation

This directory contains documentation for integrating and using the CROP Admin dashboard.

Available Documentation

Health Analytics API Integration

Complete guide for integrating the backend Health Analytics microservice.

Contents:

• API endpoint reference (4 endpoints)
• TypeScript types and examples
• Authentication with Clerk JWT
• Auto-refresh and error handling strategies
• Migration from mock data
• Troubleshooting common issues

Key Endpoints:

• GET /api/health/overview - System-wide health summary
• GET /api/health/vendors - All vendor metrics
• GET /api/health/vendors/:code - Single vendor details
• GET /api/health/collections - MongoDB collection statistics

Clerk Frontend Integration

Step-by-step guide for Clerk authentication setup and usage.

Contents:

• Environment configuration
• JWT template setup (api template)
• Cross-domain session sync (admin.crop.com ↔ app.crop.com)
• Role-based access control (Admin, Catalog Manager, Viewer)
• Authentication flow and protected routes
• Error handling and testing strategies
• Common issues and solutions

Quick Start

1. Configure Environment Variables

Copy .env.example to .env.local and fill in the required values:

cp .env.example .env.local

Required variables:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - From Clerk Dashboard
• CLERK_SECRET_KEY - From Clerk Dashboard
• NEXT_PUBLIC_HEALTH_API_URL - Backend Health Analytics API
• MONGODB_URI - MongoDB Atlas connection string

2. Set Up Clerk JWT Template

1. Go to Clerk Dashboard → JWT Templates
2. Create new template named api
3. Use default claims
4. Save template

3. Test Health Analytics Integration

The Source Tab in the Health Dashboard now connects to the real backend API:

import { HealthAnalyticsAPI } from "@/lib/health-analytics-api";
import { useAuth } from "@clerk/nextjs";

const { getToken } = useAuth();
const api = new HealthAnalyticsAPI(() => getToken({ template: "api" }));

// Fetch collections data
const data = await api.getCollections();

4. Run Development Server

bun dev

Visit http://localhost:3000 and sign in to test the integration.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    CROP Admin Dashboard                      │
│                  (admin.crop.com / localhost)                │
└───────────────────────┬─────────────────────────────────────┘
                        │
          ┌─────────────┼─────────────┐
          │                           │
          ▼                           ▼
┌──────────────────┐         ┌──────────────────┐
│  Clerk Auth      │         │ Health Analytics │
│  (JWT Tokens)    │         │ API              │
│                  │         │ api.crop.com     │
└──────────────────┘         └────────┬─────────┘
                                      │
                        ┌─────────────┴─────────────┐
                        │                           │
                        ▼                           ▼
              ┌──────────────────┐      ┌──────────────────┐
              │  MongoDB Atlas   │      │  Elasticsearch   │
              │  (crop_parts DB) │      │  (Search Index)  │
              └──────────────────┘      └──────────────────┘

Features Implemented

✅ Health Dashboard

• Source Tab: Real-time MongoDB collection statistics
• Real Tab: Elasticsearch search service monitoring
• Auto-refresh with configurable intervals
• Loading states and error handling
• Manual refresh controls

✅ Authentication

• Clerk integration with SSO (Google, Microsoft)
• JWT-based API authorization
• Cross-domain session sync
• Role-based access control
• Protected routes middleware

✅ Access Management

• Professional landing page (/)
• Access pending page (/access-pending)
• Request access form (/request-access)
• Not authorized page (/not-authorized)
• SSR authentication redirects

✅ Developer Experience

• TypeScript strict mode
• Comprehensive type definitions
• API client with error handling
• Auto-refresh utilities
• Documentation with examples

Next Steps

1. Complete Clerk Configuration

   • Set up JWT template in Dashboard
   • Configure production domains
   • Test authentication flow

2. Deploy to Production

   • Set production environment variables
   • Configure CORS on backend APIs
   • Test end-to-end integration
   • Monitor for errors

3. Add More Features

   • Vendor detail pages with drill-down analytics
   • Quality score trends and charts
   • Data integrity reports
   • Export functionality

Support

• Health Analytics API: See HEALTH_ANALYTICS_API.md
• Clerk Integration: See CLERK_FRONTEND_INTEGRATION.md
• Project Setup: See ../CLAUDE.md
• Backend Team: Contact backend developers for API issues

Contributing

When adding new documentation:

1. Create clear, structured markdown files
2. Include code examples with explanations
3. Add troubleshooting sections
4. Update this README with links

Last Updated: 2025-01-13 Admin Version: 0.1.0 Health Analytics API: v1.0