mouse1999/Telecomm-Vendor-AI

An AI-powered Telegram bot for buying mobile data bundles in Nigeria. Users chat naturally, verify via PIN, and purchase MTN/Airtel/Glo/9mobile data instantly. # DataBot NG > An AI-powered Telegram bot for buying mobile data bundles in Nigeria. Users chat naturally, verify via PIN, and purchase MTN/Airtel/Glo/9mobile data instantly. Built with Java 21, Spring Modulith, Spring AI, Kafka, PostgreSQL + PGVector, and Redis. --- ## Table of Contents - Overview - Features - Architecture - Tech Stack - Project Structure - Prerequisites - Getting Started - Configuration - Database Migrations - Running the Application - Running Tests - Observability - Kafka Topics - API — AI Tool Methods - Nigerian Phone Prefix Map - Non-Functional Requirements - Contributing --- ## Overview DataBot NG lets Nigerian users buy mobile data directly inside Telegram using plain language. A user types *"Send 2GB MTN to 08012345678"* — the AI parses the intent, validates the phone number against its network, checks the wallet balance, debits atomically, and delivers via the vendor API — all within a single conversation thread. The system is built on three guarantees: - **No lost transactions.** Every purchase is written to a Transactional Outbox before Kafka is notified. If Kafka goes down mid-purchase, the event is retried automatically when it recovers. - **No double charges.** Wallet debits use optimistic locking (`@Version`). A duplicate request is rejected at the database level. - **No silent failures.** Every failed delivery triggers a refund, a Telegram notification, and a dead-letter entry that alerts the admin. --- ## Features | # | Feature | Description | |---|---------|-------------| | ✅ | PIN-gated sessions | 6-digit PIN verified with BCrypt. Locked for 15 min after 3 failures. Session stored in Redis with 15-min sliding TTL. | | ✅ | Natural language purchase | Spring AI parses free-text messages and dispatches to typed Java `@Tool` methods. | | ✅ | RAG price lookup | Price lists and FAQs are embedded with OpenAI `text-embedding-3-small` and stored in PGVector. Similarity search answers plan queries in > @Entity — PIN log …