Frontend Sistemi

Ortak temel

Depo webgui/, docs/ ve Ink tui/ için root pnpm workspace kullanır. uv Python bağımlılık yöneticisi olarak kalır; Makefile hedefleri yalnızca pnpm ve uv tabanlı komutlara ince alias'lardır.

Hem docs/ hem de webgui/ şu komutla başlatıldı:

pnpm dlx shadcn@latest init --preset b2CQzAxv8 --template next

b2CQzAxv8 başlangıçta kullanılan preset slug'ıdır; gelecekte registry'de erişilemiyorsa veya farklı sonuç veriyorsa her uygulamadaki components.json yerel component sözleşmesi için otoritedir.

Bu da iki uygulamaya ortak bir temel veriyor:

• Next.js App Router
• Tailwind v4
• CSS-variable tabanlı theme
• mevcut shadcn preset'i
• build sırasında Google Fonts fetch etmeyen local-first monospace tipografi

Component kuralı

pnpm dlx shadcn@latest add ... ile yeni component eklediğimizde CLI, her uygulamanın kendi components.json dosyasını okur. Bu sayede eklenen component'ler mevcut preset'i miras alır; görsel olarak başka bir tarafa kaymaz.

Modülerlik kuralı

Küçük dosya tek başına bir hedef değil; ama okunabilirliği artırıyorsa frontend tarafı bölünmeli. Dosya bölmek için iyi nedenler:

• route dosyası loading, copy ve layout'u aynı anda taşıyorsa
• tek bir component çok alakasız sorumluluk üstleniyorsa
• review tek bir dosyada birkaç farklı zihinsel modeli takip etmeyi zorlaştırıyorsa
• locale-aware ya da feature-aware copy'yi ayrı test etmek kolaylaşıyorsa

Docs uygulaması artık bu yaklaşımı components/home, components/feedback, components/layout, components/ui/primitives, lib/i18n ve lib/home/content ayrımıyla uyguluyor. Web GUI control room da aynı yöne gidiyor: üst seviye component state/render coordinator olarak kalmalı; view dosyaları, shell chrome, dashboard polling, action handler'ları, request helper'ları, primitive'ler ve typed dil bazlı İngilizce/Türkçe copy ayrı modüllerde durmalı. React component dosyaları PascalCase isim kullanır; copy, formatting, hook ve request helper dosyaları ise rol bazlı lowercase isimlerle kalır.

Web GUI migration gerçeği

webgui/ hâlâ geçiş sürecinde. Modern temel orada da hazır; ama bazı ekranlar hâlâ eski global CSS'e dayanıyor. İlk control-room bölünmesi ve ana view-copy katalogu tamam; sonraki işler coordinator'u tekrar büyütmeden typed view model'leri, katalog-aware helper satırlarını ve ekran kapsamlı stilleri ayırmalı.

Mevcut bölünme webgui/src/components/control-room/ altında state-hooks, view-model, action-request, formatting, diagnostics-formatting, context-formatting, loading panelleri, odaklı PascalCase view modülleri, shell chrome, primitive'ler ve typed İngilizce/Türkçe copy modüllerini içeriyor. webgui/src/components/ControlRoom.tsx public facade olarak kalmalı; ikinci bir uygulama dosyasına dönüşmemeli.

Web GUI i18n kuralı

Web GUI render sınırındaki copy için next-intl kullanır. Uygulama next-intl/plugin, request config, locale routing, typed messages ve client provider parçalarını webgui/src/i18n/ altında bağlar. Component'ler tüm copy katalogunu import etmek yerine useTranslations("controlRoom.section") ve yerel view-model helper'larını tercih etmeli. Observer/API/dashboard JSON anahtarları İngilizce ve stabil kalır; bunlar UI metni değil runtime contract'idir.

Docs i18n kuralı

Docs Fumadocs i18n üzerinde /en/... ve /tr/... route'larıyla kalır. Web GUI next-intl kullanıyor diye docs'u da oraya taşımayız; docs uygulamasında Fumadocs contract'ine uyan content routing, lokalize MDX ve navigation copy modülleri zaten vardır.

Güvenli migration kuralları:

• ekran ekran ilerle
• shadcn primitive'leri ve Tailwind utility'lerini tercih et
• route handler'ları ince tut
• bir component taşıyabiliyorsa yeni global CSS ekleme

Route handler kuralı

webgui/ içindeki Next.js route handler'ları input'u doğrulayıp sonra Python runtime contract'ine delegasyon yapmalı. Yeni bir business-logic katmanına dönüşmemeli.

Docs UX kuralı

Özellikle docs uygulaması için:

• locale desteğini açık tut
• navigasyonu öngörülebilir kıl
• landing page'leri gereksiz yükleme
• feedback mesajlarında tarayıcıda tutulan yerel taslak ile manuel GitHub issue bağlantısı ayrımını net yaz