kuberlab/training-agent repository overview

⁠Training Agent App

A React TypeScript application with secure backend integration that generates AI-powered training plans from datasets using PostgreSQL database and Builder API.

⁠Architecture

This application uses a secure frontend-backend architecture with:

• React Frontend: Single-page application with secure backend integration
• Node.js Backend: Secure server with PostgreSQL database and Builder API proxy
• PostgreSQL Database: Direct database operations for optimal performance
• Builder API: Server-side integration for AI training plan generation

⁠Features

• Secure Architecture: Builder API credentials handled server-side for maximum security
• PostgreSQL Database: High-performance direct database operations (migrated from Supabase)
• Dataset Management: Browse and select from available datasets via secure backend API
• AI Training Plans: Generate comprehensive training plans using Builder's AI capabilities
• Interactive Learning: Student learning interface with progress tracking and quiz functionality
• Role-Based Access: Manager and trainee roles with appropriate permissions
• Training Materials: Generate, review, and approve training materials
• Real-time Status: Shows connection status for backend services

⁠Getting Started

⁠Prerequisites

• Node.js 18+
• npm or yarn
• PostgreSQL database
• Builder API access (for configuration)

⁠Quick Setup

1. Clone the repository:

git clone <repository-url>
cd training-agent

1. Install dependencies:

npm install

1. Set up PostgreSQL database:

# Create a PostgreSQL database for the application
createdb training_agent

1. Configure environment variables:

# Backend configuration
cd server
cp .env.example .env
# Edit server/.env with your database and Builder API credentials

# Frontend configuration
cd ..
cp .env.example .env
# Edit .env with your frontend configuration

1. Set up the database:

cd server
npm install
npm run migrate:up

1. Start the backend server:

npm run dev

1. Start the frontend application:

cd ..
npm run dev

The backend will be available at http://localhost:3001 and the frontend at http://localhost:5173.

⁠Configuration

⁠✅ Secure PostgreSQL Architecture

This application uses a secure architecture with PostgreSQL database and server-side Builder API integration.

⁠Backend Server Configuration (Required)

Configure the backend server in server/.env:

# PostgreSQL Database Configuration
PGHOST=localhost
PGPORT=5432
PGDATABASE=training_agent
PGUSER=postgres
PGPASSWORD=your_postgres_password

# Builder API Configuration (Backend Only - Secure)
BUILDER_API_TOKEN=your_api_token_here
BUILDER_API_BASE_URL=https://api.builder.example.com
BUILDER_IS_WORKSPACE_TOKEN=false
BUILDER_WORKSPACE_ID=

# Server Configuration
PORT=3001
FRONTEND_URL=http://localhost:5173
NODE_ENV=development

⁠Frontend Configuration

Configure the frontend in .env:

# Backend Service Configuration
# The application uses relative URLs for backend communication
# This works when frontend and backend are served from the same domain
# VITE_BACKEND_URL=http://localhost:3001

# Language Configuration
VITE_DEFAULT_LANGUAGE=en

Note: The application automatically uses relative URLs for API requests (e.g., /api/datasets), making the application more portable across different environments.

Note: All database operations and Builder API credentials are handled securely on the backend. No sensitive credentials are exposed to the frontend.

⁠Operation Modes

The application automatically operates in different modes:

1. Connected Mode: Builder API available

   • Real datasets from Builder API
   • AI-generated training plans
   • Full functionality

2. Demo Mode: Builder API unavailable

   • Uses mock datasets and responses
   • No API dependency
   • Perfect for development/testing

⁠Architecture

⁠Core Components

• App.tsx: Main application wrapper with API provider
• TrainingAgentApp.tsx: Main application logic and routing
• ApiConfig.tsx: API configuration interface
• ApiContext.tsx: React context for API client management

⁠API Integration

• apiClient.ts: TypeScript API client for Builder platform
• useApiClient.ts: React hooks for API operations
• types/api.ts: TypeScript type definitions

⁠Key Features

1. Automatic Fallback: Seamlessly switches between API and demo modes
2. Error Handling: Comprehensive error handling with user feedback
3. Loading States: Proper loading indicators for all operations
4. Type Safety: Full TypeScript support with strict typing
5. Responsive Design: Works on desktop and mobile devices

⁠API Client Features

The integrated API client supports:

⁠Authentication

• Bearer token authentication
• Workspace-specific tokens
• Automatic workspace detection

⁠Datasets

• List available datasets
• Upload and manage dataset files
• Download dataset files

⁠Extractors

• Create and manage extractors
• Process data through extractors
• Retrieve extraction results
• File upload and management

⁠Chat & Messaging

• Create and manage chat sessions
• Send messages and receive AI responses
• Wait for message completion
• Export/import chat history

⁠Timelines

• Create and manage timelines
• Add timeline points and changes
• Process timeline data
• File management for timeline points

⁠Usage

⁠Basic Workflow

1. Start the App: Launch the application
2. Configure API (optional): Set up Builder API credentials
3. Select Dataset: Choose from available datasets
4. Generate Plan: AI generates initial training plan
5. Refine Plan: Use chat interface to modify and improve
6. Export Results: Save or export the final training plan

⁠API Configuration UI

The app includes a built-in configuration interface:

• Secure token input with show/hide toggle
• URL validation
• Connection testing
• Configuration persistence (excluding sensitive tokens)

⁠Development

⁠Project Structure

src/
├── components/          # React components
│   ├── ApiConfig.tsx   # API configuration UI
│   └── TrainingAgentApp.tsx # Main app component
├── contexts/           # React contexts
│   └── ApiContext.tsx  # API client context
├── hooks/              # Custom React hooks
│   └── useApiClient.ts # API operation hooks
├── services/           # Business logic
│   └── apiClient.ts    # API client implementation
├── types/              # TypeScript definitions
│   └── api.ts          # API type definitions
└── App.tsx             # Root component

⁠Adding New API Features

1. Add types to src/types/api.ts
2. Implement methods in src/services/apiClient.ts
3. Create hooks in src/hooks/useApiClient.ts
4. Use in components via context

⁠Error Handling

The app implements comprehensive error handling:

• Network errors with retry mechanisms
• API errors with user-friendly messages
• Validation errors with inline feedback
• Fallback to demo mode on API failures

⁠Building for Production

npm run build

The built files will be in the dist/ directory.

⁠Environment Variables

⁠Frontend Variables

Note: The application uses relative URLs for backend communication, so no backend URL configuration is needed.

⁠Backend Variables (server/.env)

⁠Troubleshooting

⁠Backend Connection Issues

Problem: "Backend service unavailable" or connection errors Solution:

1. Ensure backend server is running on the same domain/port as the frontend
2. Verify backend service health at /api/health
3. Check browser console for network errors
4. Ensure frontend and backend are served from the same origin

⁠Builder API Issues (Backend)

Problem: "Using demo data - Builder API unavailable" message Solution:

1. Check Builder API credentials in server/.env
2. Verify the API token is valid and not expired
3. Check if the Builder API base URL is correct
4. Check backend server logs for detailed error messages

⁠Common Configuration Issues

1. Missing .env files: Copy .env.example to .env (frontend) and server/.env.example to server/.env (backend)
2. Invalid Builder API credentials: Verify backend BUILDER_API_TOKEN is correct and has proper permissions
3. Supabase configuration: Ensure both frontend and backend Supabase URLs match
4. CORS issues: Backend handles CORS for frontend requests
5. Same-origin policy: Ensure frontend and backend are served from the same domain/port

⁠Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

⁠License

[Your License Here] .