kuberlab/training-agent

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:

bash
git clone <repository-url>
cd training-agent

2. Install dependencies:

bash
npm install

3. Set up PostgreSQL database:

bash
# Create a PostgreSQL database for the application
createdb training_agent

4. Configure environment variables:

bash
# 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

5. Set up the database:

bash
cd server
npm install
npm run migrate:up

6. Start the backend server:

bash
npm run dev

7. Start the frontend application:

bash
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:

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:

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

bash
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] .