Mehfil

The AI planner for weddings, birthdays and community celebrations.

Describe your celebration in one sentence, in English, Hindi or Bengali. Gemini turns it into a complete plan: a budget that adds up, a timeline counted back from your date, a vendor checklist, ideas that honour your traditions and a run sheet for the day. Every detail stays yours to change.

Try Mehfil live → · Watch the demo →

Live app · Demo video · Chosen vertical · How it works · Approach and logic · Assumptions · Screenshots · Gemini · Architecture · Quality · Run it locally

Built for PromptWars Virtual 2026 · Challenge 5: Celebration & Event Planner

Why Mehfil

Planning a celebration in India means hundreds of decisions: an ₹18 lakh budget split across a dozen vendors, rituals that each need their own preparation, 300 guests with different diets, and dates that keep moving. Generic checklists don't know any of that, and a chatbot forgets your plan after one answer. Mehfil keeps Gemini working on the plan.

• Gemini plans, code does the maths. Gemini reads your description and tailors four parts of the plan at once, streaming each one as it lands. Every amount and date is then computed by tested code, so budgets always add up and no deadline lands in the past.
• A Copilot that edits the plan, not just chats. Say "we now expect 50 more guests" and Gemini's function calling proposes the exact changes: the guest count, a task, a budget line. Apply the ones you want, and undo any of them later.
• Made for Indian celebrations. Rituals, lead times and vendors for weddings, birthdays, pujas and festivals. Amounts in lakh and crore (₹18,00,000), typed the way people say them ("18 lakh", "1.5 crore"), and the whole app in English, Hindi and Bengali.
• Yours, on every device. Plans are saved on your device first. Sign in with Google to sync them, or share a read-only link that leaves out guests and contacts.
• Free to run. Vercel Hobby, Firebase Spark and the Gemini free tier, with caching, model fallback and rate limits that keep it answering within free quotas.

Chosen vertical

Celebration & Event Planner (PromptWars Virtual 2026, Challenge 5): a GenAI-powered planning assistant that helps users organise weddings, birthdays and community events with budgets, timelines, vendor checklists and personalised ideas.

Persona. A family member or community volunteer in India planning a wedding, a child's birthday or a neighbourhood puja without a professional planner. They work to a fixed budget, often plan on a phone, may be more at home in Hindi or Bengali than in English, and need to know what to do next rather than a list of generic tips. Every decision below is designed around that person.

How the solution works

1. Describe it. One sentence in English, Hindi, Bengali or a mix, or a three-step form. As you type, a local parser picks out the occasion, date, city, guest count, budget ("18 lakh", "1.5 crore") and diets, in all three languages.
2. Gemini reads it. Gemini turns the sentence into a structured brief, and Mehfil fills any gap from the local reading. If something essential is still missing, the form opens with what was understood instead of guessing; if Gemini is unreachable, the local reading is used on its own.
3. A complete plan appears at once. The planning engine builds a standard plan from the occasion's template: budget lines, tasks scheduled back from the date, vendors with book-by dates and a day-of run sheet. It works even if Gemini never answers.
4. Gemini tailors it. Four sections are tailored in parallel and stream in as each is ready: the budget split with reasons, extra tasks and risks, vendor questions and red flags, and themed ideas. Code validates every answer and computes every amount and date.
5. You stay in control. Edit anything inline, ask the Copilot for changes and review them before applying, ask for different ideas in your own words, and undo any step.
6. Keep it and share it. Plans are saved on the device. Sign in with Google to sync them, share a read-only link without personal details, and add tasks to Google Calendar.
7. On the day. A run sheet for every day of the celebration, with who is in charge of each moment, ready to print.

Approach and logic

Gemini understands and suggests; tested code decides and computes. Gemini is good at reading messy descriptions and at cultural, creative suggestions. Code is reliable at money, dates and rules. Every Gemini answer passes through deterministic rules that react to the user's context:

