How omerbakis/smsai works
Proje tipi ve amacı (README + file tree’dan çıkarım)
Bu proje bir Python tabanlı tek-servis (monolith) web uygulaması prototipi. Amaç: SMS akışı yerine hızlı MVP olarak web chat UI üzerinden gelen mesajları alıp:
Kullanım kayıtlarını tutup GET /api/usage ile raporlamak.
Kalıcı DB / gerçek LLM provider / auth / rate-limit yok; bunlar “external/placeholder” olarak diyagrama dahil edilmeli (gelecek ekler).
Dosya yapısı → mimari bileşenleri çıkarma
File tree ana sinyaller:
• app/main.py → Uygulama entrypoint’i; HTTP server’ı ayağa kaldırır (muhtemelen FastAPI/Flask tarzı).
• app/router.py → Multi-model yönlendirme mantığı (fast/multilingual/quality).
• app/classifier.py → Dil/intent/complexity sınıflandırma.
• app/budget.py → Token limitleri + tahmini maliyet + global/user budget kontrolü.
• app/storage.py → Kullanım kayıtları / state saklama (prototipte in-memory veya dosya bazlı olabilir).
• app/__init__.py → paket başlangıcı.
• static/index.html → Tek sayfa chat UI (frontend).
• tests/test_api.py, tests/test_classifier.py → API ve sınıflandırma için testler.
• .env.example → Konfigürasyon/env var (model isimleri, limitler, vs.).
Buna göre sistem; “UI + API + domain services” şeklinde, tek process içinde modüllere ayrılmış.
Diyagramı doğru çizmek için: 3 katmanlı yaklaşım önerisi
Principal-level doğruluk için tek diyagram yerine 3 görünüm üretin. Aynı bileşen isimlerini tutarlı kullanın.
Context (C4 Level 1) – Sistem sınırları
Amaç: “Bu sistem kimlerle konuşuyor?”
Bileşenler:
• User (Web Chat Kullanıcısı)
• Web Browser (UI)
• SMSAI Prototype Web Service (Python App)
• (Future) LLM Providers (OpenAI/Anthropic vb. placeholder)
• (Future) Persistent Storage / DB (placeholder)
Oklar:
• User → Browser → GET / (static UI)
• Browser → Service: POST /api/chat, GET /api/usage
• Service → (Future) LLM Providers: model inference çağrısı
• Service → (Future) DB: usage/budget persistence
Bu seviyede “prototipte hepsi aynı process içinde” notunu ekleyin.
Container (C4 Level 2) – Deploy edilebilir parçalar
Amaç: “Çalışan parçalar neler?”
Bu projede container sayısı az:
Python Web App (single process)
• Serves static: static/index.html
• Serves API: /api/chat, /api/usage
Browser UI (static HTML/JS)
• Chat UI; API’ye istek atar.
(Opsiyonel ama faydalı)
Config (.env)
• “Runtime config” kutusu; budget limitleri, model seçimi vb.
Oklar:
• Browser UI → Python Web App (HTTP)
• Python Web App → (Future) LLM providers (HTTP)
• Python Web App → (Currently) In-memory storage (app/storage.py)
Component (C4 Level 3) – app/ içi bileşen diyagramı (asıl kritik kısım)
Amaç: Kod yapısını en doğru temsil eden diyagram.
app/ altındaki modülleri “components” olarak çizip, request flow’u oklarla gösterin.
Önerilen component kutuları ve sorumlulukları:
API Layer / HTTP Handlers
• Kaynak: app/main.py (ve varsa routing setupları), app/router.py (adı router ama burada “model router”; HTTP router ayrı olabilir)
• Endpointler:
• POST /api/chat
• GET /api/usage
• GET / static
• Görev: request parse, response format.
Classifier Service
• Kaynak: app/classifier.py
• Çıktılar:
• language
• intent/domain
• complexity (low/medium/high)
Budget / Token Manager
• Kaynak: app/budget.py
• Fonksiyonlar:
• user bazlı limit kontrolü
• global limit kontrolü
• request cost estimate
• usage update tetikleme
Model Router (Multi-model routing)
• Kaynak: app/router.py
• Input: classification sonuçları + budget/quality politikası
• Output: seçilen model (fast-model-v1, multilingual-model-v1, quality-model-v2)
LLM Client / Model Executor (prototip stub olabilir)
• Kodda direkt yoksa bile diyagramda “Model Invocation” olarak gösterin.
• Router’ın seçtiği model ile inference yapar.
• Not: “Production’da external provider entegrasyonu”.
Usage Storage / Usage Repository
• Kaynak: app/storage.py
• Görev: usage events kayıt, GET /api/usage için aggregation.
• Prototip notu: in-memory olabilir → restart’ta silinir.
Static Web UI
• Kaynak: static/index.html
• HTTP üzerinden servis edilir, API’yi tüketir.
Request akışı (oklarla net gösterin)
POST /api/chat için:
API Handler → Browser UI: response (answer + metadata)
GET /api/usage için:
API Handler → Client: usage summary
Bu akış diyagramda “happy path” olarak çizilmeli; ayrıca iki hata kolu ekleyin:
• Budget exceeded → 429/403 benzeri
• Model invocation error → 5xx + usage handling kararı (kayıt yazılır mı?)
Diyagramda özellikle vurgulanacak mimari desenler
• Pipeline/Orchestration: Chat isteği sırasıyla budget → classify → route → infer → log.
• Policy-based routing: routing kararı classification ve complexity sinyallerine dayanır.
• Cross-cutting concern: budget/token tracking her request’i sarar (middleware gibi). Kodda middleware yoksa bile diyagramda “Budget/Token Manager”i akışın hem başında hem sonunda gösterin.
• Prototype storage: storage.py kalıcı değil; production target’ta DB’ye evrilecek.
Bileşenleri olabildiğince parçalayın (overthink etmeden)
Bu repo küçük; ama diyagramda şu ayrımları yapmanız kaliteyi artırır:
• “API Handler” vs “Domain services (classifier/router/budget)” vs “Storage”
• “Model Router” vs “Model Executor/Client” (ileride external provider olacağı için)
• “Usage write” ve “Usage read” akışlarını ayrı oklarla belirtin
Etiketleme (labels)
Her kutuda:
• Modül adı: app/classifier.py
• Rol: “Classification Agent”
• Input/Output anahtarları: “message → {lang,intent,complexity}”
Okların üzerinde:
• HTTP route (örn. POST /api/chat)
• Data (örn. “message”, “usage record”, “model selection”)
Renk/şekil kodlama (basit ama tutarlı)
• Mavi: UI / Client
• Yeşil: API / HTTP layer
• Sarı: Domain services (classifier/router/budget)
• Mor: Storage
• Gri kesik çizgi: Future externals (LLM provider, DB, Auth)
Şekiller:
• Dikdörtgen: component/service
• Silindir: storage (in-memory/DB)
• Bulut: external provider
Diyagrama mutlaka eklenmesi gereken “production gaps” (README notuna uygun)
Prototip olduğunu görünür kılmak için diyagramda “Future/Out of Scope” alanı açın:
• AuthN/AuthZ (kullanıcı kimliği → budget user-key)
• Rate limiting
• Persistent DB (usage/budget)
• Real LLM provider integrations
• Security controls (input validation, logging, secrets)
Bunları kesik çizgili kutular ile ekleyip, mevcut akışta nereye oturacağını oklarla gösterin (ör. Auth middleware API handler’ın önünde).
Component (app/)
• /api/chat handler
• /api/usage handler
• Classifier (classifier.py)
• Budget manager (budget.py)
• Model router (router.py)
• LLM client/executor (conceptual)
• Storage/repository (storage.py)
• Static UI (static/index.html)
Her birinde net oklar, net data-flow, ve prototip vs production ayrımı.