LogiFlow AI - Real TiDB Serverless Logistics Platform

A fully functional intelligent logistics management platform powered by real TiDB Serverless vector search and multi-step AI agents. This application provides production-ready agentic workflows that chain together live data ingestion, vector search, AI analysis, and automated actions.

🚀 Key Features

Multi-Step Agentic Workflows

1. Predictive Maintenance Agent

   • Real-time vehicle telemetry ingestion into TiDB Serverless
   • Live vector search to find similar vehicle patterns
   • Actual GPT-4 LLM calls for maintenance analysis
   • Automated maintenance scheduling with database persistence

2. Intelligent Route Optimization

   • Live route data collection with real vector embeddings
   • Real TiDB vector search for similar successful routes
   • Actual GPT-4 route optimization analysis
   • Database updates with optimized recommendations

3. Emergency Response Coordinator

   • Real-time emergency event logging with vector embeddings
   • Live TiDB search for similar incident patterns
   • Actual AI response strategy generation
   • Automated vehicle dispatch with database tracking

TiDB Serverless Integration

• Real Vector Search: Live VECTOR(1536) columns with VEC_COSINE_DISTANCE
• Live Data Processing: Real-time ingestion and querying
• Production Schema: Complete database with indexes and constraints
• Serverless Scaling: Auto-scaling with real connection pooling

🔧 REAL vs DEMO Mode

🟢 REAL MODE (with TiDB credentials):

• ✅ Live TiDB Serverless database connections
• ✅ Real vector search with VEC_COSINE_DISTANCE queries
• ✅ Actual OpenAI API calls for embeddings and GPT-4
• ✅ Persistent data storage and retrieval
• ✅ Real-time monitoring with live database events
• ✅ Production workflows with error handling and logging

🟡 DEMO MODE (without credentials):

• 🔄 Intelligent fallbacks with realistic mock data
• 🔄 Simulated workflows that demonstrate functionality
• 🔄 Local state management for testing and demos
• 🔄 Full UI functionality without external dependencies

🎯 What to Build - Hackathon Requirements

This project leverages TiDB Serverless (including vector search) on TiDB Cloud to create a working software application that showcases an innovative, multi-step, agentic solution. Our agent chains together multiple building blocks in automated workflows:

🔄 Multi-Step Workflow Implementation

Step	Description	Implementation
1. Ingest & Index Data	Pull in vectors, full-text docs, images or logs into TiDB Serverless	Vehicle telemetry, route data, and emergency events stored with vector embeddings
2. Search Your Data	Query indexes with vector search to find similar cases	VEC_COSINE_DISTANCE for pattern matching across logistics scenarios
3. Chain LLM Calls	Call LLMs to analyze results and suggest next steps	GPT-4 analysis for maintenance predictions, route optimization, and emergency response
4. Invoke External Tools	Plug in APIs or services	Automated vehicle dispatch, maintenance scheduling, and system notifications
5. Build Multi-Step Flow	Wire everything together for end-to-end automation	Complete workflows from data ingestion to final action execution

🛠 Technology Stack

Core Technologies

• Frontend: React 18, TypeScript, Tailwind CSS, Vite
• Database: TiDB Serverless with vector search capabilities
• AI Models: OpenAI GPT-4, text-embedding-3-small
• Backend: Node.js, Express.js, WebSocket

AI & Machine Learning

• Vector Embeddings: Text-embedding-3-small for semantic search
• LLM Analysis: GPT-4 for complex reasoning and recommendations
• Multi-Step Agents: Orchestrated workflows with chained AI calls
• Predictive Analytics: Time-series analysis and pattern recognition

🔧 Setup Instructions

1. Environment Variables

CRITICAL: Create a .env file in the root directory with your real credentials:

# TiDB Serverless Configuration
VITE_TIDB_HOST=gateway01.us-west-2.prod.aws.tidbcloud.com
VITE_TIDB_USERNAME=your-actual-username
VITE_TIDB_PASSWORD=your-actual-password
VITE_TIDB_DATABASE=your-actual-database

# OpenAI Configuration
VITE_OPENAI_API_KEY=sk-your-actual-openai-key

2. TiDB Serverless Setup

1. Create TiDB Cloud Account: Sign up at tidbcloud.com
2. Create Serverless Cluster: Choose the free tier for development
3. Get Real Connection Details: Copy actual host, username, password, and database name
4. Enable Vector Search: Ensure your cluster supports VECTOR operations
5. Test Connection: Use the "TiDB Setup" page in the app to verify connectivity

3. OpenAI API Setup

1. Get API Key: Visit platform.openai.com
2. Create Real API Key: Generate an actual API key with GPT-4 access
3. Add to Environment: Set real VITE_OPENAI_API_KEY in your .env file
4. Verify Access: Ensure you have credits and GPT-4 model access

4. Local Development

# Install dependencies
npm install

# Add your real credentials to .env file
cp .env.example .env
# Edit .env with your actual TiDB and OpenAI credentials

# Start development server
npm run dev

# Navigate to "TiDB Setup" to test your connection
# Then explore "TiDB AI Agent" for real workflows

