README.md
Amerik Vitamin — vit-store
Mongolia-based ecommerce store (amerikvitamin.mn) selling US-imported vitamins and supplements (NatureBell, MicroIngredients, Nutricost, and more). Shopping is in Mongolian; prices in MNT (₮). 99% of traffic is mobile.
The monorepo contains four apps — a storefront, an admin dashboard, an API server, and a Facebook Messenger AI shopping agent — plus shared packages, all deployed to Cloudflare via Alchemy (TypeScript IaC).
What's in here
Apps (apps/)
| App | Stack | What it does |
|---|---|---|
storev2 | Astro 5 + SolidJS islands, Tailwind v4, tRPC | Customer-facing storefront. Catalog with brand/category filtering, search, product detail pages, SolidJS cart, checkout (phone → address → delivery zone → confirmation), order tracking, QPay payment, OTP phone login. Neo-brutalist, mobile-first design (see DESIGN.md). |
admin | React 19 + Vite + TanStack Router/Query, tRPC, shadcn/ui | Internal dashboard. Product CRUD with AI-assisted extraction from Amazon URLs, order management, customer records (phone-based), brand/category management, purchase/inventory tracking (Amazon/iHerb imports), payment confirmation (QPay + bank transfer), analytics (sales, top products, PostHog web analytics). |
server | Hono + tRPC + Drizzle, Cloudflare Workers | Central API gateway. Three tRPC routers: /trpc/admin (dashboard), /trpc/store (storefront), /trpc/bot (Messenger admin agent). REST routes for Google OAuth, QPay webhook, Messenger webhook, image uploads. PostgreSQL via Hyperdrive, R2 for images, Upstash Redis Search for product discovery, KV for sessions, rate limiting, and structured logging. |
messenger | Agents SDK Durable Objects + Chat SDK (Zernio) + AI SDK | Customer Messenger bot through Zernio: product search, cart, checkout, QPay/transfer payments, handoff with Telegram alerts. The Telegram admin bot lives here too: POST /telegram/webhook feeds a per-chat Admin Durable Object with the Codemode query tool, image extractors, seven skills, and inline-button callbacks. Inbound admin photos stage in R2 under messenger-inbound/ (auto-expired), and only the key enters history. |
Packages (packages/)
| Package | Purpose |
|---|---|
@vit/api | tRPC routers (admin/store/bot), Drizzle DB queries, integrations (Messenger, QPay, PostHog, Resend, SMS gateway), AI product-extraction pipeline, payment logic. |
@vit/shared | Domain types, Valibot schemas, constants (delivery fee 6,000₮, bank transfer details, status enums). |
Tech stack
- Runtime/dep manager: Bun, Turborepo
- Storefront: Astro 5 (SSR via
@astrojs/cloudflare), SolidJS islands, Tailwind v4 - Admin: React 19, Vite, TanStack Router/Query, shadcn/ui
- Server: Hono, tRPC v11, Drizzle ORM
- Bots:
apps/messenger— Agents SDK + Chat SDK + AI SDK (customer Messenger via Zernio, admin Telegram bot) - Database: PostgreSQL 16 (Drizzle ORM, Hyperdrive connection pooling in prod)
- Storage: Cloudflare R2 (product + inbound images), KV (sessions/cache)
- State: Upstash Redis Search (product discovery); Durable Objects (agent sessions, inbox/outbox, cart/checkout, payments)
- IaC/deploy: Alchemy → Cloudflare Workers (server) and Pages (storev2, admin)
- Lint/format: Vite+ (
vp check: oxfmt + oxlint); type checks viatsc
Getting started
Install dependencies:
| 1 | bun install |
Database
PostgreSQL via Docker (port 5433):
| 1 | bun db:docker:up # docker-compose up -d |
| 2 | bun db:push # push Drizzle schema |
Local dev with Caddy
A Caddyfile provides local TLS domains so OAuth/cookies behave like prod:
| Local domain | Proxies | App |
|---|---|---|
https://vitstore.dev | localhost:4321 | storev2 |
https://api.vitstore.dev | localhost:3006 | server |
https://admin.vitstore.dev | localhost:3005 | admin |
Run everything in dev (Turborepo):
| 1 | bun dev |
Or run a single app:
| 1 | bunx turbo dev --filter=storev2 |
| 2 | bun dev:server |
| 3 | bunx turbo dev --filter=admin |
The messenger worker runs via Wrangler locally:
| 1 | cd apps/messenger && bun dev # wrangler dev |
Deploy
Each app deploys via Alchemy to Cloudflare (prod stage reads ../../.env.prod):
| 1 | bun deploy # turbo deploy (server first, then frontends) |
Available scripts
| Script | Description |
|---|---|
bun dev | Start all apps in dev mode |
bun build | Build all apps |
bun check-types | TypeScript checks across all apps |
bun deploy | Deploy all apps |
bun db:push | Push Drizzle schema to the database |
bun db:migrate / bun db:migrate:local | Run migrations (prod/local) |
bun db:studio / bun db:studio:local | Open Drizzle Studio |
bun db:seed | Seed the database |
bun db:docker:up / bun db:docker:down | Start/stop the Postgres container |
bun lint / bun lint:fix | oxlint / autofix |
bun fmt / bun fmt:fix | oxfmt check / write |
bun check | fmt + lint (what CI runs) |
bun check | oxlint |
bun knip | Dead-code/dependency analysis |
bun quality | check-types + fallow dead-code + fallow health |
Maintenance scripts, product JSON dumps, and QA reports live in the sibling
vit-playground checkout (see its README).
Cache maintenance
Cache maintenance moved to vit-playground/scripts/clear-kv-cache.ts. Every invocation must select local, staging, or production, the analytics scope, and a namespace. An invocation without --confirm is a non-mutating preview; staging and production previews do not contact Cloudflare.
Use a unique namespace name and persistence directory for disposable local work:
| 1 | cd ../vit-playground |
| 2 | bun scripts/clear-kv-cache.ts -- --environment local --scope analytics --namespace-id <unique-local-name> --persist-to <absolute-path> |
| 3 | bun scripts/clear-kv-cache.ts -- --environment local --scope analytics --namespace-id <unique-local-name> --persist-to <absolute-path> --confirm local:<unique-local-name> |
Remote operations additionally require both the account and namespace IDs. Replace placeholders from the intended Alchemy stage output; do not copy identifiers between environments:
| 1 | bun scripts/clear-kv-cache.ts -- --environment staging --scope analytics --account-id <staging-account-id> --namespace-id <staging-namespace-id> |
| 2 | bun scripts/clear-kv-cache.ts -- --environment staging --scope analytics --account-id <staging-account-id> --namespace-id <staging-namespace-id> --confirm staging:<staging-account-id>:<staging-namespace-id> |
| 3 | |
| 4 | bun scripts/clear-kv-cache.ts -- --environment production --scope analytics --account-id <production-account-id> --namespace-id <production-namespace-id> |
| 5 | bun scripts/clear-kv-cache.ts -- --environment production --scope analytics --account-id <production-account-id> --namespace-id <production-namespace-id> --confirm production:<production-account-id>:<production-namespace-id> --confirm-production DELETE-PRODUCTION-CACHE |
The package script disables Bun env-file loading. Wrangler runs from an isolated directory with only its user-level authentication configuration and the explicitly supplied account ID; it does not load the repository .env files.
Playground checkout
One-off scripts, JSON dumps, dogfood/QA reports, and scratch notes live in
../vit-playground as a sibling directory. The app repo keeps source, ADRs,
docs/problems/, and plans/.
Project structure
| 1 | vit-store/ |
| 2 | ├── apps/ |
| 3 | │ ├── storev2/ # Storefront (Astro + SolidJS) |
| 4 | │ ├── admin/ # Admin dashboard (React + TanStack Router) |
| 5 | │ ├── server/ # API gateway (Hono + tRPC, Cloudflare Workers) |
| 6 | │ └── messenger/ # Messenger + Telegram bots (Agents SDK) |
| 7 | ├── packages/ |
| 8 | │ ├── api/ # @vit/api — routers, DB queries, integrations |
| 9 | │ └── shared/ # @vit/shared — types, schemas, constants |
| 10 | ├── docs/ |
| 11 | │ ├── adr/ # Architecture decision records |
| 12 | │ └── agents/ # Agent workflow docs (issue tracker, triage, domain) |
| 13 | ├── CONTEXT.md # Product + domain language (customers, orders, payments, agent surfaces) |
| 14 | ├── PRODUCT.md # Product register, users, brand personality, design principles |
| 15 | ├── DESIGN.md # Storefront design system (colors, type, components) |
| 16 | ├── Caddyfile # Local dev reverse proxy (vitstore.dev / api / admin) |
| 17 | └── docker-compose.yml # Local PostgreSQL 16 |
Further reading
CONTEXT.md— product context, domain language (Customer, Order, Payment, PSID, delivery zones), and agent surfaces.PRODUCT.md— product register, users, brand personality, design principles.DESIGN.md— storefront design system (neo-brutalist, color tokens, typography, components).docs/adr/— architecture decision records (Messenger agent, R2 photo pipeline, payment surface, delivery-zone resolution, admin Codemode agent, etc.).AGENTS.md— agent workflow conventions (issue tracker, triage labels, domain docs, browser automation rules).