What Plankro actually is, in one paragraph

Plankro is a website where a Delhi couple (or a group of friends) answers a few questions — which neighborhood, what mood, what budget — and gets a ready-made 3-stop evening plan in under a minute: a café, then dinner, then something to do, all within a 35-minute radius of each other. Every plan is a shareable "Room" with a link you can send on WhatsApp. The business charges ₹199/month for extras (insider tips, café discounts, a WhatsApp panic button, table pre-booking) — see the Feature Tracker below for exactly which of those extras are real today versus still just marketing copy.

Glossary — Go and web-backend terms used throughout this doc

Request Pipeline

Project Directory & Code Map

All Go files live flat in the repo root (no internal package split). Grouped here by what they actually do, verified against the code on 2026-08-27:

main.go — Server Entrypoint & Middleware

Startup sequence

1. loadEnv() reads .env into the process (no-op if the file is missing).
2. Boot fails immediately if RAZORPAY_KEY_ID, RAZORPAY_SECRET, STITCH_SIGNING_KEY, or RAZORPAY_WEBHOOK_SECRET are unset. New: it also fails if PLANKRO_DEV_MODE=1 is combined with a live (rzp_live_) Razorpay key — that combination would leave the hardcoded-OTP test login reachable in production.
3. Checks for a CLI subcommand in os.Args[1] (migrate, reconcile-payments, merge-accounts, offer-add/list/remove/stats, suppress-lifecycle-backlog) and exits early if matched — these run instead of starting the server.
4. initDB() — opens SQLite, runs schema + migrations.
5. Loads eligible zone landing pages, initializes the Google Places client, parses all templates.
6. Starts two background schedulers: the lifecycle email sweep and the Pro-downgrade sweep.
7. Registers every route (see the Route Directory) and wraps the mux in the middleware chain.
8. Starts the HTTP listener; on SIGINT/SIGTERM, stops accepting new connections, drains in-flight HTTP requests (10s budget) and in-flight background emails/CAPI sends (10s budget), then exits.

Middleware chain, in actual execution order

logging → recovery → securityHeaders → csrf → googleVerify → rateLimit → auth

Graceful shutdown

stop := make(chan os.Signal, 1)
signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
<-stop

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
server.Shutdown(ctx)      // 1. stop accepting new connections, drain in-flight requests

// 2. wait (bounded) for background emails / CAPI sends to finish
drainInFlightEmails(ctx)

database.go — Schema & Storage

SQLite, single file, tuned deliberately for a 952MB RAM production box.

Connection & pragma settings — corrected from the previous version of this doc

db.SetMaxOpenConns(25)
db.SetMaxIdleConns(10)
db.SetConnMaxLifetime(5 * time.Minute)

// DSN: ?_journal_mode=WAL&_synchronous=NORMAL&_busy_timeout=5000&_cache_size=-8000&_temp_store=MEMORY

Tables

Real index names (the old doc invented different ones)

idx_itineraries_scheduled_date, idx_users_lifecycle, idx_email_sends_suppressed_sent_at, idx_activities_zone_budget, idx_activities_zone_active_cat, plus lookup indexes for OTP-by-email, subscriptions/itineraries-by-user, and room participants/suggestions.

Startup seeding shortcut

On boot, the server SHA-256-hashes the venue seed data and skips the entire re-insert pass if it's unchanged from the last recorded hash in schema_meta — keeps a clean-slate boot fast.

Complete Route Directory

Every route currently registered in main.go, grouped by area. Pulled directly from the route registrations, not reconstructed from memory — the previous doc's route table was missing most of these.

Auth, Sessions & OTP

Anonymous sessions (new 2026-08-30)

A visitor with no account can now generate and revisit a plan. Identity for that visitor is a second, separate signed cookie — plankro_anon, format sessionID|expiryUnixTimestamp|hexHMACSignature, same signing key and verification style as plankro_session, 1-year expiry. It answers "which browser is this" the way plankro_session answers "which account is this" — the two are independent and a request only ever carries one or the other.

The dev-mode test backdoor — and its new safety guard

When PLANKRO_DEV_MODE=1, requesting an OTP for tester@plankro.com, test@plankro.com, or admin@plankro.com returns an instant "VIP Pro Test Account" message, and any of the codes 123456, 000000, or 777777 verifies successfully for those three emails only.

OTP rate limiting

OTP requests are covered by the same per-IP+path rate limiter described in the middleware section (15/15min), plus a dedicated otp_request_log table for per-email tracking.

Payments, Entitlement & Offers

This is the money path — a live rzp_live_ Razorpay key runs in production. Every change here is a money-path change.

Webhook events handled — corrected from the old doc

entitlement.go — the fix for a real production bug

