ADR-013: Monorepo And Package Strategy

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-002
• Decision owners: project architecture maintainers

Context

Munderecat tek bir urun arayuzunden ibaret degildir. Ayni release zincirinde iki ayri web uygulamasi, Python veri pipeline’lari, PostgreSQL migration ve fonksiyonlari, paylasilan istemci contractlari, version-controlled corpus artifactleri ve kullanici/gelistirici dokumantasyonu bulunacaktir.

Bu parcalar birbirine baglidir, fakat ayni runtime veya deploy birimi degildir. Ayrik repolar schema ve veri surumlerini eszamanlamayi, atomik degisiklikleri ve yeniden uretilebilir release kanitlarini zorlastirir. Siniri olmayan tek repo ise uygulamalari birbirine ve pipeline implementasyonuna baglayarak ayni sorunu baska bicimde uretir.

Faz 0’da uretilen data/baselines/, data/manifests/, data/schemas/, Ruby bootstrap/safety araclari ve execution kayitlari kabul edilmis proje hafizasidir. Yeni iskelet bunlari tasimadan veya yeniden yorumlamadan genislemelidir.

Decision

Munderecat tek Git reposu icinde, acik sahiplik ve tek yonlu dependency kurallari olan bir monorepo olarak gelistirilecektir.

Repository Layout

Kalici ust seviye yerlesim soyledir:

munderecat/
|-- apps/
|   |-- web/
|   `-- docs/
|-- db/
|   |-- migrations/
|   |-- functions/
|   |-- policies/
|   |-- tests/
|   `-- fixtures/
|-- pipelines/
|   |-- corpus/
|   |-- annotations/
|   |-- ottoman/
|   |-- lexicon/
|   |-- repetitions/
|   `-- translations/
|-- packages/
|   |-- corpus-model/
|   |-- corpus-sdk/
|   |-- validation/
|   `-- ui/
|-- data/
|   |-- baselines/
|   |-- manifests/
|   |-- canonical/
|   |-- curated/
|   |-- fixtures/
|   `-- schemas/
|-- docs/
|   |-- user/
|   |-- developer/
|   |-- project/
|   `-- i18n/
|-- reports/
`-- scripts/
    |-- bootstrap/
    |-- release/
    |-- maintenance/
    |-- baseline/
    `-- safety/

Ust seviye root; workspace, lock, task runner, local environment, lint ve CI gibi repo-geneli sozlesmeleri tasir. Uygulamaya ozel ayarlar ilgili uygulama dizininde kalir.

Bu agactaki sorumluluklar:

Alan	Sorumluluk	Paket/deploy siniri
apps/web	Okuyucu ve arastirma urunu	Bagimsiz build ve deploy
apps/docs	docs/ iceriginin statik yayinlayicisi	DB’siz bagimsiz build ve deploy
db	PostgreSQL schema, migration, RPC, policy ve DB testleri	Sirali migration release’i
pipelines	Python corpus ve annotation derleyicileri	Tek kok Python proje sozlesmesi icindeki domain modulleri
packages	Uygulamalarca paylasilan TypeScript kutuphaneleri	pnpm workspace package’lari
data	Schema, manifest, kucuk curated karar, fixture ve sertifikali artifact	Runtime package degil; provenance kontrollu veri
docs	Markdown/MDX kaynak icerigi ve proje kayitlari	apps/docs tarafindan okunur
scripts	Bootstrap, release ve bakim orkestrasyonu	Yeniden kullanilan domain mantiginin evi degil
reports	Gecici veya yerel uretilmis raporlar	Git disi, yeniden uretilebilir output

JavaScript And TypeScript Workspace

