Kaartje: یک کرهی زمین سهبعدی برای نمایش کارتپستال
فرانتاند
جاوااسکریپت
هوش مصنوعیخلاصهٔ کاملتر
تیم Spatie (Nick و Dries) در یه هکاتون یکروزه تصمیم گرفتن صفحهی کارتپستال سایتشون رو از یه لیست ساده به چیز جالبتری تبدیل کنن. نتیجه شد Kaartje — یه کرهی زمین سهبعدی که هر کارتپستال رو روی موقعیت تقریبی شهر فرستندهاش نمایش میده. علاوه بر وب، یه اپ Expo هم ساختن که اجازه میده کارتپستال فیزیکی رو عکاسی و مستقیم به سیستم ارسال کنن.
استک فنی پروژه سبک و آشناست: سرور API با Bun (بدون فریمورک)، پایگاه داده SQLite، فرانتاند با Astro + React، اپ موبایل با Expo، و یه پکیج مشترک برای لاجیک و کامپوننتهای UI. همه چیز داخل یه monorepo با npm workspaces مدیریت میشه. کرهی سهبعدی با react-three-fiber ساخته شده و همزمان هم روی وب و هم داخل اپ Expo کار میکنه.
برای سرعت بخشیدن به توسعه از Claude (هوش مصنوعی Anthropic) کمک گرفتن، اما به شکل کنترلشده: هر فاز پروژه جدا بود، با معیارهای پذیرش مشخص، و بعد از هر مرحله خودشون کد رو بررسی میکردن. حدود ۴ ساعت طول کشید تا به یه نسخهی کارکرد برسن، بعدش polish دستی و بهینهسازی شروع شد.
بزرگترین چالش فنی، رندر صدها کارت متحرک روی کره بود. پیادهسازی اولیه هر کارت رو بهصورت یه THREE.Mesh جداگانه رندر میکرد — با ۵۰ کارت سنگین میشد، با ۱۰۰ تا فریم میافتاد. راهحل GPU instancing بود: بهجای صدها draw call جداگانه، یه THREE.InstancedMesh واحد با یه geometry و یه material. موقعیت، اندازه و تکسچر هر کارت بهعنوان attribute پاس داده میشه.
// Each stamp gets a layer index; the shader samples the right one
const layerIndex = atlas.allocateLayer(card.frontImageUrl);برای اینکه هر کارت تصویر مخصوص خودش رو داشته باشه از DataArrayTexture استفاده کردن — یه تکسچر چندلایه که هر لایهاش تصویر یه کارتپستاله. کلاس StampTextureAtlas این pool از لایههای 128×86 RGBA رو مدیریت میکنه و به هر کارت یه layer index اختصاص میده که shader موقع رندر ازش استفاده میکنه.
چند تصمیم کوچیکتر هم جمعاً تفاوت زیادی ایجاد کردن: بارگذاری تصاویر بهصورت دستهبندیشده با فاصلهی ۳۰۰ms برای جلوگیری از flood شدن سرور، استفاده از useRef بهجای useState در اپ موبایل برای جلوگیری از re-render اضافه در فلوی ۵ صفحهای ثبت کارت، یه زنجیرهی fallback برای موقعیت جغرافیایی (GPS → centroid کشور → آنتورپ)، و clamp کردن time delta به حداکثر 0.1 ثانیه تا بعد از تغییر تب مرورگر، کره ناگهان نچرخه.
نکات کلیدی:
- Kaartje یه کرهی سهبعدی هست که کارتپستالها رو روی موقعیت فرستنده نمایش میده
- استک: Bun + SQLite + Astro/React + Expo در یه monorepo
- GPU instancing با THREE.InstancedMesh مشکل رندر صدها کارت رو حل کرد
- DataArrayTexture امکان داشتن تصویر مجزا برای هر کارت رو در یه material واحد فراهم میکنه
- AI (Claude) برای سرعت توسعه استفاده شد، با کنترل کامل در هر مرحله
- نسخهی دمو در kaartje.earth قابل مشاهدهست
