Logistics AI Chatbot

A sophisticated AI-powered logistics chatbot built with .NET 8 and Clean Architecture, demonstrating enterprise-grade AI agent capabilities for delivery and shipping management.

🏗️ Architecture

This project follows Clean Architecture principles with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────┐
│                      PRESENTATION LAYER                         │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Telegram Bot (Program.cs)                   │   │
│  │        Handles user interactions and commands            │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     INFRASTRUCTURE LAYER                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   EF Core    │  │  Semantic    │  │   Telegram.Bot       │  │
│  │   SQLite     │  │   Kernel     │  │   Integration        │  │
│  │  DbContext   │  │   OpenAI     │  │   Service            │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      APPLICATION LAYER                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │    DTOs      │  │   Services   │  │   Semantic Kernel    │  │
│  │  (Data       │  │  (Order,     │  │     Plugins          │  │
│  │  Transfer)   │  │   Cost,      │  │   (Logistics,        │  │
│  │              │  │   AI Agent)  │  │    FAQ)              │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        DOMAIN LAYER                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   Entities   │  │    Value     │  │    Interfaces        │  │
│  │  (Order,     │  │   Objects    │  │   (IOrderRepo,       │  │
│  │   Client,    │  │  (Dimensions,│  │    IClientRepo,      │  │
│  │   Status)    │  │   Address)   │  │    IUnitOfWork)      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Dependency Flow

Presentation → Infrastructure → Application → Domain
     ↓              ↓               ↓            ↓
  Bot UI        EF Core +       Business      Core
              Semantic Kernel     Logic      Entities

Key Principle: Dependencies flow inward. The Domain layer has no external dependencies.

🚀 Features

1. Create Delivery Order

• AI extracts shipment details from natural language
• Supports origin/destination cities, weight, dimensions, cargo type
• Automatic cost calculation and order number generation
• Persisted to SQLite database

2. Delivery Cost Calculator

• AI-powered parsing of casual cost queries
• Distance-based calculation (using Haversine formula)
• Weight and volume coefficients
• Cargo type multipliers (Documents, Fragile, Oversized, Standard)
• Detailed cost breakdown

3. Order Status Tracking

• Query orders by order number
• Full status history with timestamps
• Estimated delivery date

4. FAQ Consultant

• Semantic Kernel powered Q&A
• Topics: shipping times, international delivery, packaging, prohibited items, insurance, etc.
• Graceful fallback to human manager suggestion

5. Smart Query Filtering

• Distinguishes business queries from casual chat
• Polite responses to non-business messages
• Reduces manager workload (key client requirement!)

📋 Tech Stack

Technology	Version	Purpose
.NET	8.0	Framework
Semantic Kernel	1.70.0	AI Orchestration
OpenAI API	GPT-4o-mini	LLM Backend
Telegram.Bot	22.8.1	Telegram Integration
Entity Framework Core	8.0.11	ORM
SQLite	-	Database
Serilog	8.0.0	Logging
xUnit + Moq	Latest	Testing

🛠️ Setup Instructions

Prerequisites

• .NET 8.0 SDK
• OpenAI API Key
• Telegram Bot Token (from @BotFather)

Local Development

1. Clone the repository

   git clone <repository-url>
   cd LogisticsChatbot

2. Configure API Keys

   Edit src/Presentation/appsettings.Development.json:

   {
     "OpenAI": {
       "ApiKey": "sk-your-openai-api-key-here",
       "ModelId": "gpt-4o-mini"
     },
     "TelegramBot": {
       "BotToken": "your-telegram-bot-token-here"
     }
   }

3. Restore packages and build

   dotnet restore
   dotnet build

4. Run the application

   cd src/Presentation
   dotnet run

5. Run tests

   dotnet test

Docker Deployment

1. Create environment file

   cp .env.example .env

   Edit .env with your API keys:

   OPENAI_API_KEY=sk-your-key
   TELEGRAM_BOT_TOKEN=your-token
   

2. Build and run with Docker Compose

   docker-compose up -d --build

3. View logs

   docker-compose logs -f

💬 Bot Commands

Command	Description
/start	Welcome message with introduction
/new_order	Start creating a new delivery order
/calculate	Calculate delivery cost
/status <order>	Check order status
/myorders	View all your orders
/help	Show available commands

📝 Example Conversations

Use Case 1: Create Delivery Order

User: I need to ship 15kg of fragile electronics from Moscow to Berlin

Bot: ✅ Order created successfully!

📦 Order Number: ORD-20240115-4521
📍 Route: Moscow → Berlin
⚖️ Weight: 15 kg
📋 Cargo Type: Fragile
💰 Total Cost: $287.50
📅 Estimated Delivery: January 22, 2024

Save your order number to track your shipment!

Use Case 2: Calculate Delivery Cost