• Kokte tek bir pnpm-workspace.yaml, tek package.json toolchain contracti ve tek pnpm-lock.yaml bulunur.
• apps/* ile packages/* pnpm workspace kapsamina girer.
• Her uygulama kendi build, test ve gerekli runtime dependency’lerini tanimlar; bir uygulamanin build’i diger uygulamanin runtime’ini gerektirmez.
• Paylasilan kod ancak gercekten iki tuketicisi veya acik bir platform contracti varsa packages/* altina cikarilir. Tek tuketicili kod ilgili uygulamada kalir.
• Internal package exportlari acik entrypointler ile sinirlidir. Baska bir package’in private source path’ine deep import yapilmaz.
• Workspace package surumleri tek repo release manifestinde izlenir; bu karar tum paketlerin ayni anda npm’e yayinlanmasini zorunlu kilmaz.

Python Workspace

• Python pipeline’lari repo kokundeki tek proje/environment contracti altinda pipelines/* domain modulleri olarak yonetilir.
• Tek dependency lock kullanilir. Resolver, Python surumu ve lock formati F1-003 tarafindan secilir; ADR-013 belirli bir araci erken kilitlemez.
• Ortak Python mantigi domain modulleri arasinda acik package API’leriyle paylasilir. scripts/ yalniz ince CLI/orkestrasyon katmani olabilir.
• Python ve TypeScript ayni kaynak dizinini veya private implementasyon dosyasini import etmez.
• Faz 0’daki Ruby bootstrap ve safety araclari sertifikali yonetim altyapisi olarak yerinde kalir. Urun pipeline’larinin yeni dili olarak Ruby secilmis sayilmaz ve bu ADR mevcut araclari yeniden yazmayi gerektirmez.

Dependency Direction

Izin verilen temel akis:

apps/* ---------> packages/*
apps/docs ------> docs/*
apps/* ---------> data/schemas + generated public contracts
packages/* -----> data/schemas + generated public contracts
pipelines/* ----> data/schemas + data/curated
pipelines/* ----> deterministic data/canonical + data/manifests outputs
db/* ----------> version-controlled SQL/schema contracts
scripts/* ------> public CLI entrypoints of the area being orchestrated

Asagidaki baglantilar yasaktir:

• apps/web ile apps/docs birbirini import edemez.
• packages/*, apps/* kaynaklarina baglanamaz.
• Uygulamalar pipeline private implementasyonunu veya migration dosyalarini runtime kutuphanesi gibi kullanamaz.
• Pipeline’lar uygulama componentlerini ya da Next.js runtime’ini kullanamaz.
• Bir dil diger dilin private kaynak kodunu okuyarak contract cikarmaz.
• scripts/ icinde ikinci bir domain implementasyonu olusturulamaz.

Cycle olusturan ihtiyac, daha alt seviyedeki mevcut bir contract package’ina alinir veya yeni bir ADR ile yeniden modellenir; karsilikli importla cozulmez.

Cross-Runtime Contracts

Runtime ve dil sinirini gecen bilgi yalniz version-controlled, sahipligi belli bir contract uzerinden paylasilir. Bunlar sunlarla sinirlidir:

• data/schemas/ altinda JSON Schema veya corpus package schema’lari,
• db/ tarafindan sahiplenilen SQL/OpenAPI/PostgREST contractlari,
• canonical kaynagi ve generator komutu belirtilmis generated types/SDK,
• release manifestiyle hash ve surumu baglanmis veri artifactleri.

Generated artifact elle duzeltilmez. Canonical kaynak, generator ve drift kontrolu ayni degisiklikte bulunur. Birden fazla dilde elle kopyalanmis ayni model contract kabul edilmez.

Source And Artifact Policy

Sinif	Ornek	Git politikasi
Elle yonetilen source	uygulama/pipeline kodu, migration, docs, schema	Takip edilir; review ile degisir
Curated karar	data/curated icindeki kucuk deklaratif kayit	Takip edilir; provenance ve review gerekir
Sertifikali generated	canonical corpus release’i, manifest, generated public contract	Yalniz deterministik uretici ve hash ile takip edilir
Gecici generated/cache	.next, coverage, search index scratch, reports/*	Ignore edilir; temiz clone’da yeniden uretilir
Local-only/private	.env, DB volume/dump, raw arsiv, credential	Repo disinda kalir ve denylist ile engellenir

F0 baseline ve manifestleri bu siniflandirmadan once kabul edilmis girdilerdir; yerleri ve icerikleri ilgili successor task acikca sahiplenmedikce degismez.

Consequences

Benefits

• Schema, migration, pipeline, generated SDK, web ve docs degisiklikleri tek PR ve tek release kanit zincirinde atomik incelenebilir.
• Ortak pnpm ve Python locklari temiz clone tekrar uretilebilirligini kolaylastirir.
• Uygulamalar ayri build/deploy edilebilirken paylasilan UI ve contractlar kopyalanmaz.
• Dil sinirlari schema ve generated artifactlerle gorunur olur; drift CI’da olculebilir.
• Acik kaynak katilimcisi hangi dosyanin source, curated karar, generated artifact veya local output oldugunu ust dizinden anlayabilir.

Costs

• Kok lockfile, workspace ve ortak config degisiklikleri tek-writer sahipligi ve daha genis review gerektirir.
• Her package acmak yerine tekrar kullanimi kanitlamak gerekir; aksi halde package sayisi ve CI grafigi gereksiz buyur.
• Cross-language contract generatorleri ve drift testleri kurulmalidir.
• Monorepo CI’i degisen alana gore filtreleme yapmadikca zamanla pahali hale gelebilir.

Alternatives Considered

Separate Repositories

Web, docs, DB ve pipeline’i ayri repolara bolmek bagimsiz sahipligi artirir, ancak schema/corpus surumlerinin atomik degisimini ve tek release manifestini zorlastirir. Bu projenin veri sadakati ve replay hedefi icin reddedildi.

One Undifferentiated Application

Tum kodu tek uygulama/package altinda tutmak ilk kurulumu kisaltir, fakat docs build’ini DB runtime’ina baglar ve pipeline ile UI arasinda private importlari tesvik eder. Bagimsiz failure domain gereksinimini karsilamadigi icin reddedildi.

Polyglot Packages With Shared Source Directories

Python ve TypeScript implementasyonlarini ayni package dizininde tutmak model kopyalarini ilk anda azaltabilir. Buna karsilik iki build sistemini birbirine baglar ve hangi dilin canonical oldugunu belirsizlestirir. Schema-first, generated contract yaklasimi daha denetlenebilir oldugu icin reddedildi.

Commit Every Generated Output

Tum rapor, cache ve build outputlarini Git’e almak tekrar uretim kaniti gibi gorunur, fakat repoyu sisirir ve source ile gecici sonucu karistirir. Yalniz release veya sertifika degeri olan deterministik artifactler takip edilecektir.

Deferred Decisions

• F1-001: Bu karara uygun fiziksel workspace iskeleti.
• F1-003: Python surumu, environment/resolver ve lock araci.
• F1-004: Next.js ve Node toolchain surumleri.
• F1-005: Local PostgreSQL/Supabase container topolojisi.
• F1-006: Tek task runner ve komut isimleri.
• F1-014: Dokumantasyon frameworku ve content rendering modeli.
• F2-*: Domain schema, stable identity, corpus package, API ve migration contractlari.

Bu kararlar ADR-013’un dependency yonunu ihlal edemez; yeni bir ihtiyac bunu gerektirirse ADR-013 supersede edilmeden uygulama yapilmaz.