Your context	What Mehfil decides	Where
Type of celebration	A template for weddings, birthdays, community events or anything else: budget categories with typical shares and bounds, vendors to book, and tasks with ideal lead times and rituals.	src/shared/templates/
Venue	Shifts the budget before any AI is involved: at home the venue's weight drops to a fifth, at a community hall or temple to 60 %; a destination wedding triples accommodation and raises transport; an outdoor event raises decor and the contingency.	adjustedShares in src/shared/domain/budget.ts
Budget	Keeps Gemini's suggested shares inside each category's bounds, turns them into amounts with largest-remainder rounding so the lines always equal the total, rebalances to a new total while protecting chosen lines, warns at 90 % spent and flags any line or total that goes over.	src/shared/domain/budget.ts
Guests and RSVPs	Per-guest lines (catering, favours, return gifts) scale with the count, optionally absorbed by other lines to keep the total. Once a guest list exists, the expected headcount (confirmed, maybe and pending) and diet counts replace the estimate.	scaleForGuests, src/shared/domain/guests.ts
Date and today	Schedules every task back from the date by its lead time. When time is short, lead times are compressed in order so nothing lands in the past, and those tasks are marked "brought forward". Moving the date re-dates open tasks only.	src/shared/domain/timeline.ts
Progress	Readiness blends tasks (50 %), vendor bookings (30 %) and budget health (20 %). "Today's focus" lists the earliest-due open tasks, highest priority first, and anything overdue is flagged. A booked vendor's chosen quote counts against its budget line.	readiness.ts, timeline.ts, vendors.ts
Diets	Every prompt spells out what each requested diet rules out (Jain: no onion, garlic, potato or other root vegetables), and the evaluation checks the dishes.	src/server/ai/prompts.ts, evals/run.ts
Accessibility needs	Passed to Gemini with the rest of the brief, so tasks, vendor questions and risks account for them, such as ramps and accessible seating for elderly guests.	src/server/ai/prompts.ts

Screenshots

Every occasion gets its own look. The home page stays calm and neutral; a plan opens like its occasion's invitation card, in its colours and with its photograph, recognised from what you wrote in any of the three languages, and the first time it opens, the occasion plays for a few seconds.

The plan below was tailored by real Gemini from one sentence: "A Bengali wedding of Ananya and Rohan in Kolkata on 14 Feb 2027 for about 300 guests. Budget ₹18 lakh, mostly vegetarian, and my grandparents need wheelchair access."

Features

The brief asks for	What Mehfil does
A GenAI planning assistant	Describe the occasion in your own words (English, Hindi, Bengali or a mix) or use a three-step form. Gemini tailors the plan section by section, and the Copilot turns requests into reviewable edits with undo.
Weddings, birthdays and community events	Templates with Indian categories, rituals and lead times for weddings, birthdays and community events such as pujas and festivals, and a general template for anything else.
Budgets	Gemini's suggested split, turned into amounts by code that always add up; planned, committed and paid per line; rebalance to a new total; "what if the guest count changes"; cost per guest; a realistic-or-not check with saving tips. Indian grouping (₹18,00,000) and amounts typed as "18 lakh" or "1.5 crore".
Timelines	Tasks scheduled back from the date and brought forward when time is short, grouped by phase, with priorities, filters and a countdown. A calendar file with reminders, "Add to Google Calendar" on every task, and a printable day-of run sheet for multi-day celebrations.
Vendor checklists	What to book and by when, a status pipeline from "not started" to "paid", questions to ask and red flags, quote comparison (the chosen quote counts in the budget), and a Google Maps search for each category in your city.
Personalised ideas	Themes with colour palettes, food, decor, entertainment, activities, personal touches, favours and greener choices, shaped by your traditions, diets and budget. Keep the ones you like; ask for different ones in your own words.
Made for the occasion	The plan opens like its occasion's invitation card, in its colours and with a real photograph of the festival (wedding, Durga Puja, Ganpati, birthday, Diwali or another festival), and the first time it opens it plays a few seconds of that celebration.
Beyond the brief	A guest list with RSVPs and diets that feeds catering numbers (CSV import and export), an invitation writer for WhatsApp, email, cards and social posts, readiness at a glance, sync across devices, and read-only share links.

