Arryt — kuryer logistikasi v1

• Bu nima: oziq-ovqat yetkazib berish tizimi uchun monorepo. Buyurtmalarni qabul qiladi, ularni real vaqtda kuryerlarga taqsimlaydi (geolokatsiya, navbatlar, smenalar, "kunlik garant"ni hisobga olgan holda), zaxira xizmat sifatida Yandex Dostavka bilan integratsiya qiladi, kuryerlarning maoshi/balansini, reytinglar va hisobotlarni hisoblaydi. Yetti sub-servis: api (Elysia backend), queue (BullMQ vorkerlari), crons (rejalashtirilgan vazifalar), duck_api (DuckDB ustida OLAP analitika), transfer_db (ma'lumotlar migratsiyasi), admin (Refine panel), mob (Flutter kuryer ilovasi).
• Turi / holati / roli: web-app (taqsimlangan tizim + mobil) · maintained (~1.5 yil davomida faol ishlagan) · lead — foydalanuvchi Ilhombek bilan co-lead (≈78 va 59 kommit).
• Faollik oynasi: 2023-11-04 → 2025-03-09. Ichida stek evolyutsiyasi bilan uzoq umr ko'rgan production tizim: Prisma→Drizzle migratsiyasi va NestJS'ga o'xshash qatlam→Elysia migratsiyasi katta "silkinish" kommitlarida ko'rinadi (92 fayl +2962/−3418, 35 fayl +2386/−2924, 29 fayl +2002/−2341).

• Tillar: TypeScript (backend/admin), Dart (Flutter mobil), SQL (Postgres + DuckDB).
• Freymvork/kutubxonalar:
• *Backend (api):* Bun + Elysia (node:cluster orqali klasterlangan, prod'da 4 vorker), Apollo GraphQL (@elysiajs/apollo) + REST, Drizzle ORM (drizzle-typebox, drizzle-zod), Postgres (postgres/pg), BullMQ + Bull, ioredis, jose (JWT), bcrypt, geolib (geo matematika), dayjs (utc/timezone), lodash/radash, @evan/duckdb + duck_api'ga gRPC klient.
• *Analitika (duck_api):* DuckDB (duckdb-async) Postgres extension ulanishi bilan (ATTACH … TYPE POSTGRES), pg-logical-replication (CDC), Kafka (kafkajs + node-rdkafka), Hono + Elysia, gRPC server (arryt.proto, Transactions servisi).
• *Admin:* Refine (@refinedev/antd, @refinedev/graphql, kbar) + Ant Design 5, TanStack Query, React 18, Vite, Yandex Maps (react-yandex-maps), Excel/PDF eksport, react-hook-form, i18next.
• *Mobil (mob):* Flutter + flutter_bloc, auto_route, Dio + HTTP/2, Firebase (analytics/crashlytics/messaging/performance/remote_config), flutter_background_service (kuryerning fonda GPS kuzatuvi), flutter_local_notifications, chatview (chat), inappwebview.
• Infra/deploy: Bun runtime (har bir paketda bun.lockb), PM2 (queue/pm2.config.js), klasterlangan API. Navbatlar va kesh uchun Redis. Observability: OpenTelemetry (@opentelemetry/sdk-node, OTLP eksporter), Prometheus (prom-client), Pino + pino-loki (loglar Grafana Loki'ga).
• Ma'lumotlar: Postgres (OLTP, Drizzle orqali asosiy DB), DuckDB (OLAP/analitika, alohida servis), Redis (navbatlar + kesh). api va duck_api o'rtasida transport sifatida gRPC.
• E'tiborga molik tooling: .proto fayllarini to'g'ridan-to'g'ri modul sifatida import qilish uchun maxsus Bun plagin (proto.ts); admin filtrlaridan dinamik Drizzle so'rovlari uchun maxsus parseFilterFields/parseSelectFields qatlami.

NOTE: bu repodagi kommit xabarlari asosan keraksiz ("dddd", "dd", "ddd", "fff", "solved") — xulosalar xabarlardan emas, koddan chiqarilgan.

• Stek migratsiyasi: deyarli teng +/− bilan katta kommitlar (92 fayl +2962/−3418 va hokazo) — backend'ni Bun/Elysia + Drizzle'ga ko'chirish (api ichida hali ham prisma/ artefakti va ~schema.gql bor, drizzle bilan yonma-yon @prisma/client — o'tish davri).
• Buyurtma dispetcherligi: BullMQ'ga asoslangan kuryer tayinlash dvigateli qurildi (~18 navbat/vorker): new_order_notify, try_assign_courier, push_courier_to_queue, set_queue_last_courier, change_courier, clear_courier, order_complete, change_status, store_location (kuryer GPS), send_notification, order_index (qidiruv indeksi), try_set_daily_garant.
• Yandex Dostavka integratsiyasi: check_and_send_yandex + yandex_callback vorkerlari — o'z kuryeri mavjud bo'lmaganda tashqi xizmatga avtomatik topshirish.
• OLAP analitika: duck_api servisi — Postgres jadvallarini DuckDB'ga aks ettiradi + logik replikatsiya/Kafka orqali CDC, agregatlarni (withdraw/transaction hisobotlari) gRPC orqali xizmat qiladi.
• Hisobotlar va hisob-kitoblar: crons/calculate_courier_performance.ts (oylik kuryer reytingi), balance_report_send.ts, send_courier_withdraws_report.ts; orders/controller.ts 3054 qator — garant hisobotlari, yetkazib berish narxlash, jamlanmalar.
• Kuryer mobil ilovasi: fonda GPS, push, chat, BLoC arxitekturasi bilan Flutter.
• Hajm: ~16 oy davomida ikki asosiy dasturchi tomonidan 148 kommit; foydalanuvchi eng katta hissa qo'shuvchi (~78 kommit, uning 3 identifikatorini hisoblaganda).

Barchasi fayllar/difflar bilan tasdiqlangan:

• DuckDB + CDC orqali OLTP→OLAP (duck_api/src/sync_duck.ts, arryt.proto, api/src/lib/duck_grpc.ts): og'ir analitik so'rovlar (kuryer transaction/withdraw tarixi) Postgres'dan DuckDB'ga ko'chirildi. Sinxronizatsiya DuckDB'ning native Postgres extension'idan (INSTALL postgres; ATTACH '…' AS db (TYPE POSTGRES); CREATE TABLE … AS FROM db.<table>) + pg-logical-replication va Kafka orqali streaming delta ishlatadi. Natijalar asosiy API'ga gRPC orqali qaytadi (Transactions.getWithdrawTransactions). → OLTP/OLAP ajratish, CDC va servislararo gRPC tushunchasini namoyish etadi — jiddiy data-engineering ishi.
• Navbatlarda real vaqtli dispetcherlik (queue/index.ts + 16 protsessor): yagona Redis ustida ~18 BullMQ Queue/Worker jufti, "terminal boshiga oxirgi kuryer" navbati bilan kuryer tayinlash pipeline'i, Yandex'ga fallback, user kesh yangilash, qidiruv indekslash. → Vazifalar bo'yicha ajratilgan vorkerlar bilan event-driven tizim loyihalash.
• Kuryer reytingi algoritmi (crons/calculate_courier_performance.ts): "bog'langan terminallar" grafini yechadi (getLinkedTerminalIds), barcha buyurtmalarni to'plamli oladi va lodash orqali guruhlaydi, Promise.all orqali 3 parallel so'rov (count / avg-score / reyting pozitsiyasi uchun ro'yxat), o'rtacha yetkazib berish vaqtini hisoblaydi va kuryerlarni saralaydi (yetkazishlar soni bo'yicha ↓, so'ng o'rtacha vaqt bo'yicha ↑). Har bir kuryer uchun continue bilan try/catch — qisman xatolar butun cron'ni to'xtatib qo'ymaydi. → Production mustahkamligi + noan'anaviy biznes mantiq.
• Observability bilan klasterlangan Elysia (api/src/index.ts, app.ts, package.json): prod'da node:cluster orqali 4 vorker fork qilinadi, OpenTelemetry + OTLP eksport, Prometheus metrikalari (prom-client), Loki'ga strukturaviy loglar (pino-loki). → Yetuk operatsion holat.
• Dinamik so'rov qatlami (api/src/lib/parseFilterFields.ts, parseSelectFields.ts, prepared statement'lar uchun sql.placeholder bilan): admin panel (Refine) filtrlar/maydon tanlovlarini yuboradi → backend Drizzle so'rovlarini xavfsiz quradi. → Har bir kontrollerda copy-paste o'rniga qayta ishlatiladigan abstraksiya.
• `.proto` uchun maxsus Bun plagin (proto.ts): /\.proto$/ filtri bilan onLoadli Bun.plugin, protobuf'ni parslaydi va JS modul qaytaradi (loader "object"). → Bun runtime tooling'ining nostandart bilimi.
• Og'ir Flutter klient (mob/pubspec.yaml): fonda GPS servisi (flutter_background_service + disable_battery_optimization), to'liq Firebase steki, Dio orqali HTTP/2, BLoC, auto_route, o'rnatilgan chat. → Kuryerlar uchun real production mobil ilova, prototip emas.

• Topilgan sessiyalar: bu loyiha uchun lokal Claude Code sessiyalar katalogida 0. Sessiyalar alohida new_arryt loyihasi (va uning mobil sub-katalogi) uchun mavjud — bu qayta yozish, task #37 da qamrab olingan, bu emas.
• AI bilan nima qilingan: bu repo uchun ma'lumot yo'q.
• AI vorkflow patternlari: yo'q — loyiha asosan faol Claude Code ishlatishdan oldin yozilgan (2023–2025, new_arryt'ga o'tishdan avval).

• Miqyos: 7 sub-servisli monorepo, api/src/modules/ ichida ~25 domen moduli (orders, couriers/users, terminals, delivery_pricing, daily_garant, order_transactions, manager_withdraw, brands, organizations, roles/permissions, work_schedules, chart, missed_orders, …).
• Asosiy murakkablik: orders/controller.ts — 3054 qator biznes mantiq; ~18 fon vorkeri; api versiyasi 1.0.50.
• Real yuklama: production oziq-ovqat yetkazib berish (Restaurant chain (UZ)/Restaurant chain (UZ)), Yandex Dostavka integratsiyasi, kuryer maoshi/balansi hisob-kitobi — tizim ~1.5 yil ishladi.
• To'liqlik: backend + analitika + admin + mobil — butun yetkazib berish tsiklini yopadi.