Humindx Docs

Appearance

ADR 003: Monorepo Tek Repo + npm Workspaces ​

  • Tarih: 2026-04-16
  • Durum: Kabul Edildi (Accepted)
  • İlgili Bileşen: Repo Yapısı / Build Sistemi
  • Bağlam Dosyaları: ../../architecture/system-overview.md, ../../../CLAUDE.md §1
  • Sahip: Simetri

1. Bağlam ve Problem ​

Humindx, docs'ta tanımlı hedef mimariye göre en az iki TypeScript servisi (services/api-gateway NestJS, clients/b2b-panel Next.js), bir Python servisi (services/psychometric-engine FastAPI) ve bir mobil istemci (clients/b2c-mobile React Native veya Flutter) barındıracak. Mobil istemcinin de TS kullanması muhtemel. 3-4 TS projesi + 1-2 Python projesi = klasik çok-dilli monorepo.

İki soru:

  1. Tek repo mu, çoklu repo mu?
  2. Tek repo ise TS projeleri için hangi workspace/monorepo aracı (npm / pnpm / yarn / Nx / Turborepo / yok)?

Python servisi bu kararın dışında — kendi pyproject.toml ile bağımsız yönetilir.

2. Karar ​

  • Tek repo (monorepo) — services/, clients/, docs/, infra/ kardeş klasörler.
  • TS projeleri için npm workspaces — sıfır yeni araç; her alt proje kendi package.json'unu tutar, kök package.json workspaces array'i ile bunları bağlar.
  • Shared TS config — kök tsconfig.base.json her alt proje tarafından extends edilir.
  • Python servisi — services/psychometric-engine/pyproject.toml, workspace sistemi dışında; CI'da ayrı job.

3. Değerlendirilen Alternatifler ​

3.1. Çoklu Repo (her servis kendi repo'su) ​

  • Artıları: Repo izolasyonu, küçük git history, bağımsız deploy.
  • Eksileri: docs'u hangi repo'da tutacağız? Çapraz değişiklik (örn: api-contracts.md + hem API hem client güncellemesi) çoklu PR demek. Pre-development ekip için koordinasyon yükü.
  • Neden seçilmedi: Ekip <5 kişi iken monorepo'nun basitliği ağır basar. Çoklu repo'ya ihtiyaç ekibin "servis sahipliği" netleşince duyulur.

3.2. pnpm Workspaces ​

  • Artıları: Hızlı install, disk-verimli (content-addressable store), katı bağımlılık hoisting (phantom dep yok), iyi monorepo desteği.
  • Eksileri: Yeni bir araç (npm ile gelmiyor); CI'da setup adımı + developer machine'e kurulum.
  • Neden seçilmedi: Şu an 2-3 TS projesi için npm workspaces yeterli. Dep graph'ta pain (phantom deps, slow install) yaşanırsa migrate kolay — sadece lockfile + workspace syntax değişir.

3.3. Yarn v4 Workspaces + PnP ​

  • Artıları: Hızlı, zero-install.
  • Eksileri: PnP ile TS/Jest/editör uyumsuzlukları hala sık; ek yapılandırma gerekir.
  • Neden seçilmedi: Stabilite-karmaşıklık dengesi npm'in altında.

3.4. Nx veya Turborepo ​

  • Artıları: Graph-based build cache, etkilenen proje tespiti, büyük monorepo'lar için vazgeçilmez.
  • Eksileri: Konfigürasyon overhead, learning curve, 2-3 projede ROI yok.
  • Neden seçilmedi: "Çözüm arayan problem" sınıfı. CI süresi > 10 dk olunca veya proje sayısı 5+ olunca Turborepo eklenir (migrate kolaydır; npm workspaces hala altta çalışır).

3.5. Hiç Workspace Aracı — Her Proje Tam Bağımsız ​

  • Artıları: En basit.
  • Eksileri: Shared TS config'i her projede kopyala, hangi versiyonun nerede olduğu belirsiz, shared utility çıkartıldığında ayrı package publish gerekir.
  • Neden seçilmedi: İlk shared type (örn. packages/shared-contracts) gerektiğinde patlıyoruz.

4. Gerekçeler ​

  1. Sıfır yeni araç. Node ile gelir; CI/CD kurulumu daha basit; yeni developer extra tool kurmaz.
  2. Migrasyon ucuz. pnpm-workspace.yaml + pnpm install ile pnpm'e geçiş yarım saatte tamamlanır; Nx/Turborepo da npm workspaces üzerine eklenir.
  3. Çapraz değişiklik kolaylığı. api-contracts.md + kontratı kullanan istemcinin aynı PR'da güncellenmesi mümkün (bkz. CONTRIBUTING.md §8.4).
  4. Dev deneyimi yeterli. VS Code, TypeScript Language Server ve Jest npm workspaces ile sorunsuz çalışır.
  5. Python servisi etkilenmez. Kendi pyproject.toml ve .venv'i ile çalışır; CI'da ayrı job.

5. Sonuçlar ve Gelecek Etkileri ​

Klasör yapısı (hedef):

humindx/
├── package.json                     ← Workspaces root
├── tsconfig.base.json
├── services/
│   ├── api-gateway/                 ← NestJS (TS workspace)
│   │   ├── package.json
│   │   └── tsconfig.json (extends ../tsconfig.base.json)
│   └── psychometric-engine/         ← FastAPI (pyproject.toml, NOT in npm workspace)
├── clients/
│   ├── b2c-mobile/                  ← React Native / Flutter (TBD)
│   └── b2b-panel/                   ← Next.js (TS workspace)
├── packages/                        ← (future) shared TS utilities if needed
└── infra/                           ← Docker, Terraform

Avantajlar:

  • Tek npm install tüm TS projelerini kurar.
  • Cross-package import (@humindx/shared-contracts) npm workspaces sayesinde native çalışır.
  • CI cache tek package-lock.json üzerinden.

Dezavantajlar ve Riskler:

  • Tek package-lock.json büyüdükçe CI install süresi artar.
  • npm hoisting "phantom dependency" sorunlarına yol açabilir (bir paket, açıkça belirtmediği bağımlılıkları hoisting sayesinde import edebilir — prod'da patlar).

Hafifletme Stratejisi:

  • Phantom dep için CI'da npm ls + linter kuralı (import/no-extraneous-dependencies).
  • CI süresi > 10 dk'ya çıkarsa npm ci --prefer-offline --no-audit + cache optimizasyonu; hala yetmezse Turborepo eklenir.

Ne Zaman Yeniden Değerlendirilir?

  • TS proje sayısı 5+ olduğunda (Turborepo/Nx)
  • CI install süresi > 5 dk (pnpm'e migrate)
  • Phantom dep'ten kaynaklı bir prod incident (pnpm katı hoisting)
  • Tek bir TS projesi ayrı release cadence'a geçerse (polyrepo'ya split)

Simetri tarafından inşa ediliyor.