Arxitektura qarorlari: ADR va C4 diagrammalar bilan jamoa dizaynini yozish
Qisqacha: ADR — bitta muhim qaror haqida qisqa yozuv: kontekst, qaror, muqobillar, oqibatlar. C4 — tizimni to'rt darajada chizish usuli: kontekst, konteynerlar, komponentlar, kod. Ikkalasi birga ishlaydi: diagramma "nima qayerda", ADR "nega aynan shunday" degan savolga javob beradi. Bu darsda
jamoacapstone'i uchun yozilgan yettita ADR va uch darajali C4'ni o'qiymiz, keyin o'zingiznikini shu shablon bilan yozasiz.
Bu darsda
- ADR qachon kerak va qachon ortiqcha ekanini ajratasiz.
- Yaxshi ADR'ning to'rt belgisini bilasiz: raqamli kontekst, haqiqiy muqobillar, narx va qayta ko'rish sharti.
- ADR holatlari va "almashtirildi" zanjirini tushuntirasiz, ularni skript bilan tekshirasiz.
- C4 modelining kontekst, konteyner va komponent darajalarini Mermaid'da chizasiz.
jamoauchun o'zdocs/papkangizni boshlaysiz: ADR'lar va C4.
Oldin bilishingiz kerak: Jamoada muloqot: sinxron va asinxron (ADR shabloni), Jamoadagi yangi loyihaga kirish (arxitektura xaritasi), Dasturiy arxitektura va trade-off, API gateway, BFF va service mesh.
1. Nega bu kerak?
Oldingi o'ttiz bitta darsda vazifalar-api ustida o'lchadik: kesh, yuk taqsimlagich (load balancer), replika, saga, ID turlari. Har o'lchovdan bitta xulosa chiqdi. Masalan, "bitta nusxa soniyasiga 393 so'rov beradi" yoki "uuidv4 bilan INSERT bigint'dan ikki barobar sekin".
Endi 38-qismda yangi loyiha boshlanadi — jamoa. Bu jamoalar uchun pullik vazifalar xizmati: bir nechta jamoa, rollar, taklif, obuna. Kodi hali yo'q. Lekin bir qancha qarorlar allaqachon kerak. Bitta server yoki ko'p? Har jamoaga alohida baza yoki umumiy? Sessiya yoki JWT?
Bu qarorlar xulosalari bilan birga yozilmasa, uch narsa bo'ladi. Birinchidan, olti oydan keyin o'zingiz "nega shunday qilgan edim?" deb so'raysiz. Ikkinchidan, yangi jamoadosh har qarorni qayta bahsga qo'yadi. Uchinchidan, sharoit o'zgarganda qaysi qarorni qayta ko'rish kerakligini hech kim bilmaydi.
Hayotiy o'xshatish: uy qurilishining loyiha papkasi. Unda ikki xil hujjat bor. Chizmalar — qaysi xona qayerda, quvur qayerdan o'tadi. Tushuntirish xati — nega poydevor chuqurroq (yer osti suvi yaqin), nega tom tekis emas (qor ko'p). Chizma — C4, tushuntirish xati — ADR. Biri ikkinchisisiz chala.
2. ADR: qarorning yozuvi
2.1 Eslatma
ADR shablonini Jamoada muloqot darsida ko'rgansiz: sarlavha (fe'l bilan), holat, sana, qatnashchilar, keyin to'rt bo'lim — Kontekst, Qaror, Ko'rib chiqilgan muqobillar, Oqibatlar. vazifalar-api da birinchi ADR — LLM modellari uchun alohida circuit breaker. U yerda ADR muloqot vositasi edi: qaror chatda yo'qolmasin.
Bu darsda ADR'ga arxitektor ko'zi bilan qaraymiz. Savol endi "qanday yoziladi" emas, "qachon yoziladi va qanday qilib foydali bo'ladi".
2.2 Qachon ADR yoziladi
Trade-off tafakkuri darsidagi sinovni eslang: qarorni bir yildan keyin o'zgartirsak, nechta fayl, jadval va foydalanuvchiga ta'sir qiladi? ADR — aynan shu sinovdan "qimmat" bo'lib chiqqan qarorlar uchun.
| Qaror | ADR kerakmi | Nega |
|---|---|---|
| bitta server yoki ko'p | ha | deploy, zaxira, SLO o'zgaradi |
| jamoalar ma'lumotini ajratish usuli | ha | har jadval, har so'rov |
| ID turi | ha | URL, API, indekslar |
| funksiya nomi, papka ichidagi fayl | yo'q | bitta PR bilan o'zgaradi |
| kutubxonaning minor versiyasi | yo'q | CHANGELOG yetadi |
Yana bitta belgi: muqobil haqiqatan bormi? Agar boshqa variantni hech kim jiddiy taklif qilmasa, ADR yozish shart emas. ADR — tanlov bo'lgan joyda tanlovning izi.
2.3 jamoa ning yetti qarori
Kanon tajribasida (IlmHamroh, 2026-11) jamoa uchun yettita ADR yozildi. Har biri shu qismdagi bitta o'lchovga tayanadi:
| ADR | Qaror | Asosiy dalil |
|---|---|---|
| 0001 | bitta VPS, modular monolit | 1 nusxa — 393 so'rov/s; yuk ~3 so'rov/s |
| 0002 | umumiy baza, jamoa_id + RLS |
IDOR sinovida RLS ikkinchi qatlam bo'ldi |
| 0003 | server sessiyasi, JWT emas | darhol chiqish va bloklash kerak |
| 0004 | to'lov: webhook — haqiqat manbai | imzosiz webhook buyurtmani "to'landi" qildi |
| 0005 | outbox + BullMQ, Kafka emas | Streams'da 38 xabar tasdiqlanmay qoldi |
| 0006 | ichida bigint, tashqarida UUIDv7 | INSERT 2.6 / 3.9 / 5.5 s |
| 0007 | kesh faqat o'lchov bilan | kesh readiness'ni aldagan edi |
Dalillar ustuniga qarang: birorta ham "yaxshi amaliyot shunday" yo'q. Har birida raqam yoki haqiqiy voqea. Raqamlarning manbasi: Load balancing, IDOR, To'lov xavfsizligi, Servislararo aloqa, Vaqt, tartib va ID, Trade-off tafakkuri (readiness) va Kesh qatlamlari darslari.
2.4 Bitta ADR'ni yaqindan o'qiymiz
ADR-0001 dan bo'laklar. Telefon uchun qatorlar bo'lindi; kanon matnidagi dars raqamlari dars nomi bilan almashtirildi. O'qiyotganda uch joyga qarang: Kontekstdagi raqamlar, "Narxi" qatori va "Qayta ko'rish sharti".
# 0001. jamoa ni bitta VPS'da modular monolit
# sifatida chiqaramiz
- Holat: qabul qilingan
- Sana: 2026-11-09
## Kontekst
Jamoa — 1 dasturchi. Kutilgan yuk: 1-yil oxirida
~200 faol jamoa, ~2 000 foydalanuvchi, cho'qqida
~3 so'rov/s (o'rtacha 0.3). vazifalar-api bitta
jarayonda bir nusxada yuzlab so'rov/s beradi
(Load balancing darsidagi o'lchov).
## Oqibatlar
- Yaxshi: bitta tranzaksiya (to'lov + obuna holati),
oddiy debugging, arzon.
- Narxi: bitta server — yagona nosozlik nuqtasi.
- Qayta ko'rish sharti: cho'qqi > 200 so'rov/s yoki
billing modulining deploy chastotasi qolganlardan
keskin farq qilsa — modul chegarasi bo'yicha ajratish.Bu ADR'da yaxshi ADR'ning to'rt belgisi bor.
- Kontekstda raqam. "Yuk kichik" emas, "cho'qqida ~3 so'rov/s". Raqam bo'lsa, qaror tekshiriladigan bo'ladi.
- Haqiqiy muqobillar. Jadvalda mikroservislar, Kubernetes va PaaS bor — har birining afzalligi ham yozilgan. Faqat kamchilik yozilgan muqobil — "somon odam" (strawman): uni yiqitish uchun qo'yilgan.
- Narx ochiq. "Yagona nosozlik nuqtasi" — qarorning eng og'riqli tomoni, yashirilmagan.
- Qayta ko'rish sharti. "200 so'rov/s dan oshsa" — qachon bu ADR eskiradi. Bu shart bo'lmasa, qaror abadiy qoida bo'lib qoladi.
To'rtinchisi eng kam uchraydi va eng foydalisi. Evolyutsion arxitektura darsida bunday shartlarni avtomatik tekshiriladigan qilamiz.
Tekshirib ko'ring: ADR-0001 kontekstidagi "~3 so'rov/s" raqami qayerdan olingan?
Javob
Halol javob: kanon hujjatida bu raqamning formulasi yo'q. ADR "hisob-kitob" faylini havola qiladi, lekin u faylda jamoa bo'limi yo'q. Bu — hujjatdagi bo'shliq. Taxminiy hisob-kitob darsida bu raqamni faraz va formula bilan qayta tiklaymiz va tekshiramiz. Qoida: ADR'dagi har raqamning manbasi bo'lsin — o'lchov fayli yoki formula.
2.5 Holat va hayot sikli
ADR'ning to'rt holati bor:
stateDiagram-v2
[*] --> taklif
taklif --> qabul: PR merge
taklif --> bekor: rad etildi
qabul --> almashtirilgan: yangi ADR
almashtirilgan --> [*]
bekor --> [*]Diagrammada qabul — "qabul qilingan", bekor — "bekor qilingan". Asosiy qoida: qabul qilingan ADR o'zgartirilmaydi. Qaror o'zgarsa — yangi ADR yoziladi, eskisining holati "0009 bilan almashtirilgan" bo'ladi. Shunda tarix saqlanadi: kim, qachon va nima uchun fikrini o'zgartirgani ko'rinadi.
Mayda tuzatish (imlo, buzilgan havola) — mumkin. Qarorning mazmunini o'zgartirish — yo'q.
jamoa da ikkita ADR hali "taklif": 0006 (ID) va 0007 (kesh). Nega? Ikkalasi ham kod yozilmasdan oldin tasdiqlanishi shart emas. ID turi birinchi migratsiyada, kesh esa birinchi o'lchovda hal bo'ladi. "Taklif" holati — "yo'nalish shu, lekin oxirgi so'z hali aytilmagan" degani.
2.6 ADR ro'yxatini skript bilan tekshirish
ADR'lar ko'paygach, ikki xato paydo bo'ladi: holat noto'g'ri yoziladi ("qabul" va "qabul qilingan" aralashadi) va "almashtirilgan" ADR yo'q raqamga ishora qiladi. Ikkalasini kichik skript ushlaydi. Chiqishda ikki qatorga qarang: bugungi ro'yxat va bir yildan keyingi faraziy ro'yxat.
const HOLATLAR = ["taklif", "qabul qilingan", "bekor qilingan",
"almashtirilgan"];
const adrlar = [
{ n: 1, nom: "bitta VPS, monolit", holat: "qabul qilingan" },
{ n: 2, nom: "multi-tenant: RLS", holat: "qabul qilingan" },
{ n: 3, nom: "sessiya cookie, JWT emas", holat: "qabul qilingan" },
{ n: 4, nom: "to'lov: webhook manba", holat: "qabul qilingan" },
{ n: 5, nom: "outbox + BullMQ", holat: "qabul qilingan" },
{ n: 6, nom: "bigint + UUIDv7", holat: "taklif" },
{ n: 7, nom: "kesh faqat o'lchov bilan", holat: "taklif" },
];
function tekshir(royxat) {
const xatolar = [];
const bor = new Set(royxat.map((a) => a.n));
for (const a of royxat) {
if (!HOLATLAR.includes(a.holat)) {
xatolar.push(`${a.n}: noma'lum holat "${a.holat}"`);
}
if (a.holat === "almashtirilgan" && !bor.has(a.ornida)) {
xatolar.push(`${a.n}: o'rnini bosgan ADR yo'q`);
}
}
return xatolar;
}
console.log("bugun:", tekshir(adrlar));
// faraz: bir yildan keyin ID qarori qayta ko'rildi
const keyin = adrlar.map((a) => a.n === 6
? { ...a, holat: "almashtirilgan", ornida: 9 } : a);
keyin.push({ n: 8, nom: "Redis kesh", holat: "qabul" });
console.log("keyin:", tekshir(keyin));Konsolda:
bugun: []
keyin: [ "6: o'rnini bosgan ADR yo'q", `8: noma'lum holat "qabul"` ]Bugungi yettita ADR toza. Ikkinchi qism — faraz: 0006 "0009 bilan almashtirilgan" deb belgilandi, lekin 0009 hali yozilmagan; 0008 da esa holat qisqartirib yozilgan. Ikkalasi ham ushlandi.
Node massivni ko'rsatganda satr ichida ' bo'lsa, uni backtick bilan o'raydi — shuning uchun ikkinchi xato boshqacha qo'shtirnoqda. Haqiqiy loyihada bu skript ADR fayllarining birinchi qatorlarini o'qiydi va CI'da ishlaydi. Bu docs-as-code g'oyasi: hujjat ham kod kabi tekshiriladi.
2.7 ADR qayerda yashaydi
docs/adr/NNNN-qisqa-nom.md— kod bilan bitta repoda. Kod o'zgarsa, ADR shu PR'da yangilanadi.- Raqam ketma-ket va qayta ishlatilmaydi. Bekor qilingan 0004 ham o'z raqamini saqlaydi.
0000-shablon.md— nusxa olish uchun.- Kod izohidan ADR'ga havola:
// ADR-0005: hodisa outbox orqali. Kodni o'qigan odam "nega" ni topadi.
Wiki yoki Confluence'dagi ADR ham ishlaydi. Lekin kod bilan birga review qilinmaydi va tez eskiradi. Shuning uchun kursda — repoda.
Tekshirib ko'ring: Jamoadosh ADR-0003 (sessiya cookie) ni ochib, "Qaror" bo'limiga "mobil ilova uchun JWT ham" deb qo'shib qo'ydi. Nima noto'g'ri?
Javob
Qabul qilingan ADR'ning mazmuni o'zgartirildi. Endi tarix yo'qoldi: qaror qachon va nega kengaygani ko'rinmaydi. To'g'ri yo'l — yangi ADR (masalan, "0008. Mobil ilova uchun token"), u 0003 ga havola qiladi. Agar yangi qaror eskisini to'liq bekor qilsa, 0003 holati "0008 bilan almashtirilgan" bo'ladi. Qisman kengaytirsa — 0003 o'z kuchida, 0008 unga qo'shimcha.
2.8 ADR review: beshta savol
ADR "taklif" holatida PR bilan keladi. Review qiluvchi kod emas, fikrni tekshiradi. Beshta savol yetarli:
- Kontekstdagi raqamning manbasi bormi? O'lchov fayli, formula yoki voqea havolasi.
- Muqobillar adolatlimi? Har birida kamida bitta haqiqiy afzallik yozilganmi?
- Narx kimga tushadi? Dasturchiga, foydalanuvchiga yoki serverga — aniq aytilganmi?
- Qachon qayta ko'riladi? Raqamli yoki aniq hodisali shart bormi?
- Qaytarish qanchaga tushadi? Bir haftalikmi yoki bir yillikmi — qaror qanchalik "qimmat"?
Beshinchi savol qaror tezligini belgilaydi. Qaytarish arzon bo'lsa, uzoq muhokama shart emas: tanlang, o'lchang, kerak bo'lsa almashtiring. Qaytarish qimmat bo'lsa (RLS yoki ID turi kabi), bir hafta muhokama ham arzon.
2.9 Natijani halol o'qish: raqam to'g'ri ko'chirilganmi
Birinchi savol kanon tajribasida haqiqiy xatoni ushladi. ADR-0006 ning birinchi qoralamasini ko'ring. Unda: "Hamma joyda UUIDv7 — indeks bigint'dan ~40 % katta". Vaqt, tartib va ID darsidagi o'lchovda PK indeksi bigint uchun 11 MB, uuidv7 uchun 15 MB edi. Hisoblaymiz: 15 / 11 ≈ 1.36, ya'ni ~36 % katta.
"40 %" — yaxlitlangan, lekin bir tomonga: rad etilgan variantni biroz yomonroq ko'rsatadi. Bu holda xulosa o'zgarmaydi — farq baribir sezilarli. Lekin odat xavfli: muqobillar jadvalidagi raqamlar har gal "bizning tanlov foydasiga" yaxlitlansa, ADR targ'ibot hujjatiga aylanadi. Review'dan keyin ADR'da shunday yozildi: "36 % katta (o'lchov: 15 MB va 11 MB)". Qoida: raqamni o'lchovdagidek yozing, foizni yoniga qo'ying — o'quvchi o'zi tekshira olsin.
E'tibor bering: bu tuzatish "taklif" holatidagi ADR'da qilindi. Qabul qilinmagan ADR'ni tahrirlash mumkin — u hali muhokama ostida.
Shu ADR'da yana bir yaxshi tafsilot bor: "UUIDv7 dagi vaqt — tartib uchun EMAS". O'lchovda soati bir soat orqada qolgan tugun yaratgan id tartibda birinchi bo'lib qolgan edi. ADR bu topilmani qoidaga aylantirgan: biznes vaqti alohida ustunda. Mana shunday — o'lchov, keyin qaror, keyin qoida.
2.10 Chala ADR'ni beshta savoldan o'tkazamiz
Beshta savolni bitta to'liq misolda ko'ramiz. Jamoadosh Jasur shunday qoralama ochdi:
# 0009. Redis kesh qo'shamiz
- Holat: taklif
## Kontekst
Sayt sekin ishlayapti.
## Qaror
Vazifalar ro'yxatini Redis'da keshlaymiz.
## Oqibatlar
Sayt tezlashadi.Har savolni ketma-ket beramiz:
| Savol | Qoralamada | Nima kerak |
|---|---|---|
| raqam manbasi | "sekin" — raqam yo'q | p95 qancha, qaysi endpoint, qaysi o'lchov |
| muqobillar | bo'lim umuman yo'q | indeks, so'rovni tuzatish, HTTP kesh |
| narx | yozilmagan | eskirgan ma'lumot, invalidatsiya kodi |
| qayta ko'rish | yo'q | "p95 50 ms dan past bo'lsa — keshni olib tashlash" |
Beshinchi savol — "qaytarish qanchaga tushadi?" Kesh qo'shish va olib tashlash arzon, shuning uchun bu ADR'da uzoq muhokama shart emas. Lekin bitta narsa majburiy: o'lchov. Trade-off tafakkuri darsida kesh readiness tekshiruvini aldagan edi: baza o'chiq, /health/ready esa 200. Shuning uchun jamoa ning ADR-0007 si aynan "kesh faqat o'lchov bilan" deydi.
Nima bo'ldi? Qoralama "nima qilamiz" ni aytdi, lekin "nega", "nimaning o'rniga" va "qanchaga" ni aytmadi. Review'dan keyin uchala savolga javob bor — endi bu e'lon emas, tekshiriladigan qaror.
3. C4: tizimni to'rt darajada chizish
3.1 Nega oddiy "quti va strelka" yetmaydi
Jamoadagi yangi loyihaga kirish darsida vazifalar-api ning birinchi diagrammasini chizgansiz. Bunday diagrammaning muammosi — hamma narsa bitta rasmda: foydalanuvchi, nginx, controller, jadval, Redis kaliti. Bunday rasmni mijoz ham, yangi dasturchi ham tushunmaydi.
C4 modeli — Simon Brown taklif qilgan usul: tizimni xaritadagidek kattalashtirib chizish. Har darajada boshqa auditoriya va boshqa savol:
| Daraja | Savol | Kim uchun |
|---|---|---|
| 1. Kontekst | tizim kim bilan gaplashadi | hamma, biznes ham |
| 2. Konteyner | qaysi ilovalar va bazalar | dasturchi, DevOps |
| 3. Komponent | konteyner ichida qaysi modullar | shu konteyner dasturchisi |
| 4. Kod | klasslar, funksiyalar | odatda chizilmaydi |
C4'dagi konteyner — alohida ishga tushadigan yoki ma'lumot saqlaydigan birlik: SPA, API jarayoni, baza, navbat. U Docker konteyneri bilan bir xil narsa emas, garchi ko'pincha mos kelsa ham. Masalan, Postgres — bitta C4 konteyneri, lekin uni Docker'siz ham o'rnatish mumkin.
To'rtinchi daraja amalda chizilmaydi: kodning o'zi uning eng aniq rasmi. jamoa hujjatida ham uchta daraja bor.
Asosiy diagrammalardan tashqari, C4 yordamchi diagrammalarni ham taklif qiladi: tizimlar landshafti, dinamik (ketma-ketlik) va deployment diagrammalari. Ketma-ketlikni siz Mermaid sequenceDiagram bilan ko'p chizgansiz.
3.2 1-daraja: tizim konteksti
Kanon 01-c4.md dagi birinchi diagramma (aynan):
flowchart LR
egasi["Jamoa egasi<br/>(to'laydi, a'zo taklif qiladi)"]
azo["Jamoa a'zosi<br/>(vazifa bilan ishlaydi)"]
admin["Platforma admini<br/>(qo'llab-quvvatlash)"]
jamoa(["jamoa<br/>jamoalar uchun vazifalar SaaS"])
tolov["To'lov provayderi<br/>(Payme / Click / Stripe)"]
pochta["SMTP provayderi<br/>(taklif, tasdiq xatlari)"]
tg["Telegram Bot API<br/>(eslatmalar)"]
google["Google OIDC<br/>(kirish)"]
egasi -->|"obuna, a'zolar, sozlamalar (HTTPS)"| jamoa
azo -->|"vazifalar, izohlar (HTTPS, SSE)"| jamoa
admin -->|"bloklash, yordam (HTTPS, 2FA)"| jamoa
jamoa -->|"to'lov sahifasi, webhook (imzoli)"| tolov
tolov -->|"to'lov hodisasi (webhook)"| jamoa
jamoa -->|"xat (SMTP, STARTTLS)"| pochta
jamoa -->|"xabar (HTTPS)"| tg
jamoa -->|"OIDC (PKCE)"| googleMarkazdagi yumaloq quti — bizning tizim, bitta quti. Ichida nima borligi bu darajada muhim emas. Chapda — odamlar (rollar), o'ngda — tashqi tizimlar. Har strelkada ikki narsa yozilgan: nima o'tadi va qanday (protokol).
Bu diagrammadan nimalarni o'qish mumkin:
- Uchta rol bor. Admin 2FA bilan kiradi — demak, admin uchun alohida xavfsizlik talabi bor.
- To'lov provayderi bilan ikki tomonlama aloqa: biz sahifaga yo'naltiramiz, u webhook yuboradi. Bu ADR-0004 ning sababi.
- To'rtta tashqi tizim — to'rtta "tashqi nosozlik nuqtasi". Har biri o'chsa nima bo'lishini runbook aytishi kerak.
3.3 2-daraja: konteynerlar
Endi jamoa qutisini ochamiz:
flowchart TB
subgraph mijoz["Brauzer / telefon"]
web["web — React 19 SPA (Vite)<br/>statik fayllar"]
end
subgraph vps["VPS (Docker Compose, bitta server — ADR-0001)"]
nginx["nginx — TLS, CSP, rate limit,<br/>statik web, /v1 → api"]
api["api — NestJS 12 (Node 24)<br/>REST /v1, SSE; stateless, 2 nusxa"]
ishchi["ishchi — BullMQ consumer<br/>outbox relay, xat, webhook, billing"]
db[("Postgres 18<br/>tenant_id + RLS (ADR-0002)")]
redis[("Redis 8<br/>sessiya keshi, cheklagich, BullMQ")]
s3[("S3-mos ombor<br/>fayl ilovalari")]
end
web -->|"HTTPS"| nginx
nginx -->|"HTTP 127.0.0.1"| api
api -->|"SQL (vazifalar_api roli, RLS)"| db
api -->|"RESP"| redis
api -->|"presigned URL"| s3
ishchi -->|"SQL (outbox, BYPASSRLS yo'q — tenant bo'yicha)"| db
ishchi -->|"navbat"| redis
ishchi -->|"SMTP / HTTPS"| tashqi["tashqi: SMTP, Telegram, to'lov provayderi"]
tashqi -->|"webhook"| nginxStrelkalardagi qisqa nomlar oldingi qismlardan tanish. Eslatma uchun: SSE — serverdan brauzerga uzluksiz xabar oqimi; RESP — Redis'ning o'z protokoli; presigned URL — fayl omboriga vaqtinchalik ruxsatli havola, fayl API orqali o'tmaydi; BYPASSRLS — Postgres rolining RLS'ni chetlab o'tish huquqi.
Diagrammani yuqoridan pastga o'qing. Brauzer faqat nginx bilan gaplashadi. nginx ichkariga 127.0.0.1 orqali uzatadi — API tashqariga ochiq emas. API va ishchi — bitta koddan ikki jarayon (33-qismdagi ishchi.ts kabi). Ma'lumot uchta joyda: Postgres, Redis, fayl ombori.
Ikki narsaga e'tibor bering:
- Diagrammada ADR raqamlari bor. "bitta server — ADR-0001", "RLS (ADR-0002)". Diagramma "nima", ADR "nega" — ular bir-biriga havola qiladi.
- Strelkada xavfsizlik tafsiloti bor: "BYPASSRLS yo'q", "vazifalar_api roli". Konteyner darajasida qaysi rol bilan ulanish — arxitektura qarori, chunki IDOR darsida ko'rganingizdek, superuser bilan ulangan ilova RLS'ni chetlab o'tadi.
Bitta kamchilik ham bor: diagrammada "2 nusxa" yozilgan, lekin ikki nusxa orasidagi balanslash ko'rinmaydi. Bu ataylab: nusxalar soni deployment diagrammasining ishi.
Tekshirib ko'ring: Nega diagrammada
tashqiqutisidan nginx'ga strelka bor, API'ga emas?
Javob
To'lov provayderining webhook'i ham oddiy HTTPS so'rov: u internetdan keladi va avval nginx'ga tushadi (TLS, tezlik cheklovi). API to'g'ridan-to'g'ri ochiq emas. Agar diagrammada strelka API'ga chizilsa, o'quvchi "API internetga ochiq" deb o'ylaydi — bu noto'g'ri va xavfli taxmin.
3.4 3-daraja: api ning komponentlari
Uchinchi daraja faqat api konteyneri uchun chizilgan:
flowchart LR
subgraph api["api (modular monolit — ADR-0001)"]
auth["auth<br/>sessiya, OIDC, 2FA"]
tenant["jamoalar<br/>tenant, a'zolik, rollar, taklif"]
vazifa["vazifalar<br/>vazifa, izoh, teg, fayl"]
billing["billing<br/>tarif, obuna, limitlar, invoice"]
bildir["bildirishnomalar<br/>email, telegram, SSE"]
umumiy["umumiy (shared kernel)<br/>xatolar, tekshir, log, RLS yordamchisi"]
end
vazifa -->|"tenant konteksti (CLS)"| tenant
vazifa -->|"limit so'rovi (port)"| billing
billing -->|"hodisa: obuna.ozgardi (outbox)"| bildir
tenant -->|"hodisa: azo.taklif_qilindi"| bildir
auth --> umumiy
tenant --> umumiy
vazifa --> umumiy
billing --> umumiyBu daraja Coupling va cohesion darsining natijasini rasmga aylantiradi. umumiy — hamma unga bog'liq, u hech kimga bog'liq emas. Modullar bir-biriga faqat port yoki hodisa orqali murojaat qiladi. Chegara qoidasi kanon hujjatida yozilgan: modul boshqa modulning ichki fayllarini import qilmaydi — faqat index.ts yoki hodisa. Bu qoida ESLint bilan majburlanadi, xuddi vazifalar-api dagi umumiy qoidasi kabi.
O'lchovdan kelgan sabab: vazifalar-api da 22 ta modul jufti ikki tomonlama bog'liq edi. jamoa da bu boshidan yopiladi — keyin tozalash qimmatroq.
Strelka turlariga qarang. Uzluksiz strelka bilan "tenant konteksti" va "limit so'rovi" — sinxron chaqiruv. "hodisa: …" — asinxron, outbox orqali (Event-driven arxitektura). Bitta diagrammada ikki xil aloqa — strelka yozuvi ularni farqlaydi.
3.5 Biz shunday xato qildik: diagramma noto'g'ri ADR'ga ishora qilgan
Kanon 01-c4.md ning birinchi versiyasida bu diagrammaning subgraph sarlavhasi api (modular monolit — ADR-0003) edi. ADR-0003 esa sessiya cookie haqida. Modular monolit — ADR-0001. Xato review'da topildi va hujjatda tuzatildi; yuqoridagi diagramma — tuzatilgan versiya.
Kichik xato, lekin ibratli. Diagramma va ADR alohida fayllarda yashaydi, ular orasidagi havola hech narsa bilan tekshirilmaydi. ADR'lar qayta raqamlansa yoki yangisi qo'shilsa, bunday havolalar jim eskiradi. Ikkita chora bor:
- havolada raqam bilan birga qisqa nom:
ADR-0001 (modular monolit)— xato ko'zga tashlanadi; - skript: diagrammadagi har
ADR-NNNNuchun fayl borligini va uning sarlavhasida kalit so'z borligini tekshirish. Design doc, runbook va postmortem darsida shunday havola tekshiruvchisini yozamiz.
3.6 Diagramma kod sifatida
Kanon diagrammalari Mermaid'da — matn fayli. Afzalliklari:
- Git diff'da ko'rinadi: "nginx → api strelkasiga 127.0.0.1 qo'shildi".
- PR'da review qilinadi, xuddi kod kabi.
- Kurs sayti ham, GitHub ham uni rasmga aylantiradi.
Kamchiligi: joylashuvni boshqarish qiyin. Mermaid tugunlarni o'zi joylashtiradi, katta diagramma chalkash chiqadi. Shuning uchun har darajada 12 tadan kam quti — bu ham telefon uchun, ham tushunish uchun yaxshi chegara.
Mermaid'da C4 uchun maxsus sintaksis ham bor (C4Context, C4Container). Kanon oddiy flowchart ni tanladi: u hamma joyda bir xil chiziladi va o'quvchi uni allaqachon biladi. Boshqa vositalar — Structurizr DSL (Simon Brown'ning o'z vositasi) va PlantUML — bitta modeldan bir nechta diagramma chiqaradi. Katta tizimda bu foydali; jamoa uchun ortiqcha.
4. ADR va C4 birga: o'qish tartibi
Yangi odam jamoa/docs/ ni qanday o'qiydi:
flowchart LR
R[README] --> RFC[RFC-0001]
RFC --> K[C4: kontekst]
K --> C[C4: konteyner]
C --> A[ADR'lar]
C --> M[C4: komponent]
M --> D[DDD lug'ati]Avval RFC — "nima qilyapmiz va nega". Keyin C4 kattalashtirib boradi. Har qutida ADR raqami — "bu yerda qaror bor, o'qing". Komponent darajasidan keyin umumiy til lug'ati (DDD strategik darsida yozilgan 02-ddd.md).
Kanon jamoa-dizayn/README.md aynan shu tartibni jadval bilan beradi. Fayllar: RFC-0001-jamoa-mvp.md, 01-c4.md, 02-ddd.md, adr/0001–0007, runbook.md. RFC va runbook — keyingi darsda.
4.1 Uch hujjat — uch vazifa
Boshida bu hujjatlar bir-biriga o'xshab ko'rinadi. Farqi — vaqt va hajmda:
| Hujjat | Nimani aytadi | Qachon o'zgaradi |
|---|---|---|
| ADR | bitta qaror va uning sababi | hech qachon (yangisi yoziladi) |
| C4 diagramma | tizim hozir qanday tuzilgan | har tuzilma o'zgarishida |
| RFC (design doc) | katta ish rejasi, ko'p qaror birga | muhokama tugaguncha |
| ARXITEKTURA.md | yangi odam uchun xarita | vaqti-vaqti bilan |
ADR — tarix: u o'tmishdagi qarorni o'sha kungi bilim bilan saqlaydi. C4 esa — bugungi holat, u doim yangilanib turadi. Shuning uchun diagrammada eski qutini "tarix uchun" qoldirmang: tarix ADR'larda.
vazifalar-api da to'rttalasining namunasi bor: docs/adr/0001-har-modelga-alohida-breaker.md, docs/ARXITEKTURA.md (Mermaid diagrammalari bilan), docs/talablar/takrorlanuvchi-vazifalar.md (talab hujjati). jamoa ning RFC'si — yangi tur, uni keyingi darsda o'qiymiz.
4.2 Diagramma qachon yangilanadi
Oddiy qoida: PR yangi konteyner, yangi tashqi tizim yoki modullar orasida yangi aloqa qo'shsa — C4 shu PR'da yangilanadi. Review qiluvchi buni so'raydi: "Redis'ga yangi navbat qo'shildi — konteyner diagrammasida bormi?".
Komponent darajasi tezroq eskiradi, chunki modullar tez-tez o'zgaradi. Shuning uchun uni faqat eng muhim konteyner (api) uchun chizing. Kontekst darajasi esa yillar davomida deyarli o'zgarmaydi — uni bir marta yaxshilab chizish yetadi.
5. Loyiha qadami: jamoa/docs/
38-qismda jamoa yangi repo bo'ladi. Hujjatni hozir boshlang — kod yo'q paytda qaror arzon.
- Repo ildizida
docs/adr/papka va0000-shablon.md(Jamoada muloqot darsidagi shablon). - Yettita ADR. Kanondagilarni ko'chirmang — o'z qarorlaringizni yozing. Masalan, siz Stripe'siz faqat Payme'ni tanlashingiz mumkin; unda ADR-0004 boshqacha bo'ladi. Har kontekstda kamida bitta raqam (shu qism darslaridan), har muqobilda afzallik ham.
docs/01-c4.md— uch daraja. Har strelkada nima va qanday; har qarorli qutida ADR raqami va qisqa nomi.- «ADR ro'yxatini skript bilan tekshirish» bo'limidagi tekshiruvni
scripts/adr-tekshir.mjsqiling: udocs/adr/*.mddan raqam va holatni o'qisin.
Commit xabari, masalan: docs(adr): jamoa uchun 0001–0007 va C4 diagrammalar.
6. Ko'p uchraydigan xatolar
6.1 Har narsaga ADR
Kutubxona patch versiyasi, papka nomi — ADR emas. ADR'lar ko'payib ketsa, muhimlari ularning orasida yo'qoladi va hech kim o'qimaydi.
6.2 Qaror qabul qilingandan keyin yozish
"Kodni yozdik, endi ADR yozib qo'yamiz" — muqobillar jadvali sun'iy chiqadi. ADR qarordan oldin, "taklif" holatida yoziladi va PR'da muhokama qilinadi.
6.3 Raqamsiz kontekst
"Yuk katta bo'lishi mumkin" — tekshirib bo'lmaydi. "Cho'qqida ~3 so'rov/s, formulasi …" — tekshiriladi va qayta ko'rish shartiga aylanadi.
6.4 Qabul qilingan ADR'ni tahrirlash
Qaror o'zgarsa — yangi ADR va "almashtirilgan" holati. Eskisini o'chirish yoki qayta yozish tarixni yo'q qiladi.
6.5 Bitta diagrammada hamma daraja
Foydalanuvchi, jadval va Redis kaliti bitta rasmda — hech kimga foydasiz. Har auditoriyaga o'z darajasi.
6.6 Yozuvsiz strelka
A --> B — nima o'tadi? Sinxronmi? Qaysi protokol? Kanondagi komponent diagrammasida ham to'rtta shunday strelka bor — ular umumiy ga. Bu yerda ma'nosi aniq ("import qiladi"), lekin qoida sifatida yozuvsiz strelkani qoldirmang. 3-mashqda ularni skript bilan topasiz.
6.7 Texnologiyasiz konteyner
"Backend", "Database" deb yozilgan qutilar hech narsa aytmaydi. Konteyner darajasida texnologiya va versiya muhim: "Postgres 18", "NestJS 12 (Node 24)", "Redis 8". Kanon diagrammasidagi har qutida shunday. Versiya o'zgarsa (masalan, Postgres 19 ga ko'chish), bu ham diagrammada ko'rinadi va ehtimol yangi ADR talab qiladi.
6.8 Diagrammada sirli qisqartmalar
"BFF", "GW", "SVC-2" — siz bilasiz, yangi odam bilmaydi. Qisqartma kerak bo'lsa, diagramma ostida izohlar ro'yxati (legend) bering. C4 muallifi ham har diagrammaga kalit (legend) qo'yishni tavsiya qiladi: qaysi shakl odam, qaysi biri baza, uzluksiz va uzuq chiziq nimani anglatadi.
7. Mashqlar
Mashqlar kurs/mashqlar/36/32-adr-c4/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik).
1-mashq (oson): bo'shliqlarni to'ldiring
- Qabul qilingan ADR o'zgarsa, yangi ADR yoziladi, eskisining holati —
- C4'ning tizim kim bilan gaplashishini ko'rsatadigan birinchi darajasi —
jamoada ikki holati hali "taklif" bo'lgan ADR'lardan biri — ID yoki- ADR-0001 qaysi cho'qqi yukda qayta ko'riladi (so'rov/s) —
- Odatda chizilmaydigan C4 darajasi —
Yechim
- almashtirilgan — "NNNN bilan almashtirilgan" deb, yangi raqam bilan.
- kontekst — tizim bitta quti, atrofida odamlar va tashqi tizimlar.
- kesh — ADR-0007; ikkinchisi ADR-0006 (ID).
- 200 — undan oshsa, modul chegarasi bo'yicha ajratish ko'riladi.
- kod — kodning o'zi eng aniq rasm.
2-mashq (o'rta): ADR bo'limlarini tekshirish
tekshirADR(md) funksiyasini yozing. U ADR matnini olib uch narsani qaytarsin: sarlavha # NNNN. (to'rt raqam, nuqta, bo'shliq) bilan boshlanadimi, **Sana:** qatori bormi va to'rt majburiy bo'limdan qaysilari yo'q. Quyidagi qoralamada sinang (u ataylab chala).
Ishora: ^## (.+)$ naqshi gm bayroqlari bilan har ## sarlavhani topadi, matchAll hammasini qaytaradi (Regex amaliyotda).
# 0008. Fayllarni S3-mos omborda saqlaymiz
- **Holat:** taklif
## Kontekst
Fayl ilovalari 50 MB gacha, jamoa 200 ta.
## Qaror
Presigned URL bilan to'g'ridan-to'g'ri yuklash.
## Oqibatlar
Server fayl trafigini ko'rmaydi.Yechim
const KERAK = ["Kontekst", "Qaror", "Ko'rib chiqilgan muqobillar",
"Oqibatlar"];
const qoralama = `# 0008. Fayllarni S3-mos omborda saqlaymiz
- **Holat:** taklif
## Kontekst
Fayl ilovalari 50 MB gacha, jamoa 200 ta.
## Qaror
Presigned URL bilan to'g'ridan-to'g'ri yuklash.
## Oqibatlar
Server fayl trafigini ko'rmaydi.`;
function tekshirADR(md) {
const bolimlar = [...md.matchAll(/^## (.+)$/gm)].map((m) => m[1]);
const yoq = KERAK.filter((b) => !bolimlar.includes(b));
const sarlavha = /^# (\d{4})\. /.test(md);
const sana = /\*\*Sana:\*\*/.test(md);
return { yoq, sarlavha, sana };
}
const n = tekshirADR(qoralama);
console.log(`raqamli sarlavha: ${n.sarlavha}, sana: ${n.sana}`);
console.log(`yo'q bo'limlar: ${n.yoq.join(", ") || "-"}`);Konsolda:
raqamli sarlavha: true, sana: false
yo'q bo'limlar: Ko'rib chiqilgan muqobillarQoralamada ikki kamchilik bor: sana yo'q va muqobillar jadvali yo'q. Ikkinchisi muhimroq: muqobilsiz ADR — qaror emas, e'lon. m bayrog'isiz ^ faqat butun matn boshini bildiradi va bitta ham bo'lim topilmasdi.
3-mashq (qiyin): yozuvsiz strelkalar
Mermaid flowchart matnidan strelkalarni ajratib oling. A -->|"yozuv"| B va A --> B shakllarini tushuning. Ikki natija chiqaring: yozuvsiz strelkalar ro'yxati va eng ko'p kiruvchi strelkasi bor tugun. Kanon komponent diagrammasidagi sakkizta strelkada sinang.
Ishora: bitta regex ikki shaklni ham ushlay oladi — yozuv qismini (?:…)? bilan ixtiyoriy qiling. Hisoblash uchun Map, tartiblash uchun toSorted (Nusxa bilan o'zgartirish).
Yechim
const diagramma = `
vazifa -->|"tenant konteksti (CLS)"| tenant
vazifa -->|"limit so'rovi (port)"| billing
billing -->|"hodisa: obuna.ozgardi (outbox)"| bildir
tenant -->|"hodisa: azo.taklif_qilindi"| bildir
auth --> umumiy
tenant --> umumiy
vazifa --> umumiy
billing --> umumiy`;
const QIRRA = /^\s*(\w+)\s*-->(?:\|"([^"]*)"\|)?\s*(\w+)\s*$/;
function tahlil(matn) {
const yozuvsiz = [];
const kiruvchi = new Map();
for (const qator of matn.split("\n")) {
const m = qator.match(QIRRA);
if (!m) continue;
const [, dan, yozuv, ga] = m;
if (!yozuv) yozuvsiz.push(`${dan} -> ${ga}`);
kiruvchi.set(ga, (kiruvchi.get(ga) ?? 0) + 1);
}
return { yozuvsiz, kiruvchi };
}
const { yozuvsiz, kiruvchi } = tahlil(diagramma);
console.log(`yozuvsiz strelkalar: ${yozuvsiz.length}`);
console.log(yozuvsiz.join(", "));
const top = [...kiruvchi].toSorted((a, b) => b[1] - a[1])[0];
console.log(`eng ko'p kiruvchi: ${top[0]} (${top[1]})`);Konsolda:
yozuvsiz strelkalar: 4
auth -> umumiy, tenant -> umumiy, vazifa -> umumiy, billing -> umumiy
eng ko'p kiruvchi: umumiy (4)To'rtta yozuvsiz strelkaning hammasi umumiy ga — va umumiy eng ko'p kiruvchi tugun. Bu Coupling va cohesion darsidagi Ca (kiruvchi bog'liqlik) ning diagrammadagi ko'rinishi: ko'p modul bog'liq bo'lgan joy barqaror bo'lishi kerak. Tavsiya: bu strelkalarga ham yozuv qo'shing, masalan "import (xatolar, log)". Regex faqat oddiy nomli tugunlarni tushunadi — A["…"] --> B kabi qatorlarni o'tkazib yuboradi; haqiqiy vosita uchun Mermaid'ning o'z tahlilchisi kerak.
8. Real ishda
- Ochiq loyihalar. Ko'p ochiq loyihalarda
docs/adr/yokidocs/decisions/papkasi bor. ADR shablonlari va vositalari to'plami — adr.github.io. - Thoughtworks Technology Radar "lightweight ADR" amaliyotini 2017–2018 yillarda "Adopt" (qo'llang) halqasiga qo'ygan. Hozirgi nashrda bu yozuv ko'rsatilmaydi, lekin oxirgi bahosi — "Adopt" (2018-yil may).
- Arxitektura review. Katta kompaniyalarda yangi servis ADR va C4 konteyner diagrammasisiz review'dan o'tmaydi.
- Intervyu. System design intervyusida birinchi chiziladigan narsa — aslida C4 konteyner diagrammasi: mijoz, yuk taqsimlagich, servislar, baza, kesh. Buni System design metodi darsida qilamiz.
Xulosa
- ADR — qimmat va muqobili bor qaror uchun; mayda tanlovlar uchun emas.
- Yaxshi ADR: kontekstda raqam, haqiqiy muqobillar, ochiq narx va qayta ko'rish sharti.
- Qabul qilingan ADR o'zgartirilmaydi — yangisi yoziladi, eskisi "almashtirilgan".
- C4 — to'rt daraja: kontekst, konteyner, komponent, kod; har biri o'z auditoriyasi uchun.
- Diagramma va ADR bir-biriga havola qiladi; havolani skript tekshirmasa, u eskiradi (C4 ning birinchi versiyasidagi ADR-0003 xatosi).
Keyingi dars: Design doc (RFC), runbook va postmortem yozish — jamoa ning RFC'sini bo'lim-bo'lim o'qiymiz va hujjatlar orasidagi havolalarni skript bilan tekshiramiz.
Manbalar
- Michael Nygard — Documenting Architecture Decisions (2011): https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions (tekshirildi, 2026-11)
- ADR shablonlari va vositalari: https://adr.github.io/ (tekshirildi, 2026-11)
- Simon Brown — The C4 model: https://c4model.com/, https://c4model.com/diagrams/notation (tekshirildi, 2026-11)
- Thoughtworks Technology Radar — Lightweight ADR: https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records (tekshirildi, 2026-11)
- Mermaid — C4 diagrammalari: https://mermaid.js.org/syntax/c4.html (tekshirildi, 2026-11)
- Kurs tajribasi (IlmHamroh, 2026-11):
jamoadizayn hujjati — 7 ADR, uch darajali C4; dalillardagi raqamlar shu qism o'lchovlaridan. Mashq yechimlari — biz ishga tushirdik (2026-11-09).
Izohlar · 0
Izoh yozish uchun kiring.