Before this file existed, is_pro was the only gate anywhere, and pro_expires_at was written by some grant paths but read by nothing except a disabled sweep. A customer who paid for one month kept Pro forever. proActive() now derives entitlement live on every request:

• is_pro = 0 → never active, full stop.
• legacy_lifetime = 1 → always active (grandfathered one-time payers from before the subscription model).
• A NULL expiry on a non-grandfathered Pro user → not active (previously the bug: NULL was silently treated as lifetime).

subscriptionEraStart (2026-08-16) marks the day pricing flipped from one-time-lifetime to monthly-subscription — the grandfather rule only applies to payments before that date, closing the exact loophole that once granted a brand-new monthly subscriber permanent free Pro on launch day.

Offers — the café discount system

See the redemption flow diagram above. Managed via CLI: offer-add, offer-list, offer-remove, offer-stats — string subcommands, e.g. go run . offer-add ....

Reconciliation & account cleanup tools

Lifecycle Email Engine

Full flow diagram is in the System Flow Diagrams section above. This section covers the delivery mechanics.

var pendingEmails sync.WaitGroup

func goSendEmail(fn func()) {
    pendingEmails.Add(1)
    go func() {
        defer pendingEmails.Done()
        defer func() {
            if r := recover(); r != nil {
                log.Printf("recovered from email panic: %v", r)
            }
        }()
        fn()
    }()
}

Without the panic recovery here, one broken email template would crash the entire server process for every user, not just fail that one email. Real Gmail SMTP is used directly (smtp.gmail.com:587, STARTTLS, app-password auth) — no third-party ESP. Bulk lifecycle sends optionally route through a separate Gmail account (GMAIL_LIFECYCLE_USER) so a bulk-send spike can never throttle the account that also sends OTP codes and payment receipts. In local dev with no Gmail credentials configured, it logs instead of sending.

Analytics & Tracking

All three tracking systems below are real and live — this corrects several wrong claims in the old doc.

Date Rooms & Friends Mode

What a "Room" is

There's no separate "plan" object anymore — every generated plan is a room. createItinerary writes the itinerary row and the creator's participants row inside one transaction. /room/{code} is the universal landing page. A guest without a pk_room_{code} cookie is shown room_join.html and must enter a display name before seeing the plan.

Couple vs. Friends mode — same engine, different funnel

Both modes POST /generate into the same createItinerary function with the same PlanParams struct. The only fork is which template renders (plan_new_couple.html vs. plan_new_friends.html) and how downstream code reads the stored plan_mode — pricing phrasing, the stop-count stepper, and the feasibility check are all conditioned on it. An unrecognized mode value (e.g. a mangled WhatsApp-pasted URL) defaults to couple mode.

Friends Mode mechanics

Surprise Mode redaction

A plan is hidden from a viewer only if is_hidden=1 AND the plan has an owner AND the current viewer isn't that owner — a room guest with no login (nil viewer) counts as "not the owner," so guests are redacted too. Redaction replaces stop 2+'s name with "Surprise Stop N 🤫" and wipes description, note, price, links, image, and the activity ID (which also kills the venue-detail link). This happens in-memory on every render — the database always holds the full plan. An earlier bug that leaked the venue link even while the name was hidden was fixed on 2026-08-19.

Planning Engine & Venue Matching

Proximity clusters — a lookup table, not a distance algorithm

planner_engine.go is 29 lines. It hard-codes 5 clusters matching Delhi's real geography:

This exists to stop a plan from crossing the whole city, not to calculate travel time between two points.

Venue selection algorithm