How Gemini is used

Gemini does the planning work in five server-side tasks. Every answer is constrained by a JSON schema generated from the same Zod schemas the app uses, then validated, clamped and cleaned before it reaches the plan.

Task	What Gemini does	Model	Gemini features
Read a description	Turns a sentence in English, Hindi, Bengali or a mix into a structured brief, and asks one question when something essential is missing.	3.5 Flash-Lite	Structured output
Tailor the plan	Budget split with reasons, extra tasks and risks, vendor questions and red flags, themed ideas. Four sections run in parallel and each is streamed as soon as it is ready.	3.5 Flash-Lite for budget, timeline and vendors; 3.5 Flash for ideas	Structured output, parallel calls, streaming (NDJSON)
Refine ideas	New ideas from a chip ("More budget-friendly") or your own words, keeping the ones you liked.	3.5 Flash	Structured output
Copilot	Proposes typed edits through 10 tools: tasks, budget lines and total, guest count, vendors, ideas and the run sheet.	3.5 Flash	Function calling
Invitation writer	Drafts invitations in your tone (warm, formal, playful, traditional), for WhatsApp, email, a card or social media, in your language.	3.5 Flash-Lite	Structured output

sequenceDiagram
    autonumber
    actor You
    participant App as Mehfil (browser)
    participant API as AI gateway (Vercel)
    participant Gemini as Gemini API
    You->>App: "A Bengali wedding in Kolkata for 300 guests, ₹18 lakh"
    App->>API: POST /api/ai/brief
    API->>Gemini: structured output with the brief schema
    Gemini-->>API: the brief as JSON
    API-->>App: validated brief
    Note over App: A complete standard plan appears at once
    App->>API: POST /api/ai/personalize
    par Budget
        API->>Gemini: budget split
    and Timeline
        API->>Gemini: extra tasks and risks
    and Vendors
        API->>Gemini: questions and red flags
    and Ideas
        API->>Gemini: themes, food and decor
    end
    Gemini-->>API: JSON for each section
    API-->>App: one streamed event per section, as soon as it is ready
    Note over App: Validate, compute amounts and dates, merge, announce to screen readers

Guardrails

• AI suggests, code computes. Gemini returns bounded percentages and day offsets; the planning engine turns them into rupees (largest-remainder rounding, so lines sum exactly) and dates.
• No invented facts. There are no schema fields for vendor names, phone numbers or prices, the prompts forbid them, and a filter strips phone numbers, emails and links. Real vendors come from Google Maps searches built by code.
• Prompt injection is contained. User text is passed as clearly marked, untrusted data; answers must match a schema; the Copilot can only propose typed operations on IDs that exist, and nothing changes until you apply it.
• Diets are spelled out. Each prompt states what every requested diet rules out (Jain means no onion, garlic, potato or other root vegetables), so dishes stay within them.
• Reliable on the free tier. A 30-minute response cache, a per-model request budget, one jittered retry, automatic fallback to the other model, a circuit breaker (three failures pause a model for 60 seconds) and, if Gemini is unavailable, a clearly labelled standard plan.
• Private by design. Guest names and contacts never reach Gemini; only counts do.
• Evaluated against real Gemini. npm run eval runs six celebrations, including descriptions in Hindi and Bengali, a Jain dinner and a short-notice party. On 24 October 2026 all six passed every check: valid structured answers, budgets that add up, dates before the event, no contact details, diets respected and text in the requested language.

More in docs/AI_DESIGN.md.

Architecture

One TypeScript codebase. Vercel serves the React app from its CDN and runs the AI gateway as a Node function in Mumbai; Firebase holds identity and synced data.

