Skip to content

README.md

Latest commit

 

History

History
325 lines (239 loc) · 9.8 KB

README.md

File metadata and controls

325 lines (239 loc) · 9.8 KB

ICC Rule Engine Admin Dashboard

A lightweight React-based admin dashboard for managing the ICC Rule Engine system. This internal tool provides comprehensive system administration capabilities including rule management, validation monitoring, and system configuration.

Features

  • Dashboard: System health monitoring, metrics, and recent activity
  • Rules Management: CRUD operations with JSON editor and bulk upload
  • Validation Logs: Search and view validation history (coming soon)
  • Webhooks: Manage webhook endpoints and test deliveries (coming soon)
  • API Keys: Create and manage API keys with role-based access (coming soon)
  • Tenants: Multi-tenant organization management (coming soon)
  • Versions: Ruleset version management and releases (coming soon)
  • Settings: System configuration and feature flags (coming soon)

Tech Stack

  • Frontend: React 18 + TypeScript + Vite
  • Styling: TailwindCSS + Custom component library
  • State Management: TanStack Query (React Query)
  • Routing: React Router v6
  • Icons: Lucide React
  • Development: Hot reload, TypeScript checking, ESLint

Prerequisites

  • Node.js 18+
  • npm or yarn
  • ICC Rule Engine backend running (default: http://localhost:8000)
  • Admin API key for backend access

Setup

1. Install Dependencies

cd admin
npm install

2. Environment Configuration

Create a .env.local file (copy from .env.local.example):

cp .env.local.example .env.local

Configure the following variables:

# Backend API Configuration
VITE_API_BASE_URL=http://localhost:8000
VITE_DASHBOARD_TITLE=ICC Rule Engine Admin
VITE_ADMIN_API_KEY=your-admin-api-key-here

3. Backend Configuration

Ensure your backend is configured to allow admin dashboard access:

Environment Variables (in backend .env):

ADMIN_CORS_ORIGINS=http://localhost:3001,http://localhost:3000
MULTI_TENANT_ENABLED=false  # or true for multi-tenant mode

Admin API Key: Create an admin-level API key in your backend system. The key should have admin role for full dashboard access.

Development

Start Development Server

npm run dev

The dashboard will be available at http://localhost:3001

Available Scripts

  • npm run dev - Start development server with hot reload
  • npm run build - Build production bundle
  • npm run preview - Preview production build locally
  • npm run lint - Run ESLint for code quality

Development Workflow

  1. Start Backend: Ensure ICC Rule Engine backend is running on port 8000
  2. Set API Key: Configure VITE_ADMIN_API_KEY in .env.local
  3. Start Frontend: Run npm run dev to start the admin dashboard
  4. Access Dashboard: Navigate to http://localhost:3001

Authentication

The admin dashboard uses API key-based authentication:

  • Header: X-API-Key: your-admin-key
  • Role: API key must have admin role for full access
  • Security: Keys are validated by the backend tenant middleware

API Key Requirements

  • Must be registered in backend system
  • Role: admin (for full dashboard access)
  • Status: active and not expired
  • Associated with valid tenant (in multi-tenant mode)

API Endpoints

The dashboard communicates with these backend endpoints:

Core Endpoints

  • GET /health - System health and version info
  • GET /rules - List all rules
  • POST /rules - Create new rule
  • PUT /rules/{id} - Update existing rule
  • DELETE /rules/{id} - Delete rule

Admin Endpoints

  • GET /admin/settings - System settings and feature flags
  • GET /admin/me - Current user info and permissions
  • GET /admin/tenants - List tenants (admin only)
  • GET /admin/api-keys - List API keys (admin only)
  • GET /admin/validation-logs - List validation logs (admin only)

Metrics Endpoints

  • GET /metrics - Prometheus metrics
  • GET /usage - Usage statistics

Features by Page

1. Dashboard

  • System health status with real-time updates
  • Key metrics: total rules, tenants, API keys, 24h validations
  • Validation statistics: success rate, average score
  • Recent validation activity list

2. Rules Management

  • List View: Searchable table with filtering by source, severity
  • Create/Edit: Form with validation for all rule fields
  • JSON Editor: Direct JSON editing with validation
  • Bulk Upload: Upload JSON files (single rule or array)
  • Export: Download filtered rules as JSON
  • Toggle Status: Activate/deactivate rules

3. Other Pages (Coming Soon)

The remaining pages (Validation Logs, Webhooks, API Keys, Tenants, Versions, Settings) are implemented as placeholder components and will be fully developed in subsequent phases.

Building for Production

1. Build the Application

npm run build

This creates a dist/ folder with optimized static files.

2. Deployment Options

Option A: Static File Hosting

Deploy the dist/ folder to any static hosting service:

  • Render Static Sites: Connect GitHub repo, set build command to npm run build
  • Vercel: Simple deployment with GitHub integration
  • Netlify: Drag and drop dist/ folder or connect repository
  • AWS S3 + CloudFront: Upload to S3 bucket with CloudFront distribution

Option B: Server Integration

Serve static files from your existing backend server or reverse proxy.

3. Production Environment Variables

Set these environment variables in your deployment:

VITE_API_BASE_URL=https://your-backend-domain.com
VITE_DASHBOARD_TITLE=ICC Rule Engine Admin
VITE_ADMIN_API_KEY=prod-admin-key-here

Security Note: In production, consider loading the API key from a secure environment variable at build time or implementing server-side injection.

Security Considerations

API Key Management

  • Development: Store in .env.local (git-ignored)
  • Production: Use secure environment variable injection
  • Never: Commit API keys to version control

CORS Configuration

  • Configure ADMIN_CORS_ORIGINS in backend to allow only your admin domain
  • Use HTTPS in production
  • Consider IP whitelisting for admin access

Access Control

  • Admin dashboard is for internal use only
  • All API calls require admin-level API key
  • Backend validates permissions on every request

Troubleshooting

Common Issues

  1. CORS Errors

    • Ensure ADMIN_CORS_ORIGINS includes your frontend URL
    • Check backend CORS middleware configuration

  2. Authentication Failed

    • Verify VITE_ADMIN_API_KEY is set correctly
    • Ensure API key has admin role in backend
    • Check that API key is active and not expired

  3. Connection Refused

    • Verify backend is running on correct port
    • Check VITE_API_BASE_URL matches backend URL
    • Ensure no firewall blocking requests

  4. Build Errors

    • Run npm ci to clean install dependencies
    • Check Node.js version (requires 18+)
    • Clear npm cache if needed: npm cache clean --force

Debug Mode

Enable debug logging by setting:

VITE_DEBUG=true

This will show API request/response details in browser console.

Architecture

Component Structure

src/
├── components/
│   ├── ui/           # Reusable UI components
│   └── layout/       # Layout components (Sidebar, TopBar)
├── pages/            # Page components
├── lib/
│   ├── api.ts        # API client with auth wrapper
│   ├── types.ts      # TypeScript type definitions
│   ├── query.ts      # React Query configuration
│   └── utils.ts      # Utility functions
├── routing.tsx       # React Router setup
├── App.tsx          # Main app component
└── main.tsx         # Entry point

State Management

  • Server State: Managed by TanStack Query with caching
  • Component State: React hooks for local UI state
  • Global State: React Context for toast notifications

API Client

All API calls go through a central client (lib/api.ts) that:

  • Adds authentication headers automatically
  • Handles base URL configuration
  • Provides typed request/response interfaces
  • Includes error handling and retry logic

Contributing

Code Style

  • Use TypeScript for all new code
  • Follow existing component patterns
  • Use Tailwind classes for styling
  • Add proper error handling and loading states

Adding New Features

  1. Define types in lib/types.ts
  2. Add API calls to lib/api.ts
  3. Create page components in pages/
  4. Add routes to routing.tsx
  5. Update navigation in components/layout/Sidebar.tsx

Testing

While not implemented in this MVP, consider adding:

  • Unit tests with Vitest
  • Integration tests with Testing Library
  • E2E tests with Playwright

Roadmap

Phase 1 ✅ (Current)

  • Project setup and core infrastructure
  • Dashboard with system metrics
  • Rules management with CRUD operations
  • Basic authentication and CORS setup

Phase 2 (Coming Soon)

  • Validation Logs with search and filtering
  • Webhooks management with test functionality
  • API Keys CRUD with role management
  • Enhanced error handling and user feedback

Phase 3 (Future)

  • Tenants management for multi-tenant setups
  • Versions management for ruleset releases
  • Settings page with feature flag controls
  • Advanced monitoring and analytics

Phase 4 (Future)

  • User management and authentication
  • Audit logging and compliance features
  • Advanced reporting and data export
  • System backup and restore capabilities

Support

For issues and questions:

  1. Development Issues: Check troubleshooting section above
  2. Feature Requests: Create GitHub issue with detailed requirements
  3. Bug Reports: Include reproduction steps and environment details
  4. Security Issues: Report privately to the development team

Note: This admin dashboard is designed for internal use by system administrators. Ensure proper access controls and security measures are in place before deploying to production environments.