Project Hack - AI Chat & Workflow Backend

A comprehensive AI-powered chat and workflow backend system with multiple integration options including Flutter frontend, n8n workflows, and direct API access.

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Git
• (Optional) Flutter for mobile app integration
• (Optional) n8n for workflow automation

1. Clone and Setup

git clone https://github.com/juinc/project-hack.git
cd project-hack

2. Install Dependencies

pip install -r requirements_api.txt

3. Environment Configuration

# Run the setup script to create .env file
python setup.py

Or manually create a .env file with:

LLM_KEY=your_openrouter_api_key_here
LLM_MODEL=openai/gpt-3.5-turbo

4. Start the Backend

# Start the main API server
python api.py

# Or start the workflow backend
python workflow_backend.py

# Or start the local backend
python local_backend.py

📁 Project Structure

Core Backend Files

• api.py - Main Flask API server with OpenRouter integration
• workflow_backend.py - Backend optimized for n8n workflow integration
• local_backend.py - Local development backend
• chat.py - Simple command-line chat interface

Integration Files

• n8n_api.py - n8n workflow integration
• pdf_learning_backend.py - PDF document processing backend
• test_flutter_integration.py - Flutter integration testing

Configuration & Setup

• setup.py - Automated environment setup
• requirements_api.txt - Python dependencies
• env_example.txt - Environment variables template

Testing & Debugging

• test_*.py - Various test files for different components
• debug_api.py - API debugging utilities
• quick_test.py - Quick functionality tests

🔧 Available Services

1. Main API Server (api.py)

Port: 5000 (default) Endpoints:

• POST /chat - Send message and get AI response
• GET /health - Health check
• POST /upload - File upload support

# Start main API
python api.py

2. Workflow Backend (workflow_backend.py)

Port: 5001 (default) Features:

• Optimized for n8n integration
• Request/response logging
• Session management

# Start workflow backend
python workflow_backend.py

3. Local Development Backend (local_backend.py)

Port: 5002 (default) Features:

• Local development server
• Enhanced debugging
• CORS enabled

# Start local backend
python local_backend.py

4. Command Line Chat (chat.py)

Interactive command-line chat interface:

# Start CLI chat
python chat.py

🔌 Integration Options

Flutter Mobile App

The project includes Flutter integration for mobile apps:

• See FLUTTER_INTEGRATION_GUIDE.md for detailed setup
• API service handles all backend communication
• Real-time chat functionality

n8n Workflow Integration

For workflow automation:

• Use workflow_backend.py for n8n integration
• Configure webhooks in n8n to point to your backend
• Supports complex workflow scenarios

Direct API Usage

Simple HTTP requests to the API:

# Test the API
curl -X POST http://localhost:5000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, AI!"}'

🧪 Testing

Run All Tests

# Test API functionality
python test_api.py

# Test Flutter integration
python test_flutter_integration.py

# Test n8n integration
python test_n8n.py

# Test PDF learning
python test_pdf_learning.py

# Quick functionality test
python quick_test.py

Debug Mode

# Run with debug information
python debug_api.py

📱 Flutter Integration

Setup Flutter Frontend

1. Navigate to the Flutter project directory
2. Run flutter pub get
3. Update API endpoints in lib/services/api_service.dart
4. Run flutter run

API Service Configuration

The Flutter app includes a complete API service with:

• Chat functionality
• File upload support
• Health check monitoring
• Error handling

🔄 n8n Workflow Integration

Setup n8n Webhooks

1. Start the workflow backend: python workflow_backend.py
2. Configure n8n webhook nodes to point to your backend
3. Use the provided workflow templates

Workflow Features

• Request/response logging
• Session management
• Error handling
• Custom system prompts

🐛 Troubleshooting

Common Issues

1. API Key Not Found

   • Check your .env file
   • Ensure API_KEY is set correctly

2. Port Already in Use

   • Change port in the respective Python files
   • Or kill existing processes using the port

3. CORS Issues

   • All backends have CORS enabled
   • Check your frontend URL configuration

4. Model Not Available

   • Check model availability
   • Try a different model in your .env file

Debug Commands

# Check API health
curl http://localhost:5000/health

# Test with verbose output
python debug_api.py

# Check environment variables
python test_key.py

📊 Monitoring & Logs

Health Checks

• GET /health - Basic health check
• GET /status - Detailed status information
• GET /logs - Recent request logs

Logging

All backends include comprehensive logging:

• Request/response logging
• Error tracking
• Performance monitoring

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is open source and available under the MIT License.

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review the test files for examples
3. Check the Flutter integration guide
4. Open an issue on GitHub

---

Happy Hacking! 🚀