Proje mimarisi

Multica'nın istemcilerinin, Go servisinin, çalıştırma daemon'ının ve paylaşımlı ön yüz paketlerinin birlikte nasıl çalıştığını öğrenin.

Multica, bir Go arka ucu, birden fazla istemci ve çalıştırma bilgisayarlarında koşan bir daemon'dan oluşur. PostgreSQL iş birliği verisini tutar; daemon görevleri üstlenir ve yerel yapay zekâ kodlama araçlarını çağırır.

Bu, uygulamaya odaklanan sayfa, ürün tarafındaki bir Çalıştırma'nın arkasındaki iç zamanlayıcı, API ve veritabanı varlığı için task terimini kullanır. Arayüz ve ürün dokümantasyonu buna Çalıştırma der; TaskService ve task_id gibi tanımlayıcılar uyumluluk için değişmeden kalır.

Web / Desktop / Mobile / CLI
             │
       HTTP + WebSocket
             │
      Go API ───────── PostgreSQL
             │
      daemon WebSocket
             │
     local daemon ─── AI coding tools

Ürüne yönelik bir açıklama için bkz. Multica nasıl çalışır. Bu sayfa, kodun nasıl katmanlandığına odaklanır.

Depo yerleşimi

Dizin	Sorumluluk	Ana teknolojiler
`server/`	API, kimlik doğrulama, çalıştırma zamanlaması, entegrasyonlar, CLI ve daemon	Go, Chi, sqlc, gorilla/websocket
`apps/web/`	Tarayıcı istemcisi ve tanıtım sayfası	Next.js App Router
`apps/desktop/`	Masaüstü istemcisi ve yerel süreç yönetimi	Electron, electron-vite
`apps/mobile/`	Bağımsız iOS istemcisi	Expo, React Native
`apps/docs/`	Çok dilli dokümantasyon sitesi	Next.js, Fumadocs
`packages/core/`	API istemcisi, tipler, sorgular, mutasyonlar ve platformdan bağımsız iş mantığı	TanStack Query, Zustand
`packages/ui/`	İş mantığı içermeyen temel arayüz bileşenleri	shadcn, Base UI
`packages/views/`	Web ve Desktop tarafından paylaşılan iş sayfaları ve bileşenleri	React
`packages/tsconfig/`, `packages/eslint-config/`	Paylaşımlı araç yapılandırması	TypeScript, ESLint

Paylaşımlı paketler .ts ve .tsx kaynak dosyalarını doğrudan dışa aktarır ve bunları tüketen uygulamalar tarafından derlenir. Bağımlılık yönü views → core + ui'dir; core ve ui birbirine bağımlı değildir.

Web ve Desktop arasında kod paylaşımı

Web ve Desktop üç katmanı paylaşır:

packages/core, API'leri, önbelleklemeyi, izinleri ve platformdan bağımsız durumu yönetir.
packages/ui, temel bileşenleri sağlar.
packages/views, iş sayfalarını bir araya getirir.

