Complete architectural overview, deployment guide, API reference, and operations manual for eInvit v123 — Kerala & India's digital event invitation platform. Built entirely on Cloudflare's free stack.

🏗️ Architecture Overview

eInvit is a three-package Cloudflare-native monorepo. All compute runs at the edge — no traditional servers, no Docker, no VMs. The entire platform runs on Cloudflare's free tier.

⚙️ Tech Stack

📁 Project Structure

einvite/
├── apps/
│   ├── public/           # Astro SSR — public invitation pages + landing
│   │   └── src/
│   │       ├── pages/
│   │       │   ├── index.astro           # Landing page (8 communities incl. Corporate)
│   │       │   ├── w/[slug]/index.astro  # Event invitation page
│   │       │   ├── card-studio.astro     # Card Maker Studio entry point
│   │       │   ├── privacy.astro
│   │       │   ├── terms.astro
│   │       │   └── refund.astro
│   │       ├── public/
│   │       │   ├── user-manual.html      # User guide — v123
│   │       │   ├── technical-docs.html   # You are here — v123
│   │       │   └── chatbot/              # Local-KB assistant widget (v89+), no external AI API
│   │       ├── layouts/
│   │       │   └── WeddingLayout.astro   # Theme CSS injection per template
│   │       ├── env.d.ts                  # PUBLIC_API_URL typed (v54)
│   │       └── components/
│   │           ├── blocks/               # Server-rendered Astro components
│   │           │   ├── HeroSection.astro
│   │           │   ├── EventTimeline.astro
│   │           │   ├── CoupleStory.astro
│   │           │   └── VenueMap.astro
│   │           └── islands/              # Hydrated React islands
│   │               ├── CountdownTimer.tsx
│   │               ├── RSVPForm.tsx
│   │               ├── PhotoGallery.tsx
│   │               ├── Guestbook.tsx
│   │               ├── ShareButtons.tsx
│   │               └── MusicPlayer.tsx
│   │
│   └── admin/            # React SPA — admin dashboard (installable PWA, sw.js)
│       └── src/
│           ├── pages/
│           │   ├── LoginPage.tsx
│           │   ├── RegisterPage.tsx      # Plan selection + coupon
│           │   ├── DashboardPage.tsx     # "Your Events"
│           │   ├── NewWeddingPage.tsx    # 4-step wizard, 70+ event types / 8 communities
│           │   ├── WeddingEditorPage.tsx # 6-tab editor
│           │   ├── CardMakerPage.tsx     # DOCX invitation card generator
│           │   ├── TemplatesPage.tsx
│           │   ├── AnalyticsPage.tsx
│           │   ├── AccountPage.tsx       # Plan upgrade + coupon
│           │   └── AdminPanelPage.tsx    # Super-admin: Events, Users, Gallery, Plan Config
│           ├── components/
│           │   ├── layout/AdminLayout.tsx
│           │   └── editor/
│           │       ├── DesignTab.tsx
│           │       ├── ContentTab.tsx        # Gift registry/items, love-story timeline, vendor credits
│           │       ├── GuestsTab.tsx
│           │       ├── EventsTab.tsx
│           │       ├── MediaTab.tsx
│           │       ├── AnalyticsTab.tsx
│           │       ├── SettingsTab.tsx
│           │       └── AIStoryWriterModal.tsx # Local phrase-bank story generator UI
│           ├── lib/storyGenerator.ts     # On-device "AI" story drafts — no external API call
│           ├── vite-env.d.ts             # VITE_* env vars typed (v54)
│           └── stores/auth.ts            # Zustand JWT store
│
├── workers/
│   └── api/              # Cloudflare Worker — Hono REST API — v123.0.0
│       └── src/
│           ├── index.ts              # Main Hono router
│           ├── middleware/auth.ts    # JWT verification middleware (stateless — no DB hit)
│           ├── lib/planConfig.ts     # Two-tier (in-memory + KV) cached plan limits
│           └── routes/
│               ├── auth.ts           # Register, login, me, forgot/reset-password, setup-admin
│               ├── weddings.ts       # CRUD + KV cache invalidation (WEDDING_CACHE_VERSION)
│               ├── guests.ts         # Guest list + batched CSV bulk import
│               ├── rsvp.ts           # Public RSVP (no auth required)
│               ├── media.ts          # Cloudinary upload/delete/reorder (batched)
│               ├── gallery.ts        # Platform-wide real-wedding gallery (admin + public)
│               ├── checkin.ts        # Guest arrival check-in + live day-of updates
│               ├── public.ts         # Public event data (cached in KV + Cloudflare Cache API)
│               ├── payments.ts       # Razorpay + coupon validation
│               ├── admin.ts          # Super-admin endpoints
│               ├── analytics.ts      # Page view tracking (batched aggregate queries)
│               ├── guestbook.ts      # Guestbook CRUD + moderation
│               ├── events.ts         # Sub-events incl. corporate (keynote, workshop…)
│               ├── whatsapp.ts       # Free wa.me link queue + sent/delivered tracking
│               ├── email.ts          # MSG91 bulk guest-facing email invites
│               ├── audio.ts          # Background-music streaming proxy
│               ├── expiry.ts         # Cron: auto-expire pages + telemetry pruning
│               └── og.ts             # OG image generation (resvg-wasm), 7-day Cache API TTL
│
├── schema/
│   ├── 000_full_schema.sql          # Canonical full schema (fresh install)
│   ├── 002_seed.sql                 # 80+ templates across all communities
│   └── 001–039_*.sql                # Incremental migrations v1→v123
│
├── scripts/
│   ├── deploy.sh                    # Full deploy orchestration
│   ├── migrate.sh                   # DB migration runner
│   └── set-secrets.sh               # Interactive secret setup
│
├── tests/
│   ├── test_einvite.py              # Production readiness suite
│   ├── comprehensive_test.py
│   ├── test_production_v67.py
│   └── regression-v92.test.js
│
├── CHANGELOG-V*.md                  # Per-release notes (see Release Highlights)
├── wrangler.toml                    # Root config (reference)
└── pnpm-workspace.yaml

