History

This project was initially developed as a modern monolith application for the OGON 2025 hackathon. The codebase includes:

Existing Code Used:

• Turborepo Configuration: Standard monorepo setup with Turborepo 2.5.4
• Fastify Backend Structure: RESTful API with OpenAPI documentation
• LangChain Integration: AI-powered chat functionality using LangChain and LangGraph
• React 19 Frontend: Modern React setup with Vite 6.3 and TailwindCSS v4
• CI/CD Pipeline: GitHub Actions workflows for testing, building, and deployment
• Docker Configuration: Multi-stage Docker builds for production deployment

Original Components:

The project structure follows industry best practices for monorepo applications:

• /apps/backend/ - Fastify server with AI integration
• /apps/frontend/ - React SPA with modern tooling
• /packages/ - Shared packages placeholder for future extensions
• Comprehensive testing setup with Vitest
• ESLint 9 + Prettier configuration for code quality
• PostgreSQL database integration

All code in this initial commit represents the starting point for the hackathon submission.

OGON 2025

A modern AI-powered SQL generation platform built as a monolith application featuring natural language to SQL conversion, real-time agent visualization, and multi-database support.

Overview

OGON 2025 is an enterprise-grade application that enables users to query databases using natural language. It leverages OpenAI's GPT-4 and LangChain/LangGraph for intelligent query generation while maintaining strong security controls and real-time feedback through WebSocket connections.

Key Features

• Natural Language to SQL: Convert plain English (and other languages) queries to SQL
• Multi-Database Support: Query across 5 different schemas (main, wallet, PAM, games, KYC)
• Real-time Agent Visualization: See the AI workflow in action with live status updates
• Secure Query Execution: Comprehensive SQL validation and injection prevention
• Vector Search: Semantic search using embeddings for better query understanding
• Schema Enrichment: LLM-powered metadata generation for improved accuracy
• WebSocket Communication: Real-time updates and agent metrics
• Multi-language Support: Russian, English, Spanish, and French interfaces

Technology Stack

Backend

• Framework: Fastify 5.3 with TypeScript
• AI/ML: LangChain 0.3.x, LangGraph for agent workflows, OpenAI GPT-4
• Database: PostgreSQL 16 with Prisma ORM (multi-schema setup)
• Vector Database: Supabase with pgvector for embeddings
• Real-time: WebSocket server on port 3001
• Documentation: Auto-generated Swagger/OpenAPI docs

Frontend

• Framework: React 19 with TypeScript
• Build Tool: Vite 6.3 for fast development
• UI Components: Radix UI primitives with shadcn/ui patterns
• Styling: TailwindCSS v4 with PostCSS plugin
• State Management: TanStack Query for server state, Zustand for client state
• Data Visualization: Recharts for query results
• Routing: React Router v7

Infrastructure

• Monorepo: Turborepo with Yarn workspaces
• Containerization: Docker with multi-stage builds
• Deployment: Dokploy platform with automatic deployments
• CI/CD: GitHub Actions for validation (optional)

Project Structure

ogon2025/
├── apps/
│   ├── backend/              # Fastify API server
│   │   ├── src/
│   │   │   ├── agents/       # LangGraph AI agents
│   │   │   ├── routes/       # API endpoints
│   │   │   ├── services/     # Business logic
│   │   │   ├── db/          # Database schemas
│   │   │   └── utils/       # Utility functions
│   │   ├── prisma/          # Database schemas (5 databases)
│   │   └── scripts/         # Development utilities
│   ├── frontend/            # React SPA
│   │   ├── src/
│   │   │   ├── components/  # React components
│   │   │   ├── services/    # API clients
│   │   │   └── styles/      # Global styles
│   │   └── nginx/           # Production proxy config
│   └── docs/                # Docusaurus documentation
├── docs/                    # Project documentation
├── docker-compose.yml       # Production config
├── docker-compose.local.yml # Development config
├── turbo.json              # Turborepo configuration
└── package.json            # Root workspace config

Quick Start (Docker - Recommended)

# 1. Clone and setup
git clone https://github.com/yourusername/ogon2025.git
cd ogon2025

# 2. Configure environment
cp .env.example apps/backend/.env.local
# Edit apps/backend/.env.local with your OpenAI API key

# 3. Start all services
./start-local.sh

# 4. Initialize database (first time only)
cd apps/backend && ./scripts/local-dev.sh init

# 5. Access application
# Frontend: http://localhost:8080
# Backend API: http://localhost:3000
# API Documentation: http://localhost:3000/documentation
# Project Docs: http://localhost:3001

Installation

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for local development)
• Yarn 4.1.1 (via Corepack)
• OpenAI API key

Manual Development Setup

# Install dependencies
yarn install

# Set up environment
cp .env.example apps/backend/.env.local
# Configure your OpenAI API key and database settings

# Generate Prisma clients
cd apps/backend && yarn prisma:generate

# Start development servers
yarn dev

Configuration

Required Environment Variables

Backend (apps/backend/.env.local)

# OpenAI Configuration (Required)
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_TEMPERATURE=0.7

# Database URLs (Required)
DATABASE_URL=postgresql://ogon2025:changeme@postgres:5432/ogon2025
WALLET_DATABASE_URL=postgresql://wallet_user:wallet_pass@postgres:5432/wallet_db
PAM_DATABASE_URL=postgresql://pam_user:pam_pass@postgres:5432/pam_db
GAMES_DATABASE_URL=postgresql://games_user:games_pass@postgres:5432/games_db
KYC_DATABASE_URL=postgresql://kyc_user:kyc_pass@postgres:5432/kyc_db