Yönlendirme, çerezler ve Electron IPC gibi platform yetenekleri uygulama katmanında kalır. Paylaşımlı sayfalar NavigationAdapter üzerinden gezinir ve next/* veya react-router-dom'u doğrudan içe aktarmaz.

Örneğin, hem Web hem de Desktop tarafından ihtiyaç duyulan bir iş özelliği genellikle şunlara dokunur:

packages/core/issues/      queries, mutations, cache updates
packages/views/issues/     pages and business components
apps/web/platform/         Next.js routing adapter
apps/desktop/.../platform/ Electron routing adapter

Mobile bu React sayfalarını yeniden kullanmaz. @multica/core'dan tipleri ve saf fonksiyonları içe aktarabilir, ancak kendi arayüzüne, sorgu anahtarlarına, durumuna, gerçek zamanlı aboneliklerine ve sürüm sürecine sahiptir.

Ön yüz durumu

Sunucu verisi ve istemci durumu ayrı yönetilir:

TanStack Query, işler, agent'lar, üyeler ve gelen kutusu öğeleri gibi sunucu verisine sahiptir.
Zustand, filtreler, taslaklar, iletişim kutuları ve yerleşim gibi istemci durumuna sahiptir.
Geçerli çalışma alanı rota tarafından belirlenir ve yalnızca istekler, kalıcı ad alanları veya yeniden bağlanmanın gerektirdiği yerlerde platform katmanında yansıtılır.
React Context yalnızca çalışma alanı kimliği ve gezinme adaptörü gibi platform altyapısını taşır.

WebSocket olayları, TanStack Query önbelleğini güncellemeli veya geçersiz kılmalıdır. Sunucu nesnelerini Zustand'a kopyalamayın. Bir çalışma alanı oluşturma, silme veya ayrılma gibi gezinen mutasyonlar, yerel durumu temizlemeden önce sunucu onayını beklemelidir.

API yanıtları, packages/core/api/ sınırında zod şemalarıyla ayrıştırılır. Kurulu bir Desktop istemcisi daha yeni bir arka uca bağlanabilir, bu yüzden ağ JSON'u doğrudan bir TypeScript tipi olarak öne sürülmemelidir.

Arka uç katmanları

Ana giriş noktaları server/cmd/ içindedir:

Giriş noktası	Amaç
`server`	HTTP API'yi, WebSocket servislerini, zamanlayıcıyı ve entegrasyon işçilerini başlatır
`multica`	CLI ve yerel daemon
`migrate`	Veritabanı migration'larını çalıştırır
`backfill_*`	Belirli sürümler için veri backfill araçları

İstekler genellikle şu yönde akar:

router → middleware → handler → service → sqlc query → PostgreSQL

internal/middleware/, kimlik doğrulamayı, çalışma alanını ve istek sınırlarını yönetir.
internal/handler/, HTTP girdisini ayrıştırır ve yanıtlar üretir.
internal/service/, sorgular arası iş akışlarına ve transaction'lara sahiptir.
pkg/db/queries/, elle yazılmış SQL içerir.
pkg/db/generated/, sqlc tarafından üretilir ve doğrudan düzenlenmemelidir.
internal/integrations/, GitHub, Slack, Feishu ve diğer servislerden gelen dış olayları yönetir.
internal/storage/, yerel ve S3 eklerini yönetir.

PostgreSQL, iş verisi için tek gerçek kaynaktır. Redis isteğe bağlıdır ve örnekler arası gerçek zamanlı olaylar, önbellekleme veya geçici koordinasyon için kullanılır. Redis olmadan, tek örnekli bir geliştirme ortamı süreç içi (in-process) uygulamalar kullanır.

Gerçek zamanlı bağlantılar

Multica'nın iki farklı WebSocket yolu vardır:

internal/realtime/, iş, yorum, gelen kutusu ve diğer değişiklikleri kullanıcı istemcilerine iletir.
internal/daemonws/, runtime'ları uyandırmak ve daemon RPC'si gerçekleştirmek için daemon'ları bağlar.

WebSocket gecikmeyi azaltır, ancak nihai durum veritabanında kalır. İstemciler, yeniden bağlandıktan sonra sorgular üzerinden kendini yeniden kalibre etmelidir. Daemon ayrıca, tek bir bağlantı kopmasının kuyruktaki bir çalıştırmayı sonsuza dek takılı bırakmaması için bir polling yolu da tutar.

Tek bir çalıştırma için kod yolu

Bir kullanıcı bir işi atar, bir agent'tan bahseder veya bir otomasyon tetiklenir.
TaskService, kuyruklu bir çalıştırma oluşturur ve ilgili runtime'ı bilgilendirir.
Daemon, çalıştırmayı daemon API'si üzerinden üstlenir.
Sunucu, çalıştırmaya ve agent'a bağlı geçici kimlik bilgileri verir.
Daemon, yerel bir dizin hazırlar ve pkg/agent içindeki ilgili sağlayıcı arka ucunu çağırır.
Araç yerelde çalışırken daemon ilerlemeyi, mesajları ve son durumu yükler.
Sunucu, çalıştırmayı ve işi günceller, ardından gerçek zamanlı olaylar üzerinden istemcileri yeniler.

Sağlayıcı adaptör katmanı, yapay zekâ kodlama araçları arasında başlangıcı, akış olaylarını, iptali ve kullanım verisini normalleştirirken, yerel dizinler ve oturumlar hâlâ daemon'a aittir.

Çoklu çalışma alanı sınırları

İş sorguları workspace_id ile sınırlandırılmalıdır ve bir istek bir çalışma alanı rotasına girmeden önce üyelik kontrol edilir. X-Workspace-ID, geçerli çalışma alanını seçer ancak yetkilendirme kontrollerinin yerini tutmaz.

Bir işin atananı polimorfiktir ve bir üyeye, agent'a veya Ekibe işaret edebilir. Yeni sorgular, önbellek anahtarları ve gerçek zamanlı olaylar, bir kaynak kimliğinin küresel olarak benzersiz bağlam olduğunu varsaymak yerine hem çalışma alanını hem de atanan tipini korumalıdır.

Sonraki adımlar

Katkıda bulunma — Yerel ortamlar, worktree'ler ve test konumları.
Geliştirme kuralları — Adlandırma, terminoloji ve Çince metin için depo sözleşmeleri.

Bu sayfada