# Build for production
npm run build

5. Deployment

The application supports both real and demo modes on Netlify:

1. Fork this repository
2. Connect to Netlify
3. Add your real environment variables in Netlify dashboard
4. Deploy - works in demo mode without credentials, real mode with them

Live Application: https://gleaming-dango-a3fc18.netlify.app

• Demo Mode: Works immediately without setup
• Real Mode: Add your TiDB/OpenAI credentials for full functionality

🤖 Agentic Workflow Architecture

Step 1: Ingest & Index Data

• Real vehicle telemetry stored in live TiDB Serverless tables
• Actual vector embeddings generated using OpenAI text-embedding-3-small
• Production indexing with VECTOR(1536) columns and B-tree indexes

Step 2: Search Your Data

• Live vector similarity search using VEC_COSINE_DISTANCE in TiDB
• Real pattern recognition in historical data for predictive insights
• Production queries combining vector search with traditional SQL

Step 3: Chain LLM Calls

• Actual GPT-4 analyzes real search results and generates insights
• Live multi-step reasoning for complex logistics decisions
• Real context-aware recommendations based on TiDB similarity results

Step 4: Invoke External Tools

• Real automated vehicle dispatch with database updates
• Live integration with maintenance scheduling in TiDB
• Actual real-time notifications and alert systems

Step 5: Multi-Step Flow Completion

• Complete automation from real data ingestion to actual actions
• Live feedback loops for continuous learning with TiDB storage
• Real performance tracking and optimization with metrics

📊 Database Schema

Tables with Vector Support

-- Logistics events with vector embeddings
CREATE TABLE logistics_events (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  event_type VARCHAR(100) NOT NULL,
  vehicle_id VARCHAR(50) NOT NULL,
  location TEXT NOT NULL,
  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  metadata JSON,
  embedding VECTOR(1536) COMMENT "Vector embedding for semantic search",
  severity ENUM('low', 'medium', 'high', 'critical'),
  description TEXT,
  processed BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_vehicle_id (vehicle_id),
  INDEX idx_timestamp (timestamp),
  INDEX idx_severity (severity)
);