flowchart TB
    App["<b>Browser</b><br/>React 19 app<br/>planning engine<br/>plans on the device"]
    Gateway["<b>AI gateway</b><br/>Hono on Vercel, Mumbai<br/>validation, rate limits<br/>cache, model fallback"]
    subgraph Google["Google services"]
        Gemini["<b>Gemini API</b><br/>3.5 Flash, Flash-Lite"]
        Auth["<b>Firebase Auth</b><br/>anonymous, Google"]
        Firestore[("<b>Cloud Firestore</b><br/>Security Rules")]
    end
    App -- "AI requests" --> Gateway
    Gateway -- "@google/genai" --> Gemini
    Gateway -. "verifies ID tokens" .-> Auth
    App -- "sign-in" --> Auth
    App -- "sync, share links" --> Firestore

Key decisions, each recorded as an architecture decision record:

1. Free hosting on Vercel Hobby, Firebase Spark and the Gemini free tier, with no billing account anywhere.
2. AI suggests, code computes: money and dates are never left to the model.
3. generateContent with JSON schemas behind a provider interface, with a deterministic demo provider for tests and key-less runs.
4. Local-first plans, with opt-in sync through Google sign-in and conflicts the user settles.
5. A prerendered, hydrated home page for a fast first paint under a strict Content Security Policy.
6. Small functions, held by lint: at most 80 lines and complexity 10, split into helpers, hooks and named components.

The full picture, including the data model and the request pipeline, is in docs/ARCHITECTURE.md.

Assumptions

• Amounts are estimates. Mehfil does not know live local prices. Budget shares come from typical ranges and Gemini's reasoning, and the app labels every figure as an estimate to confirm with vendors.
• Indian defaults, open to everyone. Templates, rituals and amounts in lakh and crore follow Indian celebrations, and rupees are the default, but eight currencies and any kind of celebration work.
• Dates are local and date-only. The browser supplies today's date, so a plan never depends on the server's time zone, and multi-day celebrations count each day.
• One planner, many viewers. One person edits a plan, on as many of their devices as they like; family and co-organisers get a read-only link. If two devices change the same plan, the user chooses which version to keep.
• No invented facts. Mehfil never names vendors or gives contact details or prices as facts; real vendors come from Google Maps.
• Guests stay private. Guest names and contacts stay on the device; Gemini only sees counts.
• No sign-up. Visitors are signed in anonymously behind the scenes, which protects the AI from abuse; Google sign-in is only needed to sync across devices.
• Gemini's free tier has limits. When a model is busy or out of quota, Mehfil switches to the other model; when Gemini is unavailable, the standard plan still works and is clearly labelled.
• Modern browsers. Current Chrome, Edge, Safari and Firefox, on phones and computers.

Google services

Service	How Mehfil uses it
Gemini API (@google/genai)	Five server-side tasks with JSON-schema structured output, function calling for the Copilot and streamed results; gemini-3.5-flash and gemini-3.5-flash-lite, each falling back to the other.
Firebase Authentication	Anonymous sign-in behind AI calls and share links, and Google sign-in for sync. The server verifies Firebase ID tokens against Google's public keys.
Cloud Firestore	Synced plans and share links through the lightweight firestore/lite SDK, protected by Security Rules that are tested on the emulator.
Google Calendar	"Add to Google Calendar" on every task, plus a calendar file with reminders for any calendar app.
Google Maps	A search link for each vendor category in the event's city, so people find real vendors.
Google Fonts	Eczar and Mukta for Latin and Devanagari, Tiro Bangla and Noto Sans Bengali for Bengali, self-hosted; each script's font loads only when it is used.

Quality

Check	Result
Unit, integration and component tests (Vitest, Testing Library, jest-axe, fast-check)	823 passing; 97.9 % of lines and 84.2 % of branches covered, with per-layer gates in CI
Firestore Security Rules and the Firebase adapter (emulator)	13 passing
Browser journeys (Playwright on desktop and a phone, axe on every page, reflow at 390 and 320 px)	44 passing
Gemini evaluation (six sample celebrations, real API)	6 of 6 pass every check
Lighthouse on the live site (simulated phone, five runs)	Performance 93–96 · Accessibility 100 · Best practices 100 · SEO 100
Static analysis	Strict TypeScript, typescript-eslint strict type-checked rules, function size and complexity limits, jsx-a11y, CodeQL, secret scan