🗄️ Database Schema

D1 (SQLite-compatible) running on Cloudflare. Schema is defined in schema/000_full_schema.sql with 39 incremental migration files for upgrades (v1 → v123).

🌍 Event Communities & Types

eInvit covers 8 community groups and 70+ event types, defined in apps/admin/src/pages/NewWeddingPage.tsx (EVENT_TYPES map) and mirrored in the public landing page's community grid.

Corporate events also expand the events (sub-event) table's allowed types with keynote, workshop, networking, awards_ceremony, and team_activity (migration 029_v93_corporate_event_types.sql), so a single conference invitation page can carry a full multi-track agenda alongside the usual ceremony/reception schedule.

The single_person flag on an event type (e.g. baptism, birthday, vidyarambham, every corporate type) tells the wizard and editor to render a single-name/host field set instead of the two-person (couple) field set — used by getPersonLabel() and isSinglePerson() in NewWeddingPage.tsx.

Event-Specific Templates

Beyond the base community templates, getTemplates() in NewWeddingPage.tsx returns extra event-specific designs layered on top of the community base set — e.g. christian-fhc-white-dove for First Holy Communion, muslim-nikah-gold-moon for Nikah, hindu-upanayanam-saffron for Upanayanam, generic-sadya-banana for Sadya/Feast across any community, and corporate-conference-horizon / corporate-launch-ignite / corporate-awards-spotlight for the Corporate community.

💳 Plan Configuration

All plan limits are stored in the plan_config table and read via workers/api/src/lib/planConfig.ts — there are no hardcoded plan limits in route handlers (since v31). Reads are two-tier cached (in-memory 5 min, KV 10 min) since v71, so this ~6-row table is almost never hit directly on the request hot path. The current values (last synced to the live database in v95, migration 032_v95_plan_config_sync.sql):

To apply these values to a database that has not yet run the v95 sync (e.g. an older fork), run:

wrangler d1 execute TAL_DB --remote --file=schema/032_v95_plan_config_sync.sql

# Verify
wrangler d1 execute TAL_DB --remote --command="SELECT key, max_weddings, max_guests, expiry_days FROM plan_config ORDER BY sort_order"

Relevant environment variable:

# workers/api/wrangler.toml and root wrangler.toml [vars]
MAX_FREE_GUESTS = "5"   # mirrors plan_config.free.max_guests

⚡ Performance & Caching

eInvit runs entirely on Cloudflare's free tier, so every request that avoids a D1 round-trip or a cold Worker invocation directly protects the daily quota. The codebase has been through several dedicated performance passes (most notably v71); this section documents the current state, including a few gaps closed in this latest audit.

Caching layers, fastest to slowest

D1 batching & parallelism