suggestActivities tries an exact zone + budget + mood match first. If fewer than 3 venues qualify, it drops the budget filter and retries zone-only — the recorded matchQuality degrades from exact → mood_relaxed → budget_relaxed. If still empty (or below a friends-mode override count), it returns "no match" rather than an incomplete plan. fillSlots seats a café/restaurant first, entertainment/outdoor second, then fills remaining slots against a running cumulative budget total — Budget ₹500, Mid ₹1500, Upscale ₹3000, Luxury ₹12000 (Luxury's cap is high enough to be effectively unconstrained).

Composition-aware planning for audited zones (new 2026-08-30)

The problem this fixes: the fallback logic above (drop budget, then drop mood) is good at guaranteeing 3 venues, but says nothing about what kind of venues they are. In practice this let a plan come back as two cafes and a restaurant — no real activity stop — or open on a ₹150 street-food stall before dinner. Neither is what "a café, then dinner, then something to do" (the one-paragraph pitch at the top of this doc) actually promises.

suggestComposedPlan (composition.go) enforces the real shape instead, for zones with an entry in zone_config.go — currently Hauz Khas, Connaught Place, and North Campus, chosen because those three have audited price and role data behind them (see the comments in zone_config.go for the actual venue counts per role, per zone). Every other zone is untouched — it keeps the exact fallback behavior described above.

Two separate "venue" datasets — don't conflate them

• venues.go's venueData map — 10 hand-written long-form SEO blog entries. Not used by the planner.
• venues_batch_three.go / venues_batch_four.go — the real planner pool, seeded into the activities table. 366 total venues, 348 active, across 15 zones.

Vibes

7 total: casual, impressive, luxury, lively, adventurous, quiet, romantic. Each maps to a bucket of mood tags scored against a venue's own tags.

Google Places caching

places.go wraps the Google Places API (New), gated on GOOGLE_PLACES_API_KEY — it disables itself gracefully (not a crash) if unset. Results cache for 30 days; a background, non-blocking refresh runs only for selected venues whose cache has gone stale, deduping concurrent refresh calls for the same venue.

Venue Profiles & Café Discounts

WhatsApp Emergency SOS

sos.go — Pro-gated at every call site (/plan/{code}, the Live Pass page, and the partner view via the plan owner's Pro status). "Same day" is evaluated against the plan's creation date in IST, not a separately scheduled date. Triggering it opens a plain wa.me link to a fixed business WhatsApp number, prefilled with the plan title, code, zone, and stop names, ending "Can you help us pivot right now?" — no in-app form, just a tap.

Templates, Frontend & CSP

HTMX — confirmed fully gone

Grepped every .go, .html, and .js file in the repo: zero references to hx- attributes or htmx. This matches the project's no-HTMX rule.

Tailwind CDN — still live, despite an earlier removal claim

The script tag <script src="https://cdn.tailwindcss.com"> still loads on room_new.html and plan.html. A commit on 2026-08-17 explicitly restored it on plan.html ("real root cause of badge overlap") after an earlier removal — so the old doc's "Unused JavaScript Removal" claim describes a change that was later reverted.

Content-Security-Policy — as actually set in main.go

default-src 'self';
script-src 'self' 'unsafe-inline' https://*.razorpay.com https://unpkg.com
           https://cdn.tailwindcss.com https://www.googletagmanager.com https://connect.facebook.net;
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://*.razorpay.com;
font-src 'self' https://fonts.gstatic.com https://*.razorpay.com;
img-src 'self' data: https:;
connect-src 'self' https://www.google-analytics.com https://*.razorpay.com https://www.facebook.com;
frame-src 'self' https://*.razorpay.com;
frame-ancestors 'none'; form-action 'self'

img-src is deliberately broad (any https: host) — a 2026-08-17 commit widened it specifically to allow hotlinking venue images from Google Places. unpkg.com is a dead entry now that HTMX is gone and worth removing; cdn.tailwindcss.com is not dead, per above.

Templates (29 files in templates/, 6 in templates/partials/)

Grouped by area: marketing/SEO (index, hub, seo_blog, seo_venue, zone_page, privacy, terms, refund, contact), wizard/generation (plan_new_couple, plan_new_friends, no_match), plan/room viewing (plan, plan_share, room, room_new, room_join, live_pass, confirmation), auth (login, signup), venues (venue_detail, redeem), dashboards (dashboard, my_dates), misc (pricing, meta, schema, icons, whatsapp). Shared partials: page_shell, plan_wizard, plan_wizard_js, site_footer, site_header, theme_js.

Brand & Design System — no shared stylesheet, tokens duplicated per template

There is no .css file in the repo. Every template carries its own inline <style> block of CSS custom properties (this is what style-src 'unsafe-inline' in the CSP above exists for). Only 5 of 30 templates — index, plan_new_couple, plan_new_friends, room, room_join — pull their tokens from the shared page_shell partial; the other 25 (hub, pricing, venue_detail, login, signup, dashboard, legal pages, etc.) each hardcode their own copy inline. The two sets have drifted from each other — see below.

3 time-of-day themes, switched via data-theme

{{template "theme-js"}} in theme_js.html picks a theme from the client clock (day 06:00–16:00, evening 16:00–20:00, night 20:00–06:00) and sets document.documentElement.setAttribute('data-theme', …). The wizard lets a user override it explicitly; everywhere else the clock is the only input. Attribute values are not day/evening/night — day maps to data-theme="light", evening to data-theme="evening", night to data-theme="dark".

Day    (:root, default)      bg #F3F2EE   accent #8C7355   heading Cormorant Garamond
Evening (data-theme="evening") bg #16111D   accent #E29578   heading Cormorant Garamond
Night   (data-theme="dark")    bg #0D0B0A   accent #DE9E48   heading Playfair Display
Body font all 3 themes: Inter

Day    (:root, default)      bg #F3F2EE   accent #8C7355   heading Cormorant Garamond
Evening (data-theme="evening") bg #FDF0D6   accent #E07030   heading Playfair Display
Night   (data-theme="dark")    bg #0C0A09/#0D0B0A  accent #FFB347/#DE9E48  heading Playfair Display
Body font all 3 themes: Inter

Drift, confirmed by grep across all 30 templates: the shared page_shell partial's Evening mode is a dark plum (#16111D, Cormorant Garamond heading) — but every one of the 25 standalone templates independently defines Evening as a warm cream (#FDF0D6, Playfair Display heading). Day and Night agree everywhere. Practically: the homepage and the plan wizard render a dark evening theme; every other page (pricing, venue pages, dashboard, login, legal) renders a cream evening theme. This isn't a bug being tracked — it's the actual current behavior, and worth knowing before assuming "the evening theme" means one thing across the site.

Friends-mode accent override — page_shell only

html[data-theme][data-mode="friends"] selectors in page_shell.html swap the accent to teal/green (#0E6E5C day, #26A69A evening, #2DD4BF night) when a room is in friends mode. Grep confirms data-mode="friends" exists only in page_shell.html — so this override only reaches the 5 shell-based pages (index, both wizard funnels, room, room_join). The 25 standalone pages have no friends-mode selector at all and always render the default earthy/orange/gold accent regardless of mode.

Core tokens (page_shell.html, Day defaults)

--bg-main: #F3F2EE;      --bg-surface: #FFFFFF;   --bg-surface-low: #FAFAF8;
--bg-surface-high: #EEEDE9;  --text-primary: #19191B; --text-secondary: #2C2C2E;
--text-muted: #63615D;   --accent: #8C7355;       --accent-ink: #6E5940;
--accent-glow: rgba(140,115,85,0.1);  --accent-hover: rgba(140,115,85,0.15);
--border-ui: rgba(25,25,27,0.08);     --border-active: #8C7355;
--shadow-card: 0 8px 40px rgba(0,0,0,0.04);
--font-heading: 'Cormorant Garamond', serif;   --font-body: 'Inter', sans-serif;

Fonts load from Google Fonts (fonts.googleapis.com/fonts.gstatic.com, whitelisted in the CSP above): Cormorant Garamond, Playfair Display, Inter, plus the Material Symbols Outlined icon font — used in 13 of 30 templates for nav icons, the theme toggle, and inline UI icons. auto_awesome (✨) is the primary/most-used icon per the brand guide. Theme transitions animate over 0.6s cubic-bezier(0.16,1,0.3,1) on background/color, and headings transition font-family over the same curve when the theme swaps typefaces.

Security & Concurrency Controls

2026-08-30 — six issues found and closed before the anon-generation change shipped

Reinstating anonymous generation was reviewed for what it could break, not just whether it built and passed tests. Six real issues surfaced across two review passes; all six were fixed and each has a test proving the fix, before this landed on main.

Test Suites & CLI Tools

Test files (~180 test functions total, as of 2026-08-30)

go test -v ./...
go test -race -count=1 ./...

CLI subcommands — corrected: these are string subcommands, not flags

The old doc's -reconcile-payments/-downgrade-pro -dry-run/-merge-dry-run syntax is wrong. The real invocation reads os.Args[1] directly:

go run . migrate
go run . reconcile-payments
go run . merge-accounts
go run . offer-add
go run . offer-list
go run . offer-remove
go run . offer-stats
go run . suppress-lifecycle-backlog

Developer Quickstart

PORT=8081
PLANKRO_DEV_MODE=1
STITCH_SIGNING_KEY=<generate-a-new-64-char-hex-secret>
RAZORPAY_KEY_ID=<your-razorpay-key-id>
RAZORPAY_SECRET=<your-razorpay-secret>
RAZORPAY_WEBHOOK_SECRET=<your-webhook-secret>
RAZORPAY_PLAN_PRO=<your-razorpay-plan-id>
GMAIL_USER=<your-email@gmail.com>
GMAIL_APP_PASSWORD=<your-gmail-app-password>
GMAIL_LIFECYCLE_USER=<optional-separate-lifecycle-email>
GMAIL_LIFECYCLE_PASSWORD=<optional-separate-app-password>
LIFECYCLE_EMAILS_ENABLED=1
META_PIXEL_ID=<your-pixel-id>
META_CAPI_TOKEN=<your-capi-token>
GOOGLE_PLACES_API_KEY=<your-places-key>
GOOGLE_ANALYTICS_ID=<your-ga4-id>
GOOGLE_ADS_ID=<your-ads-id>

Running locally

go run .
# or
go build -o stitchplanner .
./stitchplanner

Dev-mode test login

Only reachable when PLANKRO_DEV_MODE=1 and the Razorpay key is a rzp_test_ key (the app refuses to boot otherwise). Emails: tester@plankro.com, test@plankro.com, admin@plankro.com. Codes: 123456, 000000, 777777.

Recent Engineering Timeline

Pulled from actual git history, not reconstructed. Two clusters of work stand out: