MİMARİ & TASARIM KARARLARI

Bölüm 1 — Neden modüler monolit ve nasıl inşa edildi

Şubat 2026 • Solen Kablo • Yaşayan Doküman

1. MİMARİ: MODÜLER MONOLİT

Sistem bir Modüler Monolit’tir — açıkça ayrılmış dahili modüllere sahip, tek bir veritabanını paylaşan tek bir uygulama. Mikroservis değil. Geleneksel monolit değil. Aradaki ideal nokta.

Neden Mikroservis Değil?

• Ölçek gerektirmiyor. 10–12 makine, düzinelerce kullanıcı, günde yüzlerce (milyonlarca değil) işlem. Tek bir proses bunu rahatlıkla kaldırır.
• Modüller arası ACID işlemler. Sipariş oluşturulduğunda malzemeler hesaplanır, iş kartları üretilir, stok tahsis edilir — hepsi tek bir veritabanı işleminde. Mikroservislerle bu, dağıtık saga kabusu olur.
• Tek geliştirici. Mikroservisler deployment, izleme, service mesh ve servisler arası iletişimi yönetmek için bir ekip gerektirir. Solo geliştiricinin basitliğe ihtiyacı vardır.
• Fabrika ağı, bulut değil. Bu, Kubernetes kümesinde değil, fabrika zeminindeki Mac Mini’de çalışır. Tek proses, tek veritabanı, tek deployment hedefi.

2. TEKNOLOJİ STACK’İ

Backend

Frontend

3. TASARIM KURALLARI

Kural 1: Türkçe-Öncelikli Arayüz

Her UI etiketi, her hata mesajı, her bildirim Türkçe. Fabrika operatörleri İngilizce konuşmaz. Ant Design yerel ayarı Türkçe’ye kilitli. AI promptları Türkçe.

Kural 2: Her Şeye QR Kod

Fabrikada hareket eden her fiziksel nesne girişte QR kod basılır. Ham bakır sepetleri, kalaylı bakır sepetleri, makaralar, bitmiş kablolar — hepsi taranabilir. QR kod, o nesnenin sistemdeki tüm geçmişine bağlantı sağlar.

Kural 3: Üç Kullanıcı Rolü, Fazlası Yok

Kural 4: Tasarım Üretimi Yönlendirir

Kablo tasarımı tek doğruluk kaynağıdır. Bir tasarım Cable Playground’da oluşturulduğunda, tüm üretim akışını kodlar — her makine adımı, her malzeme gereksinimi, her test. Siparişler tasarımlara referans verir. İş kartları tasarımlardan üretilir. Hiçbir şey sipariş başına manuel konfigure edilmez.

Kural 5: Erken Optimizasyon Yok

Geliştirmede SQLite. Gerektiğinde PostgreSQL. Ölçülmüş bir performans problemi olana kadar Redis cache yok. Senkron işlemenin yetersiz olduğu kanıtlanana kadar mesaj kuyruğu yok. Çalışan en basit şeyi inşa et, ölç, sonra optimize et.

4. API TASARIMI

Backend, port 8000’de çalışan tek bir FastAPI uygulamasına monte edilmiş 25’ten fazla router grubu sunar. Her endpoint aynı deseni izler:

@router.get("/endpoint")
async def get_something(
    db: Session = Depends(get_database),          # DB oturumu enjekte edilir
    current_user: User = Depends(get_current_user) # Auth enjekte edilir
):
    # İş mantığı burada
    return result

Temel Desenler

• Her şey için dependency injection. Veritabanı oturumları Depends(get_database), kimlik doğrulama Depends(get_current_user), rol kontrolleri Depends(require_super_admin). Global state yok.
• Validasyon için Pydantic şemaları. Her istek gövdesi ve yanıtın tip güvenli şeması var. Model başına Create, Update ve Response varyantları.
• İş mantığı için servis katmanı. Karmaşık hesaplamalar (malzeme gereksinimleri, iş kartı üretimi, stok projeksiyonları) route handler’larda değil services/’da yaşar.
• Fabrika ağı CORS. CORS konfigürasyonu, 192.168.x.x ve 10.0.0.x fabrika ağlarındaki herhangi bir cihazdan HTTP ve HTTPS erişimini desteklemek için 1000’den fazla origin kombinasyonu üretir.

5. VERİTABANI STRATEJİSİ

Veritabanı önceden tasarlanmadı. Her modül inşa edildikçe organik olarak büyüdü. Bu kasıtlıdır — alan, anlaşılmadan önce bir şema tasarlamak için çok karmaşıktı.

SQLAlchemy ORM, aynı Python kodunun her iki veritabanına karşı çalışmasını sağlar. Geçiş yalnızca DATABASE_URL ortam değişkenini değiştirmeyi gerektirir.

6. FRONTEND MİMARİSİ

Frontend, Ant Design Pro ile inşa edilmiş, rol tabanlı menüler aracılığıyla tüm modüllere hizmet veren tek bir React uygulamasıdır.

src/pages/
├── Dashboard/              # Ana Panel — genel bakış + AI sohbet
├── Lab/                    # Laboratuvar — testler, malzeme denetimi
├── Teknik/                 # Teknik — kablo tasarımı, makineler, standartlar
├── Siparis/                # Sipariş — siparişler, müşteriler
├── Production/             # Üretim — planlama, makine arayüzleri
├── Stok/                   # Stok — projeksiyonlar, ürün stoğu
├── Hammadde/               # Hammadde — malzeme girişi, siparişler
└── Admin/                  # Admin — yazıcılar, kullanıcılar, AI ayarları

7. AI ENTEGRASYONU

Ayrı bir Python servisi, panodan erişilebilen AI destekli arama ve sohbet sağlar. AI, 92 API endpoint aracı üzerinden tüm veritabanına salt okunur erişime sahiptir.

8. AĞ & DEPLOYMENT

Sistem, fabrika zeminindeki bir Mac Mini’de çalışır ve yerel ağdaki tüm cihazlara erişilebilir.

Operatörler QR kod taramak ve üretim kaydetmek için telefon/tabletlerde mobil Chrome kullanır. Yöneticiler sipariş yönetimi, tasarım ve raporlama için masaüstü tarayıcıları kullanır.

9. EVRİM YOLU

Mimari, ölçek gerektirdiğinde planlı bir evrim yoluna sahiptir:

Her aşama bir yedek planıdır, hedef değil. Modüler monolit, belirli ölçülmüş problemler bir sonraki aşamayı gerektirmedikçe mimari olarak kalmalıdır. Bozuk olmayanı düzeltme.