Every push runs the full pipeline in GitHub Actions: secret scan, size budget, lint, formatting, type checks and tests with coverage gates on Node 22 and 24, then the production build, browser journeys, Firestore rules on the emulator, Lighthouse budgets and a dependency audit. Details in docs/TESTING.md.

How it meets the judging criteria

Criterion	What Mehfil does	Evidence
Problem alignment	Every part of the brief is a working, editable, saved feature (see Features), with Gemini doing real planning work rather than chat, and decisions that follow the user's context (see Approach and logic).	src/client/features/, e2e/plan.spec.ts
Code quality	Strict TypeScript and strict type-checked lint rules; small functions, kept small by lint (at most 80 lines, complexity 10, four parameters, three levels of nesting); one shared schema contract for browser, server and Gemini; one pure function for every edit, so undo is free; a dependency-injected server; typed translations, where a missing string fails the build; documented decisions.	src/shared/, eslint.config.js, ADRs
Security	The key stays on the server; a strict CSP with no inline code or eval; rate limits and Firebase token checks on AI calls; prompt-injection containment and output cleaning; tested Firestore rules; a CSV-injection guard; a secret scan in CI.	SECURITY.md, firestore.rules, src/server/security/
Efficiency	AI suggests and code computes; sections stream in parallel; a response cache and per-model request budget for the free tier; a prerendered home page; the React Compiler memoises components; routes, languages, Firebase and dialogs load on demand; photographs are small WebPs in several widths, and only the first screen's is fetched early; Brotli; fonts per script.	ARCHITECTURE.md, ADR 5

Run it locally

You need Node.js 22.12 or newer.

git clone https://github.com/roybishal362/Mehfil.git
cd Mehfil
npm ci
npm run dev

Open http://localhost:5173. Without a key, the server runs a clearly labelled demo mode with realistic sample answers, so every feature can be tried. For real Gemini, create a free key in Google AI Studio, copy .env.example to .env.local (git ignores it) and paste the key after the =:

GEMINI_API_KEY=

Command	What it does
npm run dev	API on port 8787 and the app on 5173, with hot reload
npm run build then npm start	Production build served by the Node server (precompressed, security headers)
npm run lint, npm run typecheck, npm run format:check	Static checks
npm test, npm run test:coverage	Unit, integration and component tests (with coverage gates)
npm run e2e	Browser journeys on desktop and phone (after a build)
npm run test:rules	Firestore rules and the Firebase adapter on the emulators (needs Java 21)
npm run eval	Checks real Gemini answers against sample celebrations (needs a key)

All variables are read by the server only; nothing here is bundled into the browser.

Variable	Purpose
GEMINI_API_KEY	Real Gemini answers. Without it, the labelled demo mode runs.
FIREBASE_PROJECT_ID, FIREBASE_API_KEY, FIREBASE_AUTH_DOMAIN, FIREBASE_APP_ID	Sign-in, sync and share links. This web config is public by design and served at runtime.
GEMINI_MODEL_SMART, GEMINI_MODEL_FAST	Model choice; defaults gemini-3.5-flash and gemini-3.5-flash-lite.
AI_RATE_LIMIT	AI tokens per visitor per 10 minutes (default 24; a tailored plan costs 4).
AI_MAX_RPM	Gemini calls per minute per server instance (default 12), to stay within the free tier.
REQUIRE_AUTH_FOR_AI	Require a Firebase ID token on AI calls; on by default when Firebase is configured.

Deploying is free: Vercel Hobby for the app and the AI gateway, Firebase Spark for sign-in and Firestore, and a Gemini key from AI Studio. Step by step: docs/DEPLOYMENT.md.

Project structure

