OperasyonAI

OperasyonAI, KOBI'ler icin tasarlanmis AI destekli operasyon kontrol merkezidir. Siparis takibi, stok riski, kargo gecikmeleri, tedarik maili, musteri sorulari ve gunluk operasyon brifingi tek bir backend uzerinden birlikte calisir.

Projenin ana fikri klasik bir dashboard'u aksiyon alabilen ajan katmaniyla birlestirmektir. Frontend sadece veriyi gosterir ve kullanici aksiyonlarini backend'e iletir; cevaplar, ozetler, tahminler ve bildirimler backend ajanlari tarafindan uretilir.

Ne Yapar?

• Musteri web chat ve Telegram mesajlarini cevaplar.
• Siparis, urun, stok ve kargo bilgilerini backend verisinden sorgular.
• Kritik stoktaki urunler icin tedarik onerisi ve mail taslagi uretir.
• Geciken kargolari bulur ve musteriyi Telegram uzerinden bilgilendirir.
• Gunluk operasyon brifingi ve oncelikli gorev listesi hazirlar.
• Satis hareketlerinden basit talep tahmini ve stok riski cikarir.

Ajanlar

Ajan	Gorev	Nerede Calisir?
Musteri Ajani	Web chat ve Telegram'dan gelen siparis, urun, stok ve kargo sorularini cevaplar	backend/app/agents/orchestrator.py
Siparis & Stok Ajani	Kritik stoklari ve siparis operasyonunu takip eder	backend/app/agents/operations.py
Kargo Ajani	Geciken kargolari tespit eder, bildirim metnini hazirlar	backend/app/agents/operations.py
Tedarik Ajani	Stok verisine gore tedarik maili taslagi uretir	backend/app/agents/operations.py
Brifing & Analitik Ajani	Gunluk ozet, gorevler, satis trendi ve tahmin uretir	backend/app/agents/operations.py

Mimari

flowchart LR
    UI[Next.js Frontend] --> API[FastAPI Backend]
    TG[Telegram Webhook] --> API

    API --> ORCH[Musteri Agent Orchestrator]
    API --> OPS[Operation Agents]

    ORCH --> TOOLS[Tool Layer]
    OPS --> TOOLS

    TOOLS --> DB[(SQLite Demo DB)]
    TOOLS --> CARGO[Cargo Mock API]
    TOOLS --> MAIL[Brevo / SMTP]

    ORCH --> LLM[Gemini / Groq]
    OPS --> LLM

Loading

Frontend tarafinda hazir cevap yoktur. Chat widget mesajlari /api/agent/chat endpoint'ine gonderir; Telegram ise /api/telegram/webhook endpoint'iyle ayni backend ajan akisini kullanir.

Ornek Akislar

Musteri Sorusu

sequenceDiagram
    participant User as Kullanici
    participant UI as Frontend veya Telegram
    participant API as FastAPI
    participant Agent as Musteri Ajani
    participant Tools as Backend Tools
    participant DB as SQLite

    User->>UI: "142 numarali siparisim nerede?"
    UI->>API: POST /api/agent/chat veya /api/telegram/webhook
    API->>Agent: process_message()
    Agent->>Tools: get_order_status / get_cargo_status
    Tools->>DB: Siparis ve kargo kayitlari
    DB-->>Tools: Structured data
    Tools-->>Agent: Tool sonucu
    Agent-->>API: Turkce cevap
    API-->>UI: Cevap

Loading

Tedarik Maili

sequenceDiagram
    participant UI as Stok Ekrani
    participant API as FastAPI
    participant Agent as Tedarik Ajani
    participant LLM as Gemini/Groq
    participant Mail as Brevo/SMTP

    UI->>API: POST /api/stock/draft-supplier-email/{product_id}
    API->>Agent: run_supplier_agent_draft()
    Agent->>LLM: Stok ve satis verisiyle mail taslagi
    LLM-->>Agent: Mail govdesi
    Agent-->>API: subject, body, suggested_order_qty
    UI->>API: POST /api/stock/send-supplier-email/{product_id}
    API->>Mail: send_email()

Loading

Teknoloji

Katman	Teknoloji
Frontend	Next.js 14, React, TanStack Query, Tailwind, Recharts
Backend	FastAPI, SQLAlchemy, APScheduler
AI	Gemini, Groq, LangGraph/LangChain
Entegrasyon	Telegram Bot API webhook, Brevo API, SMTP
Veri	SQLite demo verisi
Kargo	Mock cargo API

Servisler

Servis	Aciklama
backend	API gateway, ajan katmani, DB seed, Telegram webhook, email/kargo entegrasyonu
frontend	Operasyon dashboard'u, chat widget, stok/kargo/analitik ekranlari
cargo-mock	Demo kargo takip servisi

Veri

Backend ilk acilista demo veri uretir:

• 200 siparis
• Musteri ve urun katalogu
• Kritik stok senaryolari
• Kargo eventleri ve gecikmeler
• Son 90 gunluk satis hareketleri
• Analitik grafik ve tahmin icin trend verisi

Bu sayede proje bos kurulumda da uc uca denenebilir.

Hızlı Baslangic

cp .env.example .env
docker compose up --build
docker compose --profile extras up --build frontend

Adresler:

• Backend: http://localhost:8000
• API docs: http://localhost:8000/docs
• Frontend: http://localhost:3000
• Cargo mock: http://localhost:9000

Ortam Degiskenleri

Temel degiskenler .env.example icinde bulunur.

Degisken	Aciklama
LLM_PROVIDER	gemini veya groq
GEMINI_API_KEY / GROQ_API_KEY	AI cevaplari ve ajan uretimleri
TELEGRAM_BOT_TOKEN	Telegram webhook cevaplari
TELEGRAM_WEBHOOK_SECRET	Telegram webhook dogrulama secret'i
EMAIL_PROVIDER	brevo veya smtp
CARGO_API_URL	Kargo takip servisi URL'i
DATABASE_URL	SQLite baglanti adresi

Onemli Endpointler

Endpoint	Islev
POST /api/agent/chat	Web chat ajan girisi
POST /api/telegram/webhook	Telegram mesaj girisi
GET /api/dashboard/summary	Operasyon metrikleri
GET /api/briefing/today	Gunluk operasyon brifingi
GET /api/stock/alerts	Kritik stok listesi
POST /api/stock/draft-supplier-email/{id}	Tedarik maili taslagi
POST /api/stock/send-supplier-email/{id}	Tedarik maili gonderimi
GET /api/cargo/issues	Geciken kargolar
POST /api/cargo/issues/{id}/notify	Musteriye Telegram bildirimi
GET /api/analytics/forecast	Satis trendi ve stok riski tahmini

Proje Yapisi

backend/
  app/
    agents/        # Musteri orchestrator ve operasyon ajanlari
    api/           # FastAPI route'lari
    services/      # LLM, email, Telegram servisleri
    db/            # DB session ve seed
frontend/
  src/             # Next.js dashboard ve chat arayuzu
cargo-mock/        # Demo kargo API

Guvenlik Notu

Gercek API key, bot token ve SMTP sifreleri repo'ya commit edilmemelidir. .env.example sadece bos sablon olarak tutulur.