Kido Bag Overview
Shadcn for Distributed Systems — White-box, zero-dependency distributed systems library and architecture recipes.
Kido Bag (bag.khanhdp.com)
"Shadcn for Distributed Systems"
White-box ownership, zero black-box npm locking, and 0 bytes of unused runtime bloat.
Welcome to Kido Bag, an enterprise-grade collection of 39 Domain Combo Suites (125+ Headless Slices) and 12 Battle-Tested Architecture Blueprints built for high-concurrency Node.js, Bun, TypeScript, and distributed cloud applications.
🎯 Core Philosophy: White-Box Ownership
Modern software development often suffers from dependency sprawl: pulling in heavy npm packages with dozens of transitive dependencies for simple algorithms, lock primitives, or math utilities. When production incidents occur at 3:00 AM, debugging third-party black-box node_modules is painful and slow.
Kido Bag inverts this paradigm:
White-Box Code Ownership
You own the source code. Every slice is plain, readable TypeScript that lives directly in your repository.
0 Unused Bytes
Cherry-pick only the exact functions you need into src/lib/. Zero transitive dependency explosion.
Zero-Lock Standard
Engineered for high concurrency: non-blocking event loops, atomic Lua scripts, and single-flight coalescing.
Battle-Tested Proof
Every blueprint is verified under production loads (up to 100k req/s) with deterministic benchmarks.
⚡ The 3-Tier Taxonomy
Kido Bag is organized into three distinct, composable architectural layers:
┌────────────────────────────────────────────────────────────────────────┐
│ LAYER 3: COMPOSITE SYSTEM BLUEPRINTS (Architecture Blocks & Recipes) │
│ e.g., YouTube View Counter · 5-Stage RAG Pipeline · Flash-Sale Engine │
└───────────────────────────────────┬────────────────────────────────────┘
│ composes
┌───────────────────────────────────▼────────────────────────────────────┐
│ LAYER 2: DOMAIN COMBO SUITES (39 Cohesive Packages in @kido/*) │
│ e.g., @kido/hot-counter · @kido/resilient-cache · @kido/async-sync │
└───────────────────────────────────┬────────────────────────────────────┘
│ contains
┌───────────────────────────────────▼────────────────────────────────────┐
│ LAYER 1: HEADLESS FUNCTIONAL SLICES (125+ Zero-Coupling Modules) │
│ e.g., src/murmurhash · src/single-flight · src/token-bucket · src/hll │
└────────────────────────────────────────────────────────────────────────┘- Layer 1: Headless Functional Slices: Pure, zero-coupling primitives (e.g.,
murmurhash3_32,SingleFlight,TokenBucketLimiter,HyperLogLogCounter). Each module lives in its ownsrc/<slice>/directory with zero cross-slice dependencies. - Layer 2: Domain Combo Suites: 39 cohesive packages in
@kido/*grouping related capabilities into high-level domain toolkits (e.g.,@kido/hot-counter,@kido/resilient-cache,@kido/wallet-ledger). - Layer 3: Composite System Blueprints: 12 complete architecture recipes solving real-world scale challenges (e.g., Twitter Hybrid Feed, YouTube View Counter, Zero-Downtime Blue-Green Deployment).
🚀 The 2 Consumption Modes
You can consume Kido Bag in two ways depending on your project topology:
Mode A: Surgical Cherry-Pick into src/lib/ (The Shadcn Pattern)
For external projects (commerce-api, fintech-core, next-web), copy only the specific slice file or folder into your project.
# Example: Copying the YouTube View Counter slice into your backend
mkdir -p src/lib/hot-counter
cp packages/hot-counter/src/youtube-view-engine.ts src/lib/hot-counter/
cp packages/hot-counter/src/valkey-write-behind.ts src/lib/hot-counter/Benefits:
- Zero npm registry dependencies.
- Full customizability: adapt types, error handlers, and loggers directly in your repo.
- Zero risk of supply-chain attacks or unexpected breaking semver bumps.
🗺️ The 12 Architecture Blueprints
Explore the 12 battle-tested architecture blueprints:
01. YouTube View Counter
Adaptive Slotted Write + HyperLogLog Dedupe + Anti-F5 Bot Defense (100k views/sec).
02. 5-Stage RAG & AI Copilot
Vector Semantic Cache + Hybrid RRF + Dual RPM/TPM Guard (80% cost reduction, TTFT < 350ms).
03. Zero-Oversell Flash Sale
Atomic Redis Lua Reservation + Write-Behind Batching (50k req/s, 0 negative stock).
04. Tiered Storage Lifecycle
AWS SigV4 Presigning + Cloudflare R2 $0 Egress Cap + imgproxy WebP Cold Transcoding.
05. Twitter Hybrid Fanout Feed
Push Write + Pull Read + O(N log K) Binary Max-Heap Cursor Merger (20.6k -> 1.2k req/s).
06. Zero-Downtime Deploy Gate
Caddy Inode-Safe Reload + Shadow Parity Mirroring + Zero Next.js Action 404s.
07. PostgreSQL Logical CDC Outbox
WAL Slot Replication + Sub-5ms Event Lag + Zero-Lock Partition Detaching.
08. Multi-Tenant SaaS Isolation
Prisma RLS Filter + ABAC Policy Engine + Tamper-Proof Surgical Snapshot.
09. Offline-First POS Ledger
UUIDv7 Lamport Conflict Resolution + SWR Confirmed Ledger + Zero Data Loss.
10. 0ms TBT Growth Telemetry
Deferred Analytics + OTLP Vitals Proxy + Redis HyperLogLog (100/100 Lighthouse).
11. Double-Entry FinTech Escrow
Strict Balance Equation Sum(Debit) = Sum(Credit) + VietQR + Anti-Fraud Clawback.
12. WMS Smart Warehouse Putaway
GS1 Barcode Parser + FEFO Batch Expiry + TSP S-Shape 2-Opt Pick Routing (35% travel cut).
🏛️ The 6 Domain Combo Pillars (39 Packages)
The 39 domain suites are organized across 6 functional pillars:
1. Security & Isolation
Tenant Guard, Audit Trail, Anti-Spam & Zalo Mini App Auth.
2. Concurrency & Caching
Resilient Cache, Batch Buffer, Async Sync, Hot Counter, Hybrid Feed & AI Stream.
3. Frontend CWV & Telemetry
SPA Version Guard, Traffic Attribution, Admin UI & Incremental Sitemap.
4. FinTech & Payments
Wallet Ledger, VietQR, Stripe, Airwallex & Circular 78 E-Invoice.
5. E-Commerce & CRM
Discount Loyalty, Bundle Pricing, B2B Credit & Headless State Machine.
6. Logistics & Workforce
BOM Inventory, Geocoding Routing, Shipping Calculator & Crew Scheduler.