Factorizer/Cluster ERP WikiCluster ERP English
Ana sayfa / Genel bakış

Açıklama

Mimariye genel bakış

Cluster ERP sunucusunun, 28 modülünün, EventBus'ın, web uygulamasının, masaüstü istemcinin ve PostgreSQL veritabanının birbirine nasıl bağlandığı.

Bu sayfa Cluster ERP'nin ana parçalarını ve aralarındaki bağlantıyı gösterir: tek bir FastAPI sunucusu, ona yüklenen 28 modül, modüller arasında süreç içi bir EventBus, iki istemci ve bir PostgreSQL veritabanı. Sayfa bir haritadır, kılavuz değildir. Her parça, onu belgeleyen sayfaya bağlantı verir.

Kısaca

  • create_app tek bir FastAPI uygulaması kurar; bu uygulama hem API'yi hem web uygulamasını sunar (src/cluster_erp/server/app.py:1287, src/cluster_erp/server/app.py:1633-1644).
  • Modül kaydı cluster_erp.modules altındaki paketleri bulur ve her birini uygulamaya yükler (src/cluster_erp/core/module_registry.py:19, src/cluster_erp/core/module_registry.py:58-72).
  • Modüller birbirleriyle yalnızca EventBus ve core/contracts.py içindeki sözleşmeler üzerinden konuşur (src/cluster_erp/core/event_bus.py:43-49, src/cluster_erp/core/contracts.py:1-6).
  • İş verisine dokunan her istek, asyncpg üzerinden PostgreSQL'de bir SQLAlchemy oturumu alır (src/cluster_erp/server/dependencies.py:160-200, src/cluster_erp/core/database.py:95-102).
  • Web uygulaması ve masaüstü istemci ekranlarını GET /api/v1/_meta ile sunulan modül metadata'sından çizer (src/cluster_erp/server/app.py:1518-1556).

Nasıl çalışır

Şema parçaları ve aralarındaki çağrıların yönünü gösterir.

flowchart LR
 browser["Tarayıcı: webapp/"]
 desktop["Masaüstü istemci: PySide6"]
 subgraph server["Sunucu süreci"]
 app["create_app: FastAPI"]
 mw["Ara katman yığını"]
 shared["Ortak rotalar: server/routes"]
 mods["28 modül: ModuleBase"]
 bus["EventBus"]
 core["core: models, metadata, change_history"]
 end
 db[("PostgreSQL")]
 storage[("Dosya deposu")]
 browser -->|"HTTP /app ve /api/v1"| app
 desktop -->|"HTTP /api/v1"| app
 app --> mw
 mw --> shared
 mw --> mods
 mods <-->|"Event ve Query sözleşmeleri"| bus
 shared --> core
 mods --> core
 core --> db
 shared --> storage

Şemanın düz metin karşılığı şudur:

  1. Tarayıcı web uygulamasını /app yolundan yükler ve API'yi /api/v1 altında çağırır. Masaüstü istemci aynı API'yi httpx ile çağırır (src/cluster_erp/desktop/core/api_client.py:7, src/cluster_erp/desktop/core/api_client.py:86-87).
  2. Her istek bir rotaya ulaşmadan önce ara katman yığınından geçer. Bkz. istek hattı ve ara katmanlar.
  3. Rotalar ya bir modüle aittir (önek /api/v1/<module>, src/cluster_erp/core/module_base.py:36-38) ya da create_app'in doğrudan bağladığı src/cluster_erp/server/routes/ içindeki ortak rotalardır (src/cluster_erp/server/app.py:1432-1450). Bkz. ortak sunucu rotaları.
  4. Modüller veriyi dondurulmuş dataclass sözleşmeleriyle EventBus üzerinden değiş tokuş eder. Bkz. olay veri yolu ve sözleşmeler başvurusu.
  5. Modüller ve ortak rotalar src/cluster_erp/core/ içindeki platform çekirdeğini kullanır: temel model, metadata sınıfları, değişiklik geçmişi, para yardımcıları, arama ve depolama.
  6. Veri PostgreSQL'de durur. Yüklenen dosyalar açılışta oluşturulan bir depolama arka ucunda, yerel diskte ya da S3'te durur (src/cluster_erp/server/app.py:65-75). Bkz. ekler, notlar ve depolama.

Sunucu ve açılış

python -m cluster_erp.server.main, uvicorn'u fabrika bayrağıyla çalıştırır (src/cluster_erp/server/main.py:39-41). Yaşam süresi (lifespan) bağlamı veritabanı tutamacını, EventBus'ı, modül kaydını ve depolama arka ucunu oluşturur; ardından modülleri yükler ve açılış geçişlerini çalıştırır (src/cluster_erp/server/app.py:58-196). Bkz. sunucu açılışı ve uygulama fabrikası.

Modüller

Her modül ModuleBase sınıfından türer ve initialize, register_routes, register_events, shutdown ve get_metadata yöntemlerini uygular (src/cluster_erp/core/module_base.py:61-74). Bkz. modül yaşam döngüsü ve modüller bölümü.

Metadata ve istemciler

get_metadata ekranları, formları, listeleri ve aksiyonları tanımlayan bir ModuleMeta nesnesi döndürür (src/cluster_erp/core/metadata.py:719). Sunucu tüm modüllerin metadata'sını ETag taşıyan tek bir belgeye dönüştürür (src/cluster_erp/server/app.py:1518-1556). Bkz. metadata modeli, web uygulaması bölümü ve masaüstü bölümü.

Veritabanı

Database bir async SQLAlchemy motorunu ve bir oturum fabrikasını sarar (src/cluster_erp/core/database.py:53-105). Şema migrations/ içindeki Alembic sürümlerinden gelir (alembic.ini:2). Çok kiracılı kipte her kiracının kendi veritabanı vardır (src/cluster_erp/config/settings.py:78-84). Bkz. veritabanı ve oturumlar ve çok kiracılılık.

Neden böyle kurulmuştur

Projenin yazılı mühendislik kuralları modüller arası doğrudan iletişimi yasaklar ve bunun için EventBus'ı zorunlu kılar. Ayrıca "app-level + middleware" mimarisinin bozulmasını yasaklar ve metadata güdümlü bir web uygulaması ister. src/cluster_erp/server/app.py:1573-1575 içindeki kod yorumu, sunucunun web uygulamasını neden kendisinin sunduğunu belirtir: tarayıcı API'ye aynı kökenden, CORS olmadan ulaşır.

Kurallar ve sınırlar

  • Hiçbir modül, cluster_erp.modules.auth.guards dışında başka bir modülü içe aktarmaz. Bunu tests/test_architecture_boundaries.py:46-57 testi zorlar.
  • Her modülün bir module.py dosyası ve en az bir rota dekoratörü vardır. Bunu tests/test_architecture_boundaries.py:60-72 testi zorlar.

Diğer parçalarla etkileşim

Platform bölümü çekirdeği ayrıntılı belgeler. Kimlik ve erişim bölümü kimlik doğrulama, izinler ve kiracılığı kapsar. API bölümü HTTP rotalarını listeler. İşletim bölümü kurulumu kapsar.

Sınırlar ve açık noktalar

  • Masaüstü istemcinin varsayılan API adresi yerel bir geliştirme adresidir (src/cluster_erp/desktop/core/api_client.py:82). Üretimdeki bir masaüstü kurulumunun bir sunucuya nasıl yönlendirildiği masaüstü bölümünde belgelenir.

İlgili sayfalar

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.

Doğrulanan commit 92f8051 · 2026-11-13