# WebSocket Configuration
WEBSOCKET_PORT=3001
WEBSOCKET_PATH=/ws

# Supabase Vector Database (Optional)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key

# Application Settings
PORT=3000
NODE_ENV=development
LOG_LEVEL=debug
CORS_ORIGIN=http://localhost:8080

Frontend Environment Files

Frontend configuration uses environment-specific files in apps/frontend/:

# .env.development
VITE_API_URL=https://dev.api.nltosql.com

# .env.production
VITE_API_URL=https://api.nltosql.com

# .env.local (for local development)
VITE_API_URL=/api

Features

AI Agent Workflow

The application uses a sophisticated LangGraph-based agent system:

1. Security Agent: Validates input for threats and malicious content
2. SQL Generator: Converts natural language to SQL using GPT-4
3. Query Executor: Safely executes queries with timeout protection
4. Result Evaluator: Formats and validates query results
5. Response Agent: Generates user-friendly responses

Multi-Database Architecture

• Main: Chat sessions, messages, system configuration
• Wallet: Digital wallet transactions and bonuses
• PAM: Privileged Access Management for players
• Games: Gaming platform data and analytics
• KYC: Know Your Customer verification data

Security Features

• SQL injection prevention via Prisma
• Query validation (SELECT/WITH only)
• Automatic LIMIT injection
• Query timeout protection (30s default)
• Input sanitization and threat detection
• Role assertion prevention
• CORS configuration

Vector Search Capabilities

• Schema embeddings for semantic search
• Query expansion with synonyms
• Cosine similarity matching
• LLM-enhanced metadata
• Automatic schema discovery

API Documentation

Main Endpoints

Chat Endpoint

POST /api/agent/chat
Content-Type: application/json

{
  "message": "Show me total sales by month",
  "sessionId": "optional-session-id"
}

Response:
{
  "response": "Here are the total sales by month...",
  "sessionId": "generated-or-provided-session-id",
  "metadata": {
    "executionTime": 1234,
    "rowsReturned": 12
  }
}

Health Checks

GET /api/health
GET /api/health/db

WebSocket Connection

ws://localhost:3001/ws

// Message types:
// - agent_update: Real-time agent status
// - response: Query results
// - error: Error messages
// - connected/disconnected: Connection status

Development

Commands

# Development
yarn dev              # Start all services in dev mode
yarn dev:backend      # Backend only
yarn dev:frontend     # Frontend only

# Building
yarn build            # Build all applications
yarn build:backend    # Backend only
yarn build:frontend   # Frontend only

# Testing
yarn test             # Run all tests
yarn test:api         # API integration tests
yarn test:unit        # Unit tests only

# Database Management
cd apps/backend
yarn prisma:generate  # Generate Prisma clients
yarn prisma:push      # Push schema to databases
yarn prisma:migrate   # Run migrations
yarn prisma:studio    # Open Prisma Studio (5 instances)

# Code Quality
yarn lint             # Run ESLint
yarn typecheck        # TypeScript type checking
yarn format           # Format code with Prettier

Docker Development

# Start with hot reload
docker compose -f docker-compose.local.yml up -d

# View logs
docker logs -f ogon2025-backend-1
docker logs -f ogon2025-frontend-1

# Access containers
docker exec -it ogon2025-backend-1 sh
docker exec -it ogon2025-frontend-1 sh

# Reset environment
docker compose -f docker-compose.local.yml down -v

Testing

The project includes comprehensive test suites:

• Unit Tests: Service logic, utilities, serialization
• Integration Tests: Database operations, API endpoints
• Security Tests: SQL injection, input validation
• API Tests: Playwright-based endpoint testing

Run tests with:

yarn test              # All tests
yarn test:unit         # Unit tests only
yarn test:integration  # Integration tests
yarn test:api          # API tests

Deployment

Environments

• Production: https://nltosql.com (main branch)
• Development: https://dev.nltosql.com (develop branch)
• Local: http://localhost:8080

Deployment Platform

The application is deployed using Dokploy with automatic deployments on push to respective branches.

Production Configuration

# Required environment variables
DATABASE_URL=postgresql://...
OPENAI_API_KEY=sk-...
CORS_ORIGIN=https://nltosql.com
NODE_ENV=production
LOG_LEVEL=info

# Frontend build configuration
VITE_API_URL=https://api.nltosql.com

Troubleshooting

Common Issues

1. OpenAI API Errors

   # Check API key
   docker exec ogon2025-backend-1 printenv | grep OPENAI

2. Database Connection Issues

   # Verify PostgreSQL is running
   docker ps | grep postgres
   
   # Test connection
   docker exec -it ogon2025-postgres-1 psql -U ogon2025

3. WebSocket Connection Failed

   • Check port 3001 is accessible
   • Verify CORS settings match frontend URL

4. Frontend Proxy Issues

   • Ensure nginx configuration is correct
   • Check VITE_API_URL environment variable

Debug Commands

# View real-time logs
docker compose -f docker-compose.local.yml logs -f

# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Inspect environment
docker exec ogon2025-backend-1 env | sort

# Test API directly
curl -X POST http://localhost:3000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "test", "sessionId": "test-123"}'

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Set up local development environment
4. Make your changes
5. Run quality checks: yarn lint && yarn typecheck && yarn test
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Use ES modules syntax
• Maintain test coverage
• Document API changes
• Follow existing code patterns

License

MIT - see LICENSE for details.

Support

For issues and feature requests, please use the GitHub issue tracker.

For questions about deployment or infrastructure, refer to the documentation directory.