User: How much to send 5kg of documents from London to Paris?

Bot: Cost Breakdown:
─────────────────────────────
Base cost: $10.00
Distance (London → Paris): $173.51
Weight (5 kg × $5/kg): $25.00
Cargo type multiplier (Documents): ×0.80
Volume multiplier: ×1.00
─────────────────────────────
TOTAL: $166.81

Use Case 3: Check Order Status

User: /status ORD-20240115-4521

Bot: 📦 Order Status: ORD-20240115-4521
─────────────────────────────
Current Status: Package is in transit
Estimated Delivery: January 22, 2024

📜 Status History:
  • Jan 15, 10:30 - Order created
  • Jan 16, 08:00 - Package picked up
  • Jan 17, 14:25 - In transit

Use Case 4: FAQ Query

User: What items can't I ship internationally?

Bot: ⛔ Prohibited Items:
• Explosives and flammable materials
• Illegal drugs and narcotics
• Weapons and ammunition
• Live animals
• Perishable food items
• Hazardous chemicals
• Counterfeit goods

Contact our support for specific item inquiries.

Use Case 5: Non-Business Query Filtering

User: Hey, what's the weather like today?

Bot: Hello! I appreciate the friendly chat! 😊
While I can't help with weather forecasts, I'm here to assist
you with all your shipping needs. Would you like to:
• Ship a package?
• Calculate delivery costs?
• Track an existing order?

Just let me know how I can help!

🧪 Testing

The project includes comprehensive unit tests for the Application layer:

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test class
dotnet test --filter "FullyQualifiedName~CostCalculatorServiceTests"

Test Coverage

• CostCalculatorServiceTests - Cost calculation logic
• OrderServiceTests - Order CRUD operations
• LogisticsPluginTests - Semantic Kernel plugin functions
• FaqPluginTests - FAQ knowledge base

📁 Project Structure

LogisticsChatbot/
├── src/
│   ├── Domain/                    # Core business entities
│   │   ├── Entities/
│   │   │   ├── Client.cs
│   │   │   ├── Order.cs
│   │   │   └── StatusHistory.cs
│   │   ├── Enums/
│   │   │   ├── CargoType.cs
│   │   │   └── OrderStatus.cs
│   │   ├── Interfaces/
│   │   │   ├── IClientRepository.cs
│   │   │   ├── IOrderRepository.cs
│   │   │   └── IUnitOfWork.cs
│   │   └── ValueObjects/
│   │       ├── Address.cs
│   │       └── Dimensions.cs
│   │
│   ├── Application/               # Business logic & AI
│   │   ├── DTOs/
│   │   ├── Interfaces/
│   │   ├── Plugins/              # Semantic Kernel plugins
│   │   │   ├── LogisticsPlugin.cs
│   │   │   └── FaqPlugin.cs
│   │   ├── Services/
│   │   │   ├── AIAgentService.cs
│   │   │   ├── CostCalculatorService.cs
│   │   │   └── OrderService.cs
│   │   └── DependencyInjection.cs
│   │
│   ├── Infrastructure/            # External concerns
│   │   ├── AI/
│   │   │   ├── OpenAISettings.cs
│   │   │   └── SemanticKernelConfiguration.cs
│   │   ├── Data/
│   │   │   ├── Configurations/
│   │   │   ├── Repositories/
│   │   │   ├── LogisticsDbContext.cs
│   │   │   └── UnitOfWork.cs
│   │   ├── Telegram/
│   │   │   ├── TelegramBotService.cs
│   │   │   └── TelegramBotSettings.cs
│   │   └── DependencyInjection.cs
│   │
│   └── Presentation/              # Entry point
│       ├── Program.cs
│       ├── appsettings.json
│       └── appsettings.Development.json
│
├── tests/
│   └── Application.Tests/         # Unit tests
│
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

🔧 Configuration

Environment Variables

Variable	Description	Required
OPENAI_API_KEY	OpenAI API key	Yes
OPENAI_MODEL_ID	Model ID (default: gpt-4o-mini)	No
TELEGRAM_BOT_TOKEN	Telegram bot token	Yes
ConnectionStrings__DefaultConnection	SQLite connection string	No

Supported OpenAI Models

• gpt-4o-mini (default, recommended for cost-efficiency)
• gpt-4o (higher quality, higher cost)
• gpt-4-turbo
• gpt-3.5-turbo

🔒 Security Notes

• Never commit API keys to version control
• Use environment variables in production
• The .gitignore excludes sensitive files
• SQLite database files are excluded from git

📄 License

This project is created for portfolio demonstration purposes.

🤝 Contributing

This is a portfolio project. Feel free to fork and adapt for your needs.

---

Built with ❤️ using .NET 8, Semantic Kernel, and Clean Architecture