Sistem mimarisi

Münderecat, kaynak metni birebir koruyan immutable bir core ile bu metne bağlanan bağımsız annotation authority katmanlarını ayrı yayınlar. Reader, seçilen release’leri public API üzerinden birleştirir; annotation kaybolsa bile Latin core metin aynı sıra, boşluk ve noktalama ile yeniden kurulabilir.

Bu sayfa yön bulma rehberidir. Normatif kararlar ADR-001, core ER, annotation ER, provenance sözleşmesi ve public API sözleşmesindedir.

Sistem bağlamı

flowchart TB
  accTitle: Münderecat sistem bağlamı
  accDescr: Salt okunur kaynaklar deterministik pipeline ve corpus package üzerinden immutable core release'e dönüşür. Annotation pipeline'ları core koordinatlarına bağlanan ayrı domain release'leri üretir. Release-bound API, core ve seçilen annotation projeksiyonlarını web okuyucuya sunar; dokümantasyon uygulaması repository sözleşmelerinden bağımsız statik çıktı üretir.

  source[Salt okunur kaynaklar] --> intake[Source inventory ve parser]
  contracts[Versioned config ve contract'lar] --> intake
  intake --> package[Deterministik package ve manifest]
  package --> core[Immutable core release]

  core --> anchors[Shared span ve selection]
  domainSource[Curated/domain kaynakları] --> annotations[Annotation pipeline'ları]
  anchors --> annotations
  annotations --> domainRelease[Structural, lexical, Ottoman, repeat ve alignment release'leri]

  evidence[Provenance, run, evidence ve curation kayıtları] --> package
  evidence --> domainRelease
  core --> deployment[Release-bound API deployment]
  domainRelease --> deployment
  deployment --> api[api_v1 read projection'ları]
  api --> web[Web reader]

  repo[Repository docs ve machine contract'lar] --> docs[Statik docs uygulaması]
  docs --> contributor[Geliştirici ve kullanıcı]
  web --> reader[Okuyucu]

Okların yönü authority devri değildir. Örneğin annotation pipeline’ı core span’ına başvurur fakat cümle, token veya noktalama sahibi olmaz. API projection’ı da owner tablonun yerine geçmez; deployment’ın seçtiği immutable release’leri okuma için şekillendirir.

Authority katmanları

Katman	Sahip olduğu gerçek	Değişiklik yolu
Kaynak ve contract	Girdi locator’ı, parser/tokenizer profili, dahil/hariç kararı	Yeni versioned contract ve source closure
Core	Eser/metin sürümü hiyerarşisi, exact token occurrence, sıra, boşluk, noktalama	Yeni core/text release ve etkilenen yeni occurrence ID’leri
Shared anchor	Exact core release içindeki span ve ordered selection geometrisi	Yeni anchor veya identity-changing durumda successor
Domain authority	Heading, segment, note, terkip, lexeme, kök, lügat, Osmanlıca form, tekrar ve alignment kararı	Reviewed curation + yeni immutable domain release
Provenance/control	Source, run, evidence, decision, transaction ve release lineage	Append-only event/release
API deployment	Birlikte okunacak exact release/policy tuple	Yeni manifest ve compare-and-swap activation
Projection/cache	Reader, search veya rapor için yeniden hesaplanabilir görünüm	Kaynak authority değişmeden rebuild/refresh

Core ve annotation ayrımının pratik kuralı şudur:

core release + core rows = exact canonical Latin text
core release + selected domain releases = enriched reader view

İkinci satır birincinin sonucunu değiştiremez. Ayrıntılar için core veri modeli, exact reconstruction ve annotation veri modeline bakın.

Build ve publication akışı

flowchart LR
  accTitle: Kaynaktan immutable yayına veri akışı
  accDescr: Source inventory versioned parser ve identity contract ile deterministik package üretir. Importer paketi disposable veritabanında doğrular, exact reconstruction ve root kontrollerinden sonra immutable core release yayınlar. Annotation pipeline'ları aynı core release'in stable koordinatlarına bağlanır ve ayrı reviewed domain release'leri üretir.

  inventory[Source inventory] --> parser[Parser ve normalization profile]
  parser --> identities[Stable identity issuance]
  identities --> streams[Canonical JSONL stream'leri]
  streams --> manifest[Package manifest ve roots]
  manifest --> import[Structured importer]
  import --> reconstruct[Exact reconstruction doğrulaması]
  reconstruct --> coreRelease[Accepted core release]

  coreRelease --> geometry[Span ve selection geometry]
  geometry --> candidates[Domain candidate/evidence]
  candidates --> review[Semantic review ve curation]
  review --> domainRelease[Accepted domain release]
  coreRelease --> apiManifest[API deployment manifest]
  domainRelease --> apiManifest

Package taşıma formatıdır; source authority veya database dump değildir. Importer paket stream’lerinin schema, sıra, FK, row hash, root ve identity bağlarını kontrol eder. Accepted core satırları yerinde düzeltilmez. Corpus üretme ayrıntıları corpus package rehberinde açıklanır.

Annotation pipeline’ı otomatik candidate üretebilir, fakat candidate confidence’ı semantic authority değildir. Kabul; reviewed decision, provenance closure ve exact release inventory ile oluşur. Lexical/Osmanlıca, tekrar ve alignment akışlarının özel sınırları sırasıyla Osmanlıca ve lexical mimari, tekrar mimarisi ve çok dilli alignment sayfalarındadır.

Reader akışı

sequenceDiagram
  accTitle: Release-bound reader okuma akışı
  accDescr: Web reader deployment kimliğiyle public API'yi çağırır. API exact core ve seçilmiş domain release'lerini bağlar. Core reader source order ile metni reconstruct eder; optional annotation projection'ları aynı stable koordinatlara overlay olarak eklenir ve core çıktısına geri beslenmez.

  participant W as Web reader
  participant A as api_v1
  participant D as Deployment manifest
  participant C as Core owner relations
  participant N as Annotation projections

  W->>A: chapter + deployment_id
  A->>D: exact release/policy tuple
  D-->>A: core ve domain binding'leri
  A->>C: source-order core traversal
  C-->>A: exact sentence/token facts
  A->>N: optional heading/Ottoman/lexical/repeat/alignment reads
  N-->>A: release-bound overlays veya açık unavailable state
  A-->>W: release metadata + canonical units + optional overlays

Reader şu davranışları korur:

• metin UUID, insert sırası veya query planıyla değil parent position alanlarıyla sıralanır;
• whitespace ve punctuation renderer tarafından tahmin edilmez;
• unavailable annotation yalnız ilgili özelliği kapatır, chapter metnini kesmez;
• response kullanılan core/data/policy release kimliklerini taşır;
• public rol owner tablolara doğrudan DML yapmaz.

RPC ve response şekilleri machine contract’tan üretilen Public API v1 rehberindedir.

Correction ve curation akışı

flowchart LR
  accTitle: Append-only düzeltme ve curation akışı
  accDescr: Bir öneri exact beklenen state'e bağlanır ve bağımsız review alır. Rejected karar yalnız history ve evidence olarak kalır. Accepted karar transaction olarak uygulanır. Identity-changing değişiklik successor ve supersession ürettiğinde yeni resolution release gerekebilir; domain release'in reader deployment'a alınması ayrıca incelenen bir seçimdir.

  issue[Hata veya iyileştirme] --> proposal[Versioned proposal]
  proposal --> review[Bağımsız review]
  review --> decision{Decision}
  decision -- Rejected --> retained[Retained decision ve evidence]
  decision -- Accepted --> transaction[Append-only curation transaction]
  transaction --> preserving{Identity değişiyor mu?}
  preserving -- Hayır --> state[Mevcut ID + yeni lifecycle/evidence]
  preserving -- Evet --> successor[Yeni ID + typed supersession]
  state --> release[Yeni curation/domain release]
  successor --> release
  release --> graph{Supersession graph değişti mi?}
  graph -- Evet --> resolution[Mevcut policy altında yeni resolution release]
  graph -- Hayır --> published[Domain release yayımlandı]
  resolution --> published
  published --> activation{Reader deployment'a alınacak mı?}
  activation -- Hayır --> retainedRelease[Release retained]
  activation -- Evet --> deployment[Ayrı reviewed API deployment]

Rejected proposal transaction veya publication üretmez; karar ve kanıt audit history’de kalır. Kabul edilmiş identity-preserving bir değişiklik de supersession grafını değiştirmiyorsa yeni resolution release gerektirmez. Domain/resolution release’in reader tarafından seçilmesi ayrı manifest, review ve activation kararıdır.

Authored atıf eski hedef ID’sini korur. Exact lookup tarihsel entity’yi, current resolver ise açık policy/release altında successor kümesini verir. Dil veya canonical tekrar projection’ı sunum seçeneğidir; authored edge’e yazılmaz. Atıf hedefi ve reference readiness bu yaşam döngüsünün uygulama sözleşmesini açıklar.

Repository haritası

Yol	İçerik	Authority notu
config/	Versioned pipeline, identity, API, release ve governance contract’ları	İnsan tarafından reviewed machine input
db/supabase/migrations/	Forward-only fiziksel schema, constraint, role ve RPC değişiklikleri	Kabul edilmiş migration değiştirilmez
pipelines/, scripts/	Compiler, importer, publication, verifier ve rapor araçları	Çıktı authority’si release/evidence ile kazanılır
packages/contracts/	Paylaşılan schema ve contract kodu	API/data boundary
data/canonical/, data/curated/	Kabul edilmiş repository-retained veri	Contract ve release root ile bağlı
data/contracts/, data/schemas/	Makine şemaları	Generated/consumer validation authority
data/releases/, data/reports/	Release certificate ve bounded raporlar	Claim scope dosya içinde açık olmalıdır
apps/web/	Release-bound okuyucu	Owner authority değildir
apps/docs/, docs/	Statik docs uygulaması ve kullanıcı/geliştirici/proje içerikleri	Runtime DB’den bağımsız build edilir
tests/	Focused unit, contract, DB, reader ve release kontrolleri	Test sonucu tek başına veri yayını değildir

Bugünkü sınır

Şu anda immutable core, shared annotation, lexical/Osmanlıca, tekrar, alignment, heading/note reader katmanları ve 27 active referenceable kind için reference-readiness-v1 repository evidence certificate’ı vardır. Exact/current reference resolution DB/API sözleşmesi mevcuttur.

Henüz tamamlanmış kabul edilmemesi gerekenler:

• authored reference-edge/atıf graph ürünü;
• cross-language ve repeat-canonical projection policy aktivasyonu;
• public full-data artifact ve clean-machine reproducibility release gate’leri;
• production docs deployment ve v1.0.0 code/data tagları.

Bu işler F10 çıkış kapısına kadar ayrı acceptance ve release kanıtı gerektirir. Architecture diyagramındaki bir kutunun bulunması, onun production’da deploy edildiği anlamına gelmez; güncel durum ilgili developer guide, machine contract ve release certificate birlikte okunarak belirlenir.