-- Vehicles with performance vectors
CREATE TABLE vehicles (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  vehicle_id VARCHAR(50) UNIQUE NOT NULL,
  vehicle_type ENUM('truck', 'drone', 'van', 'motorcycle') NOT NULL,
  name VARCHAR(200) NOT NULL,
  model VARCHAR(100),
  year INT,
  license_plate VARCHAR(20),
  current_location TEXT,
  battery_level INT DEFAULT 100,
  fuel_level INT DEFAULT 100,
  status ENUM('idle', 'active', 'charging', 'maintenance', 'offline') DEFAULT 'idle',
  driver_name VARCHAR(100),
  capacity VARCHAR(50),
  fuel_type ENUM('electric', 'diesel', 'gasoline', 'hybrid') DEFAULT 'electric',
  embedding VECTOR(1536) COMMENT "Vector embedding for vehicle characteristics",
  performance_metrics JSON,
  iot_data JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Route optimizations with vector search
CREATE TABLE route_optimizations (
  id INT AUTO_INCREMENT PRIMARY KEY,
  route_id VARCHAR(100) UNIQUE NOT NULL,
  origin TEXT NOT NULL,
  destination TEXT NOT NULL,
  waypoints JSON,
  optimization_score DECIMAL(5,2),
  embedding VECTOR(1536) COMMENT "Vector embedding for route characteristics",
  ai_recommendations TEXT
);

🎯 Demo Workflows

Predictive Maintenance

1. Real Input: Actual vehicle ID from TiDB database
2. Live Process: Real telemetry analysis, TiDB vector search, GPT-4 analysis
3. Database Output: Maintenance events stored in TiDB with vector indexing

Route Optimization

1. Real Input: Actual origin and destination coordinates
2. Live Process: TiDB vector search for similar routes, GPT-4 optimization
3. Database Output: Optimized routes stored with performance metrics

Emergency Response

1. Real Input: Actual emergency type and GPS coordinates
2. Live Process: TiDB similarity search, AI strategy generation
3. Database Output: Emergency events and vehicle dispatch records

🔄 Getting Started - Real Mode

Step 1: Quick Demo (No Setup Required)

npm run dev
# Visit http://localhost:5173
# Explore all features in demo mode

Step 2: Enable Real TiDB Integration

1. Get TiDB Credentials: Create account at tidbcloud.com
2. Add to .env: Copy your real connection details
3. Test Connection: Use "TiDB Setup" page to verify
4. Initialize Database: Click "Setup Database" to create tables

Step 3: Enable Real AI Features

1. Get OpenAI API Key: Visit platform.openai.com
2. Add to .env: Set VITE_OPENAI_API_KEY with real key
3. Test AI Workflows: Use "TiDB AI Agent" for real GPT-4 integration

Step 4: Experience Real Workflows

1. Add Real Vehicles: Use "Fleet Management" to add to TiDB
2. Run AI Agents: Execute real workflows in "TiDB AI Agent"
3. Monitor Live Data: Watch real-time updates in "Monitoring"
4. Explore Vector Search: Test semantic search with real embeddings

🏆 Hackathon Highlights

• Real TiDB Serverless: Live vector search with actual VEC_COSINE_DISTANCE queries
• Production AI Agents: Real multi-step workflows with GPT-4 and OpenAI embeddings
• Live Data Processing: Actual real-time ingestion and TiDB storage
• Enterprise Ready: Production architecture with error handling and monitoring
• Technical Innovation: Real vector search application in logistics domain

🎮 Demo vs Real Mode

Feature	Demo Mode	Real Mode
TiDB Connection	❌ Mock data	✅ Live TiDB Serverless
Vector Search	❌ Simulated	✅ Real VEC_COSINE_DISTANCE
AI Analysis	❌ Mock responses	✅ Actual GPT-4 API calls
Data Persistence	❌ Local state	✅ TiDB database storage
Real-time Updates	❌ Simulated	✅ Live database streaming
Embeddings	❌ Random vectors	✅ OpenAI text-embedding-3-small

🚀 Getting Started

1. Clone the repository

   git clone <repository-url>
   cd logiflow-ai

2. Install dependencies

   npm install

3. Set up environment variables

   • Copy .env.example to .env
   • Fill in your TiDB Serverless and OpenAI credentials

4. Initialize the database

   • Navigate to "TiDB Setup" in the sidebar
   • Test your connection and initialize tables
   • Verify real database connectivity

5. Explore the workflows

   • Navigate to "TiDB AI Agent" in the sidebar
   • Execute real AI workflows with live TiDB integration
   • Monitor real-time data in the "Monitoring" section

🔍 Verification Steps

Verify Real TiDB Integration:

1. Check "TiDB Setup" page shows "Connected" status
2. Add a vehicle in "Fleet Management" - should persist in database
3. Run vector search in "Vector Search Demo" - should show real similarity scores
4. Execute AI workflow in "TiDB AI Agent" - should show real execution steps

Verify Real AI Integration:

1. Check AI workflows show actual GPT-4 responses (not templates)
2. Vector embeddings should be real 1536-dimensional arrays
3. AI analysis should be contextual and relevant to input data
4. Confidence scores should reflect actual model performance

📱 Features Overview

Dashboard

• Real-time fleet monitoring
• AI-powered insights and recommendations
• Interactive maps with live vehicle tracking
• Performance metrics and analytics

Fleet Management

• Vehicle status monitoring
• Battery and maintenance tracking
• Route optimization
• Emergency response coordination

AI Automation

• Predictive maintenance scheduling
• Dynamic route optimization
• Inventory rebalancing
• Emergency response protocols

TiDB Integration

• Vector similarity search
• Real-time data ingestion
• JSON metadata storage
• Scalable serverless architecture

🔍 Technical Deep Dive

Vector Search Implementation

// Real embedding generation with OpenAI
const embedding = await aiService.generateEmbedding(vehicleDescription);

// Real TiDB vector search with live data
const similarVehicles = await connection.execute(`
  SELECT vehicle_id, performance_metrics,
         VEC_COSINE_DISTANCE(embedding, ?) as similarity_score
  FROM vehicles 
  WHERE embedding IS NOT NULL
  ORDER BY similarity_score ASC 
  LIMIT 5
`, [JSON.stringify(embedding)]);

Multi-Step Agent Workflow

// Step 1: Real data ingestion to TiDB
await insertVehicle(vehicleData);

// Step 2: Live vector search in TiDB
const similarVehicles = await vectorSearchSimilarVehicles(embedding);

// Step 3: Real GPT-4 analysis
const aiAnalysis = await aiService.analyzeWithGPT4(prompt);

// Step 4: Database persistence
await insertLogisticsEvent(maintenanceEvent);

// Step 5: Real workflow completion
return { success: true, recommendations, actions };

🚨 Important Notes

For Hackathon Judges:

• Real Implementation: This is NOT a mockup - it's a fully functional application
• Live Database: Actual TiDB Serverless integration with vector operations
• Production AI: Real OpenAI GPT-4 and embedding API integration
• Scalable Architecture: Enterprise-ready with proper error handling

For Developers:

• Environment Setup: Real credentials required for full functionality
• Fallback Mode: Intelligent demo mode when credentials not available
• Error Handling: Graceful degradation and comprehensive logging
• Performance: Optimized for production workloads

🤝 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

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• TiDB Cloud for providing serverless vector search capabilities
• OpenAI for GPT-4 and embedding models
• React and TypeScript communities for excellent tooling
• Tailwind CSS for beautiful, responsive design

📞 Support

For questions or support:

• Real Issues: Create an issue in this repository
• TiDB Setup: Check the "TiDB Setup" page in the application
• Live Workflows: Test real AI agents in "TiDB AI Agent" section
• Monitoring: Use "Real-Time Monitoring" for system health

---

Built with ❤️ for the TiDB 2025 AI-Agentic Hackathon

Real implementation showcasing TiDB Serverless vector search with production-ready multi-step AI agents.