D1 charges a quota unit per query, and each await on a separate .prepare().run() is a full network round-trip from the Worker to D1. The codebase consistently uses env.DB.batch([...]) to ship multiple statements in one round-trip, and Promise.all to parallelise independent reads:

• GET /public/w/:slug — wedding existence-check + full row fetch run as one D1 batch on a cache miss; events/media/guestbook are then fetched in parallel via Promise.all; the view-count increment and page_views insert are batched together and run as a non-blocking background task via waitUntil so they never add latency to the response.
• GET /analytics/overview and GET /analytics/:weddingId — every aggregate query batched into a single D1 round-trip.
• GET /admin/stats — six independent COUNT/GROUP BY queries run with Promise.all.
• PATCH /media/reorder, checkin.ts arrival/list endpoints — already batched.

Other deliberate performance choices

• Stateless auth — JWT verification is pure Web Crypto (HMAC-SHA256), so authenticated requests never touch D1 or KV just to check who's calling. Only login/register pay the PBKDF2 (100,000 iterations) cost.
• Lazy WASM singleton — the @resvg/resvg-wasm OG-image renderer initialises once per Worker isolate (module-scope promise), not per request.
• Cache busting is explicit and targeted — WEDDING_CACHE_VERSION bump + bustPlanConfigCache() invalidate only the KV keys that changed, rather than flushing broadly.
• Telemetry pruning — the daily cron (expiry.ts) deletes page_views/whatsapp_messages older than 90 days and audit_log older than 180 days in the same D1 batch as the expiry job, keeping D1's free-tier row budget in check as the platform grows.
• Composite, query-shaped indexes — e.g. idx_weddings_expiry_cron (partial index for the cron's exact WHERE clause), idx_guests_rsvp on (wedding_id, rsvp_status), idx_page_views_wedding_time on (wedding_id, viewed_at DESC) — every hot-path query in analytics.ts, public.ts, and checkin.ts is covered by an index shaped for its actual WHERE/ORDER BY.

📋 Prerequisites

No Meta Business / WhatsApp Business API account is needed. WhatsApp delivery uses free wa.me links (since v68) — nothing to register or get approved.

🆕 Fresh Installation

Step 1 — Clone & Install

git clone https://github.com/your-org/einvite.git
cd einvite
pnpm install

Step 2 — Authenticate with Cloudflare

wrangler login
# Opens browser → log in → authorise Wrangler

Step 3 — Create Cloudflare Resources

# Create D1 SQLite database
wrangler d1 create TAL_DB
# → Copy the database_id from output

# Create KV namespaces
wrangler kv:namespace create TAL_SESSIONS
wrangler kv:namespace create TAL_CACHE
# → Copy the id values from each output

Step 4 — Update wrangler.toml

Edit workers/api/wrangler.toml and replace placeholder IDs:

[[d1_databases]]
binding       = "DB"
database_name = "TAL_DB"
database_id   = "YOUR_ACTUAL_D1_ID"  # from Step 3

[[kv_namespaces]]
binding = "SESSIONS"
id      = "YOUR_ACTUAL_KV_SESSIONS_ID"

[[kv_namespaces]]
binding = "CACHE"
id      = "YOUR_ACTUAL_KV_CACHE_ID"

[vars]
ENVIRONMENT           = "production"
APP_URL               = "https://einvit.in"
ADMIN_URL             = "https://admin.einvit.in"
CLOUDINARY_CLOUD_NAME = "your-cloudinary-cloud-name"
MAX_FREE_GUESTS       = "5"

Step 5 — Set Secrets

Secrets are stored encrypted in Cloudflare and never appear in your code or config files.

cd workers/api

# Auth
wrangler secret put JWT_SECRET              # 64-char random hex (openssl rand -hex 32)
wrangler secret put ADMIN_BOOTSTRAP_PASSWORD
wrangler secret put ADMIN_SETUP_KEY

# Media
wrangler secret put CLOUDINARY_API_KEY
wrangler secret put CLOUDINARY_API_SECRET

# Payments
wrangler secret put RAZORPAY_KEY_ID
wrangler secret put RAZORPAY_KEY_SECRET
wrangler secret put RAZORPAY_WEBHOOK_SECRET

# Bulk guest email (optional — only needed for the email-invite feature)
wrangler secret put MSG91_AUTH_KEY

# Transactional email — password reset, expiry warnings
wrangler secret put RESEND_API_KEY

cd ../..

Step 6 — Initialize Database

# Full schema (fresh install only — drops & recreates all tables)
pnpm db:fresh

# Seed templates and demo data (includes North/South Indian, International + Corporate templates)
wrangler d1 execute TAL_DB --remote --file=schema/002_seed.sql

# Optional: load 15 curated demo invitations spanning every community and plan tier
wrangler d1 execute TAL_DB --remote --file=schema/021_v59_demo_events.sql
wrangler d1 execute TAL_DB --remote --file=schema/039_v123_demo_events_enrichment.sql

Step 7 — Deploy All Packages

# One command deploys API Worker + Admin SPA + Public Astro site
pnpm deploy:code

Step 8 — Bootstrap Admin Password

curl -X POST https://api.einvit.in/auth/setup-admin \
  -H "Content-Type: application/json" \
  -d '{"setup_key":"<ADMIN_SETUP_KEY>"}'

# Admin login: admin@einvite.app / <ADMIN_BOOTSTRAP_PASSWORD>

Step 9 — Configure Custom Domains

In Cloudflare Dashboard → Pages:

# einvite-public → Custom Domains
einvit.in
www.einvit.in

# einvite-admin → Custom Domains
admin.einvit.in

# Workers & Pages → Routes
api.einvit.in/* → einvite-api (Worker)

🔄 Upgrade Guide

Upgrading to v139 / v140 (Recommended — Full Deploy)

# Safest: runs all pending migrations + redeploys all three packages
pnpm deploy

Upgrading from an Install Older than v123

Migrations are numbered sequentially and are safe to re-run (CREATE TABLE IF NOT EXISTS, INSERT OR IGNORE, idempotent UPDATEs) — just run everything newer than your current schema_version. The highest-impact ones if you're upgrading from anywhere before v90:

pnpm db:migrate:remote   # runs every pending migration in order
pnpm deploy:code         # redeploy API + Admin + Public

Selective Upgrades

# DB migrations only (no code change)
pnpm deploy:db

# Code only (no DB changes)
pnpm deploy:code

# Individual packages
pnpm deploy:api      # Cloudflare Worker only
pnpm deploy:admin    # Admin SPA only
pnpm deploy:public   # Public Astro SSR only

Check Schema Version

pnpm db:version
# Should return: 123

🚀 Deploy Command Reference

✅ Post-Deploy Health Checks

# 1. API health
curl https://api.einvit.in/health
# Expected: {"status":"ok","version":"123.0.0"}

# 2. Plan config (must return 5 plans with current limits)
curl "https://api.einvit.in/payments/plans?show_public=1" | jq '.plans | length'
# Expected: 5
curl "https://api.einvit.in/payments/plans?show_public=1" | jq '.plans[] | {key, max_guests, max_weddings, expiry_days}'
# free.max_guests = 5, free.expiry_days = 8
# premium.expiry_days = 545, premium_plus.expiry_days = 730
# ultimate.max_weddings = 8, ultimate.expiry_days = -1

# 3. Schema version
pnpm db:version
# Expected: 123

# 4. Demo invitation page — note the "demo-" slug prefix
curl -s https://einvit.in/w/demo-riya-rahul-2026 | head -5
# Expected: valid HTML

# 5. Admin login
open https://admin.einvit.in
# demo@einvite.app / TalDemo@2026

# 6. Corporate community spot-check
# Landing page community grid should show 8 communities incl. "Corporate Events"
# New Event wizard → Corporate → should list 5 event types incl. "Conference / Summit"

# 7. Free WhatsApp delivery (no API key needed)
# Editor → Guests → "Send via WhatsApp" should open a wa.me link, not call any Meta API

🌐 API Reference

Base URL: https://api.einvit.in. All authenticated endpoints require Authorization: Bearer <jwt>.

Auth Endpoints

Event Endpoints

Route prefix remains /weddings for backward compatibility — only the JSON error messages and UI labels say "event" (v61).

Guests & RSVP

Media & Gallery

Check-in & Live Updates

Payments

Admin (Super-Admin Only)

☁️ Cloudinary Integration

eInvit uses Cloudinary free tier for all photo, video, and music uploads. The server signs upload requests — API keys are never sent to the browser.

# Environment variables required
CLOUDINARY_CLOUD_NAME = "your-cloud-name"   # in wrangler.toml [vars]
CLOUDINARY_API_KEY    = "..."               # secret
CLOUDINARY_API_SECRET = "..."               # secret

Upload flow: Client calls POST /media/upload → Worker generates a signed Cloudinary upload URL → Client uploads directly to Cloudinary → Cloudinary URL stored in D1.

💳 Razorpay Integration

All Indian payment methods supported: UPI, NetBanking, Debit/Credit Cards, Wallets.

RAZORPAY_KEY_ID      = "rzp_live_..."
RAZORPAY_KEY_SECRET  = "..."
RAZORPAY_WEBHOOK_SECRET = "..."  # Set in Razorpay Dashboard → Webhooks

Payment flow: Client requests order → Worker creates Razorpay order → Client shows Razorpay checkout → On success, Worker verifies HMAC signature → Plan upgraded in D1 → active events' page_expires_at synced to the new plan's expiry_days.

💬 WhatsApp Delivery (wa.me)

Flow: POST /whatsapp/:weddingId/send records the intended send (for the whatsapp_sent_count analytics counter and the per-guest dedup flag) and returns the wa.me/<phone>?text=<encoded message> URL; the admin UI opens it in a new tab/app. Bulk "Send to all pending" iterates guests client-side, opening one wa.me tab per guest with a short delay so the browser doesn't block pop-ups.

Since v53, explicit guest_ids sends respect the per-guest invite_sent_at dedup flag to prevent double-sends; this still applies under the wa.me flow.

📧 Email Delivery — Resend & MSG91

Two providers, split by audience:

RESEND_API_KEY  = "re_..."
MSG91_AUTH_KEY  = "..."

# From address: einvit@proton.me (configure in both dashboards)

routes/email.ts handles the MSG91 bulk send — it chunks the guest list and tracks email_sent_count per event so the editor can show "120 of 300 guests emailed."

⏰ Cron Jobs

Defined in workers/api/wrangler.toml:

[triggers]
crons = ["0 2 * * *"]   # Daily at 02:00 UTC

The daily cron runs routes/expiry.ts which:

• Finds all weddings/events where page_expires_at < NOW(), computed from plan_config.expiry_days for the user's plan (Free=8, Basic=365, Premium=545, Premium+=730, Ultimate=−1/never)
• Sets status = 'expired' on expired pages
• Logs the expiry count to audit_log
• Sends warning emails (via Resend) N days before expiry (configurable via app_config.expiry_warning_days)
• Prunes telemetry in the same run — deletes page_views and whatsapp_messages rows older than 90 days and audit_log rows older than 180 days, keeping D1's free-tier row count from growing unbounded as the platform scales
• Reads RESEND_API_KEY and APP_URL directly from env (typed, no casts since v54)

🗃️ Database Migrations

# Run all pending migrations (idempotent — safe to re-run)
pnpm db:migrate:remote

# Expected "safe" errors on existing DBs:
# "table already exists" → already applied, skip
# "duplicate column name" → column exists, skip

📝 Release Highlights — v62 to v139 (v140)

77 versions shipped between v62 and v139. Rather than reproduce every per-version changelog file here (see the CHANGELOG-V*.md files in the repo root for the complete history), this section summarises the major, currently-live feature additions — i.e. what's actually still true about the app today.

For deprecated/historical context only: v54 removed all as any environment-variable casts; v48–v50 introduced the discount_codes coupon system; v58 added the North Indian, South Indian, and International/NRI communities. None of these required further action by v139.

🔒 Security Architecture

💻 Local Development

# Terminal 1 — API Worker (http://localhost:8787)
cd workers/api
wrangler dev --local --persist-to=../../.wrangler

# Terminal 2 — Public Astro site (http://localhost:4321)
pnpm dev:public

# Terminal 3 — Admin dashboard (http://localhost:5173)
pnpm dev:admin

🧪 Testing

# Install Python dependencies
cd tests && pip install requests

# Run against production API
python test_einvite.py --url https://api.einvit.in

# Run against local dev
python test_einvite.py --url http://localhost:8787

The test suite covers: auth register/login, event CRUD, guest management, RSVP flow, media upload, payments, coupon validation, admin endpoints, and analytics. Additional suites: comprehensive_test.py (broader endpoint coverage), test_production_v67.py (post-v67 wa.me migration regression), and regression-v92.test.js (JS-based regression runner). After upgrading to v123, also manually verify: plan_config returns the current limits, the Corporate community appears in the wizard, and "Send via WhatsApp" opens a wa.me link rather than calling any Meta API.

🔑 Demo Credentials