src/
├── shared/          One contract for browser, server and Gemini
│   ├── schemas/     Zod schemas, also turned into Gemini's JSON schemas
│   ├── domain/      Planning engine: budgets, timelines, vendors, readiness, edits, merging
│   │   ├── ops/     How each kind of edit applies: brief, tasks, budget, vendors, lists
│   │   └── parse/   The quick parser: one reader each for dates, places, guests, money, food
│   ├── templates/   Weddings, birthdays, community events and more: categories, rituals, lead times
│   └── export/      Calendar files, Google Calendar and Maps links, CSV, share snapshots
├── server/          Hono AI gateway
│   ├── ai/          Gemini provider, prompts, the gateway (cache, fallback, circuit breaker)
│   │   ├── tasks/   One module per AI task: brief, sections, invitation, Copilot and its tools
│   │   └── mock/    Deterministic demo answers for key-less runs and tests
│   ├── routes/      /api/health, /api/config and the AI routes
│   ├── middleware/  Request context, client IP, rate limits, Firebase token checks
│   └── security/    One header policy for the Node server and Vercel
└── client/          React app
    ├── app/         Shell, routes, themes and notifications
    ├── pages/       Home, new plan, plan workspace, shared plan
    ├── components/  Labelled fields, inputs that commit once, dialogs, the error boundary
    ├── features/    Plan sections, overview, Copilot, account, sync and sharing
    ├── cloud/       Firebase adapter, sync with conflict handling, share links
    ├── state/       Plans with undo and redo, saved on the device
    └── i18n/        English, Hindi and Bengali, typed so a missing string fails the build
e2e/                 Playwright journeys with axe
evals/               Evaluation against real Gemini
scripts/             Build, prerender, Vercel output, secret scan, size budget
docs/                Architecture, AI design, accessibility, testing, design, deployment, ADRs
firestore.rules      Owner-only plans; share links readable by ID only until they expire

Security and privacy

• The Gemini key lives only in the server's environment, and CI scans every file for keys.
• A strict Content Security Policy: scripts only from this origin, no inline code and no eval.
• AI calls are rate limited per visitor and, with Firebase on, need a verified Firebase ID token.
• Firestore rules let each account read and write only its own plans, with every field checked.
• Share links use 128-bit IDs, expire after 90 days and never include guests or contacts.
• Guest names and contacts never leave the device for the AI, and you can delete your cloud data and your local plans from the account menu.

The threat model, with evidence for each item, is in SECURITY.md.

Accessibility and languages

• Built to WCAG 2.2 AA: landmarks, a skip link, focus moved to each new page's heading, labelled forms with an error summary, native dialogs and announcements for streamed AI results.
• Colour contrast is checked in code for both themes and every occasion's colours; motion stops with prefers-reduced-motion, and celebration moments never play then.
• No sideways scrolling down to 320 px, checked in the browser tests.
• The interface is in English, Hindi and Bengali. AI-written text, and Hindi or Bengali words inside text in another language, carry their own lang, so screen readers pronounce them correctly.

Details in docs/ACCESSIBILITY.md.

Documentation

Document	What it covers
Architecture	Components, data model, request pipeline and performance
How Mehfil uses Gemini	Tasks, prompts, schemas, guardrails, resilience and the evaluation
Security	Threat model with evidence, data and privacy
Accessibility	WCAG 2.2 AA approach and how it is tested
Testing	Test layers, coverage gates and how to run each suite
Design	Occasion looks, tokens, type, motion and the celebration moments
Deployment	Free deployment on Vercel and Firebase, step by step
Decisions	Architecture decision records
AGENTS.md	Conventions for AI coding agents and new contributors

Acknowledgements

Built for PromptWars Virtual 2026 by Hack2skill and Google for Developers. Fonts come from Google Fonts through Fontsource (SIL Open Font License) and interface icons from Lucide (ISC License). The festival photographs are openly licensed works by I.Mahesh, Symphoney Symphoney, Subhrajyoti07, Aditi Singh 7, AjoyDutta1997, iwhosee, Ryan Harvey, TAPAS KUMAR HALDER, Azimronnie and onejeet, from Wikimedia Commons and Flickr (CC BY-SA, CC BY and CC0); each work, author and licence is listed in src/client/photos/CREDITS.md and in the app's footer.

License

MIT © 2026 Bishal Roy