Admin Dashboard

The Admin Dashboard is a React-based web application that serves as the primary interface for managing the AngelCX AI agent platform. Built with modern web technologies and following best practices, it provides a robust and user-friendly interface for administrators and customers to manage their AI agents, conversations, and integrations.

Technology Stack

• Frontend Framework: React with TypeScript
• UI Components: shadcn/ui (based on Radix UI)
• Styling: Tailwind CSS
• State Management: Jotai
• API Management: TanStack Query (React Query)
• Routing: React Router v7
• Authentication: AWS Amplify/Cognito
• Build Tool: Vite

Framework Choice

Why Not Next.js?

While Next.js is a powerful framework, it wasn't chosen for the Admin Dashboard for several reasons:

1. Development Experience

   • Development server becomes significantly slower with large codebases
   • Hot module replacement (HMR) performance degrades as the application grows
   • Complex caching behavior in development leads to inconsistent states

2. Performance Considerations

   • SSR and SSG features weren't necessary for an admin dashboard
   • Client-side rendering provides faster page transitions for dynamic content
   • Better runtime performance without the overhead of server components

3. Application Requirements

   • Admin dashboard needs quick client-side updates and interactions
   • Most data is user-specific and dynamic, reducing SSR benefits
   • No SEO requirements for admin interface

4. Development Velocity

   • Simpler development workflow with Vite
   • Faster feedback loop during development
   • More straightforward debugging without server/client boundary complexities

API Data Management

The dashboard uses TanStack Query (formerly React Query) for efficient API interactions:

// Example of API integration with TanStack Query
const { data, isLoading } = useQuery({
  queryKey: ['agentConfig', agentId],
  queryFn: () => agentService.fetchConfiguration(agentId),
  staleTime: 5 * 60 * 1000, // 5 minutes
});

Key benefits: - Automatic background refetching - Cache invalidation and management - Optimistic updates - Infinite loading and pagination support - Request deduplication - Parallel queries

AWS Amplify Authentication

The Admin Dashboard uses AWS Amplify for authentication and user management. The setup is configured in the amplify directory:

// amplify/auth/resource.ts
import { defineAuth } from '@aws-amplify/backend';

export const auth = defineAuth({
  // Cognito User Pool configuration
});

Authentication Features

1. Cognito User Pool

   • Email/password authentication
   • Custom email templates for verification
   • MFA configuration options

2. Post-Confirmation Flow

   • Lambda trigger after successful account confirmation
   • Creates customer record in database
   • Sets up initial customer configuration
   • Associates Cognito user with customer record

Backend Configuration

// amplify/backend.ts
import { defineBackend } from '@aws-amplify/backend';
import { auth } from './auth/resource';

defineBackend({
  auth,
  // Other Amplify resources
});

Project Structure

├── amplify/               # AWS Amplify backend configuration
│   ├── auth/             # Cognito authentication setup
│   └── backend.ts        # Amplify backend definition
├── app/                  # Main application code
│   ├── components/       # React components
│   │   ├── ui/          # Base UI components (shadcn)
│   │   ├── sidebar/     # Sidebar related components
│   │   └── ...          # Feature-specific components
│   ├── routes/          # React Router route components
│   ├── services/        # API services
│   ├── util/            # Utility functions
│   └── app.css          # Global styles
├── public/              # Static assets
└── build/              # Production build output

Core Features

Authentication Flow

Design System

The dashboard utilizes shadcn/ui, providing:

1. Base Components

   • Button variants (primary, secondary, ghost)
   • Form inputs and controls
   • Modal dialogs and drawers
   • Navigation components
   • Cards and containers
   • Typography system

2. Theme Customization

   • CSS variable-based theming
   • Dark/Light mode support
   • Responsive design patterns
   • Custom color schemes
   • Accessible contrast ratios

State Management

Global state is managed through Jotai atoms:

const customerDetailsAtom = atom({
  profile: CustomerProfile,
  settings: CustomerSettings
});

// Other State Atoms

Key Features

1. AI Agent Management

• Agent behavior customization
• Response configuration
• Knowledge base management
• Voice and personality settings
• Custom prompt templates

2. Analytics Dashboard

• Conversation metrics
• Performance analytics
• Usage statistics
• Custom report generation
• Data visualization

3. Integration Management

• Third-party service connections
• OAuth flow handling
• Script generation

4. Content Management

• Knowledge base updates
• Training data management
• Response template configuration
• Document ingestion

Security Considerations

1. Authentication

   • AWS Cognito integration
   • Token-based authentication
   • Role-based access control
   • Session management
   • MFA support

2. Data Protection

   • HTTPS enforcement
   • API request encryption
   • Sensitive data handling
   • XSS protection

Deployment Workflow

The application is deployed using AWS Amplify's CI/CD pipeline:

1. Code push triggers build
2. Automated testing runs
3. Production build created
4. CDN distribution updated
5. Cache invalidation

Error Handling

1. Client-Side Errors

   • Form validation
   • Network error handling
   • State management errors
   • Retry mechanisms
   • Offline support

2. API Error Handling

   • Error boundary implementation
   • Toast notifications
   • Retry mechanisms
   • Fallback states
   • Error logging

Monitoring and Logging (CloudWatch)

1. Application Monitoring

   • Error tracking
   • Performance metrics
   • User behavior analytics
   • Resource usage
   • API latency

2. Error Reporting

   • Stack trace collection
   • Error context capturing
   • Alert configuration
   • Dashboard metrics