System Requirements Document for zevi-ai

1. Introduction

zevi-ai (product name: ReviewReply AI) is a Micro-SaaS web application for local business owners — cafes, salons, clinics, and gyms — who need to answer customer reviews quickly and well. The product's intent is to remove the blank-page problem from review response: an owner pastes a customer review, picks a tone of reply, and receives a short, professional, polite, culturally appropriate reply that is ready to copy-paste directly into Google Maps or Instagram.

The audience is a single, non-technical owner-operator working on a phone between customers. The product must therefore be fast, calm, and unambiguous: one composer, one tone choice, one generate action, one reply sheet, and two ways to move the reply out (clipboard or WhatsApp). A mockup subscription offer ("Starter Plan - ₹499/month") is presented as integration-ready, linking to a placeholder Razorpay payment gateway URL rather than a live payment integration.

The emotional register is deliberate. Review replies are a hospitality act, not a data act, so the interface is designed around emptiness, paper, and quiet rather than dashboard density.

2. System Overview

zevi-ai is a responsive web application with four first-party surfaces: a public Landing page, a Sign Up page, a Login page, and a protected Dashboard. Identity is application-owned and established by self-service email/password enrollment, with returning email/password verification before the Dashboard becomes available. Authentication may be implemented with Supabase or local state.

The Dashboard is the working surface. It contains a review textarea, a tone-of-reply selector with four options, a prominent "Generate AI Reply" button, a dedicated output box for the generated reply, "Copy to Clipboard" and "Send via WhatsApp" actions, and the Starter Plan pricing card. AI generation is performed by a backend API that calls OpenAI (GPT-4o-mini or GPT-3.5-turbo) securely — the client never holds or calls the provider directly. Empty-input and API-timeout conditions are handled with visible, recoverable error states.

Actors:

• Local Business Owner — the only active human persona. Owns and runs a local business, signs in, pastes reviews, chooses tones, generates replies, and copies or shares them.
• OpenAI — external AI provider, reached only through the backend API.
• WhatsApp — external destination that receives the formatted reply text via a share link.
• Razorpay (placeholder gateway URL) — external destination reached by the "Subscribe Now" button; the subscription section is a mockup and is not a live payment integration.

Narrow exclusions: there is no live payment processing, no review-platform integration or automated review import, no multi-user or team workspace, no role-based permission model, and no reply history or analytics. The pricing section is a display mockup only.

2a. Product Interpretation and Delivery Boundary

zevi-ai is delivered as a first-party web application. The Landing page is anonymously reachable and explains the product to a local business owner before any account exists. Because the owner independently begins using the product and no invitation, provisioning, or deployment bootstrap boundary is established, access is established by self-service email/password enrollment on Sign Up, and returning owners verify email/password on Login. The Dashboard is protected: its review text, tone selection, generated replies, and pricing offer are only available once identity is established. No differentiated permissions, roles, or shared-state visibility controls exist — every authenticated owner sees the same capabilities for their own work.

Two continuations leave the application by design. "Send via WhatsApp" hands the generated reply text to WhatsApp as a share link; the owner completes the send inside WhatsApp, which is an external destination and not a first-party surface. "Subscribe Now" hands off to a placeholder Razorpay payment gateway URL; because the subscription section is explicitly a mockup, no payment state, entitlement, or billing lifecycle is created or tracked in zevi-ai.

Current scope covers everything described in this document. There is no accepted future-horizon requirement beyond the current release; the mockup payment integration is the only explicitly deferred integration, and it is deferred as a placeholder rather than as a planned feature.

2c. Page Content and Component Coverage

Landing

• Information and state: Anonymous public entry. Explains ReviewReply AI, its local-business audience (cafes, salons, clinics, gyms), and what the product does — turn a pasted customer review into a short, ready-to-paste reply. No account state is required to read it.
• Primary action: Navigate to Sign Up to begin using the product.
• Supporting actions: Navigate to Login for returning owners.
• Domain entities: Product description, audience description, tone-of-reply concept, Starter Plan price reference (₹499/month).
• Component responsibilities: Hero region presenting the product promise; a demonstration of the product's own composer-and-reply flow rendered as a flat paper sheet containing a real pasted 1-star review and a composed reply beneath a hairline; a section describing the four tones of reply; a section describing the copy-to-clipboard and WhatsApp actions; a section presenting the Starter Plan pricing card; entry controls to Sign Up and Login.
• States: Loading — static content, no data fetch required. Empty — not applicable. Success — page renders fully. Error — not applicable to static content. Recovery — if a navigation target is unreachable, the owner can retry the entry control.

Sign Up

• Information and state: Anonymous identity-access surface. Collects the credentials needed to create an application-owned account for the local business owner.
• Primary action: Submit email and password to create the account and establish access to the Dashboard.
• Supporting actions: Navigate to Login if the owner already has an account; return to Landing.
• Domain entities: Owner email address, owner password, account identity.
• Component responsibilities: Email field; password field; submit control; inline validation messaging; link to Login.
• States: Loading — submit control shows an in-progress state while enrollment is processed. Empty — fields start empty with no error shown until submission is attempted. Success — account is created and the owner proceeds to the Dashboard. Error — invalid or already-registered email, weak or mismatched password, or enrollment failure is shown inline with the fields preserved for correction. Recovery — the owner corrects the field and resubmits, or switches to Login.

Login

• Information and state: Anonymous identity-access surface for a returning owner. Verifies previously established email/password credentials.
• Primary action: Submit email and password to verify identity and gain access to the Dashboard.
• Supporting actions: Navigate to Sign Up if the owner has no account; return to Landing.
• Domain entities: Owner email address, owner password, verified session.
• Component responsibilities: Email field; password field; submit control; inline error messaging; link to Sign Up.
• States: Loading — submit control shows an in-progress state while verification runs. Empty — fields start empty with no error shown until submission is attempted. Success — verification succeeds and the Dashboard opens. Error — incorrect credentials or verification failure is shown inline without revealing which field was wrong. Recovery — the owner retries, or navigates to Sign Up.

Dashboard

• Information and state: Protected working surface for the authenticated Local Business Owner. Holds the pasted customer review, the selected tone of reply, the generated reply, and the Starter Plan offer. A quiet greeting addresses the owner's business.
• Primary action: Paste a customer review, select a tone, and press "Generate AI Reply" to produce a reply.
• Supporting actions: "Copy to Clipboard" with a "Copied!" success toast; "Send via WhatsApp" to format the reply into a WhatsApp share link; "Subscribe Now" on the Starter Plan card to open the placeholder Razorpay payment gateway URL.
• Domain entities: Customer review text; tone of reply (Professional & Polite, Friendly & Casual, Apologetic / De-escalation, Hinglish / Local Style); generated reply text; Starter Plan price (₹499/month); placeholder Razorpay payment gateway URL.
• Component responsibilities:
  • Review textarea for pasting the customer review.
  • Tone selector presented as four stacked radio rows, each with a label and a one-line description; the selected row is marked by a terracotta underline that moves between rows.
  • Full-width "Generate AI Reply" button, whose loading state is a thin terracotta line filling left-to-right beneath it.
  • Dedicated output box presenting the generated reply as a second sheet of paper.
  • "Copy to Clipboard" and "Send via WhatsApp" text buttons beneath a single rule.
  • Toast notification region for the "Copied!" confirmation.
  • Starter Plan pricing card with the "Subscribe Now" button.
• States: Loading — the Generate button's underline fills while the backend calls OpenAI; the reply sheet is not yet shown. Empty — before any generation, the output box is absent or empty and no reply text is displayed. Success — the reply sheet appears with the generated reply, and Copy and WhatsApp actions become usable. Error — empty review input is rejected with a visible message and no generation attempt; an API timeout or provider failure shows a visible error with the review text and tone selection preserved. Recovery — the owner can retry generation with the same input, edit the review, or change the tone and generate again.

3. Functional Requirements

FR-1 — Self-service account creation As a Local Business Owner, I should be able to create an account with my email and password so that I can begin using ReviewReply AI without an invitation or provisioning step.

• Provenance: required_inference (enrollment mechanics for the explicit authentication requirement)
• Lifecycle: Trigger — the owner submits email and password on Sign Up. Input — email address, password. Observable result — an application-owned account is created and the owner gains access to the Dashboard. Access state — anonymous entry surface; the Dashboard is protected. Failure/recovery — invalid, already-registered, or weak credentials are reported inline with fields preserved for correction. Continuation — the owner proceeds to the Dashboard, or switches to Login.

FR-2 — Returning owner verification As a Local Business Owner, I should be able to log in with my email and password so that I can return to my Dashboard and continue answering reviews.

• Provenance: required_inference (verification mechanics for the explicit authentication requirement)
• Lifecycle: Trigger — the owner submits email and password on Login. Input — email address, password. Observable result — identity is verified and the Dashboard opens. Access state — anonymous entry surface; protected state remains unavailable until verification succeeds. Failure/recovery — incorrect credentials are reported inline without disclosing which field failed; the owner retries or navigates to Sign Up. Continuation — the owner works in the Dashboard.

FR-3 — Paste a customer review As a Local Business Owner, I should be able to paste a customer review into a clean input textarea on the Dashboard so that the AI has the review text to respond to.

• Provenance: explicit
• Lifecycle: Trigger — the owner pastes or types review text into the textarea. Input — the customer review text. Observable result — the review text is held in the composer and is available to the Generate action. Access state — Dashboard requires login. Failure/recovery — empty input is rejected at generation time with a visible message. Continuation — the owner selects a tone and generates.

FR-4 — Select the tone of reply As a Local Business Owner, I should be able to choose the tone of reply from four options so that the generated reply matches the situation and my business's voice.

• Provenance: explicit
• Lifecycle: Trigger — the owner selects one of the four tone options. Input — one of: Professional & Polite (Standard); Friendly & Casual (for cafes/salons); Apologetic / De-escalation (for negative 1-star or 2-star reviews); Hinglish / Local Style (engaging and warm). Observable result — the selected tone is visibly marked and its one-line helper description is shown. Access state — Dashboard requires login. Failure/recovery — if no tone is selected, the default Professional & Polite (Standard) applies. Continuation — the owner generates the reply with the chosen tone.

FR-5 — Generate the AI reply As a Local Business Owner, I should be able to press a prominent "Generate AI Reply" button so that a ready-to-use reply is produced from my review and selected tone.

• Provenance: explicit
• Lifecycle: Trigger — the owner presses "Generate AI Reply". Input — the pasted review text and the selected tone. Observable result — a generated reply is returned and displayed in the dedicated output box. Access state — Dashboard requires login. Failure/recovery — empty review input is rejected with a visible message and no generation attempt; an API timeout or provider failure shows a visible error with the review text and tone preserved so the owner can retry. Continuation — the owner copies or shares the reply, or regenerates.

FR-6 — Secure backend AI processing As a Local Business Owner, I should have my review sent to OpenAI through a secure backend API so that my generation works without exposing provider credentials in the browser.

• Provenance: explicit (backend-only provider calls); required_inference (backend execution mechanics)
• Lifecycle: Trigger — the Dashboard requests generation. Input — review text, selected tone, and the system prompt instruction. Observable result — the backend calls OpenAI using GPT-4o-mini or GPT-3.5-turbo and returns the reply text to the Dashboard. Access state — server-side only; the client never calls the provider directly. Failure/recovery — provider errors and timeouts surface to the Dashboard as a recoverable error state. Continuation — the reply is displayed, or the owner retries.

FR-7 — System prompt instruction As a Local Business Owner, I should have the AI instructed as an expert customer service manager for local businesses so that replies are short, engaging, culturally appropriate, and ready to paste.

• Provenance: explicit
• Lifecycle: Trigger — every generation request. Input — the exact instruction: "You are an expert customer service manager for local businesses. Write a short, engaging, and culturally appropriate reply to the customer review provided, using the selected tone. Keep it ready to copy-paste directly to Google Maps or Instagram." Observable result — the returned reply is short, engaging, culturally appropriate, and directly pasteable into Google Maps or Instagram. Access state — applied server-side. Failure/recovery — a reply that fails to meet these constraints is regenerated by the owner. Continuation — the reply is displayed in the output box.

FR-8 — Display the generated reply As a Local Business Owner, I should see the generated reply clearly in a dedicated output box so that I can read and judge it before using it.

• Provenance: explicit
• Lifecycle: Trigger — a successful generation response. Input — the generated reply text. Observable result — the reply appears in its own dedicated box, visually distinct from the composer. Access state — Dashboard requires login. Failure/recovery — on failure the box shows the error state instead of stale or partial text. Continuation — the owner copies or shares the reply.

FR-9 — Copy to clipboard As a Local Business Owner, I should be able to copy the generated reply with one button so that I can paste it into Google Maps or Instagram.

• Provenance: explicit
• Lifecycle: Trigger — the owner presses "Copy to Clipboard". Input — the generated reply text. Observable result — the reply is placed on the clipboard and a success toast reading "Copied!" appears. Access state — Dashboard requires login; the action is available once a reply exists. Failure/recovery — if the clipboard write fails, no success toast is shown and the owner can retry or select the text manually. Continuation — the owner pastes the reply into Google Maps or Instagram.

FR-10 — Send via WhatsApp As a Local Business Owner, I should be able to send the generated reply via WhatsApp with a quick-action button so that I can move it out of the app in one step.

• Provenance: explicit (share action); required_inference (external continuation mechanics)
• Lifecycle: Trigger — the owner presses "Send via WhatsApp". Input — the generated reply text. Observable result — the text is formatted into a WhatsApp share link and WhatsApp opens with the reply ready to send. Access state — Dashboard requires login; the action is available once a reply exists. Failure/recovery — if WhatsApp cannot be opened, the owner can still copy the reply to the clipboard. Continuation — the owner completes the send inside WhatsApp, an external destination.

FR-11 — Starter Plan pricing display As a Local Business Owner, I should see a simple pricing card showing "Starter Plan - ₹499/month" so that I understand the offer.

• Provenance: explicit
• Lifecycle: Trigger — the owner views the pricing section. Input — none. Observable result — a single pricing card displays "Starter Plan - ₹499/month". Access state — visible on the Dashboard; the offer is a mockup. Failure/recovery — not applicable to static display. Continuation — the owner may press "Subscribe Now".

FR-12 — Subscribe Now placeholder handoff As a Local Business Owner, I should be able to press "Subscribe Now" and be taken to the placeholder Razorpay payment gateway URL so that the subscription flow is integration ready.

• Provenance: explicit (mockup, integration ready); required_inference (external continuation mechanics)
• Lifecycle: Trigger — the owner presses "Subscribe Now". Input — none. Observable result — the placeholder Razorpay payment gateway URL opens. Access state — Dashboard requires login. Failure/recovery — because this is a mockup, no payment state or entitlement is created; if the URL does not resolve, the owner remains on the Dashboard with no change to their access. Continuation — the owner returns to the Dashboard; no subscription is activated in zevi-ai.

FR-13 — Empty input error handling As a Local Business Owner, I should be told clearly when I try to generate without pasting a review so that I know what to fix.

• Provenance: explicit
• Lifecycle: Trigger — the owner presses "Generate AI Reply" with an empty or whitespace-only review. Input — empty review text. Observable result — a visible validation message is shown and no generation request is made. Access state — Dashboard requires login. Failure/recovery — the message clears once valid review text is entered. Continuation — the owner pastes a review and generates.

FR-14 — API timeout error handling As a Local Business Owner, I should be told clearly when the AI request times out or fails so that I can retry without losing my work.

• Provenance: explicit
• Lifecycle: Trigger — the backend call to OpenAI times out or returns an error. Input — the in-flight generation request. Observable result — a visible error state replaces the loading state, and the review text and tone selection remain intact. Access state — Dashboard requires login. Failure/recovery — the owner retries generation with the same input, edits the review, or changes the tone. Continuation — a successful retry displays the reply in the output box.

FR-15 — Responsive, fast, micro-interaction-driven interface As a Local Business Owner, I should be able to use zevi-ai comfortably on my phone and on a desktop with fast loading and smooth micro-interactions so that answering a review takes seconds.

• Provenance: explicit
• Lifecycle: Trigger — the owner opens any page on a mobile phone or desktop. Input — viewport size and interaction. Observable result — the layout adapts seamlessly across mobile and desktop, pages load quickly, and loading indicators and toast notifications provide smooth feedback. Access state — applies to all surfaces. Failure/recovery — controls remain fully visible and usable at every viewport. Continuation — the owner completes their task without layout friction.

4. User Personas

Local Business Owner

Product context. The owner runs a local business — a cafe, salon, clinic, or gym — and is the person who answers the business's public reviews. They are not a marketer or a data analyst; they are an operator who is often standing at the counter, between customers, holding a phone. Reviews arrive unpredictably, and a 1-star review carries real emotional weight and real reputational stakes. Writing a reply that is professional, polite, and de-escalating is exactly the task they most want to avoid doing from scratch.

Primary goal. Turn a customer review into a professional, polite, de-escalating reply that is ready to paste into Google Maps or Instagram, without writing it themselves.

Distinct accepted responsibilities.

• Create an account with email and password, and log back in on return visits.
• Paste a customer review into the Dashboard textarea.
• Choose the tone of reply that fits the situation: Professional & Polite (Standard) for ordinary replies, Friendly & Casual for cafes and salons, Apologetic / De-escalation for negative 1-star or 2-star reviews, and Hinglish / Local Style for engaging, warm replies.
• Press "Generate AI Reply" and wait for the reply to appear.
• Read the generated reply in its dedicated output box and judge whether it is usable.
• Copy the reply to the clipboard, or send it via WhatsApp.
• View the Starter Plan offer at ₹499/month and, if interested, press "Subscribe Now".

Relevant inputs and decisions. The review text itself; which of the four tones matches the review's sentiment and the business's voice; whether the generated reply is good enough to use as-is; and whether to copy it or route it through WhatsApp. The owner also decides how to react when generation fails — retry, edit the review, or change the tone.

Interactions with other accepted participants. The owner's work is handed off twice. The backend AI processing returns the reply to the owner's Dashboard, and the owner is the one who judges and uses it. "Send via WhatsApp" hands the reply text to WhatsApp, where the owner completes the send. "Subscribe Now" hands off to the placeholder Razorpay payment gateway URL, which is a mockup and creates no subscription state in zevi-ai.

Observable success. A short, engaging, culturally appropriate reply appears in the output box, matches the selected tone, and is ready to paste directly into Google Maps or Instagram — with a "Copied!" toast confirming the clipboard action, or WhatsApp open with the reply ready to send.

Constraints carried from source. The owner works on both mobile phones and desktops, so every control must remain fully usable at both. The owner is the only active human role; there is no team, no shared workspace, and no permission model to navigate.

5. Core User Flows

Flow 1 — First-time owner creates an account and generates a first reply

1. The Local Business Owner opens Landing anonymously and reads what ReviewReply AI does, who it is for, and how the four tones and the copy/WhatsApp actions work.
2. The owner selects the entry control to Sign Up.
3. On Sign Up, the owner enters an email address and a password and submits.
4. The account is created and the owner arrives at the protected Dashboard. If the email is already registered or the password is rejected, an inline message appears, the entered values are preserved, and the owner corrects the field and resubmits — or switches to Login.
5. On the Dashboard, the owner pastes a customer review into the review textarea.
6. The owner selects a tone of reply from the four stacked radio rows. The selected row is marked and its one-line description is shown. If the owner skips this, Professional & Polite (Standard) applies.
7. The owner presses "Generate AI Reply". A thin terracotta line fills left-to-right beneath the button while the backend calls OpenAI.
8. The generated reply appears in the dedicated output box as a second sheet of paper. The owner reads it and confirms it is short, appropriate to the tone, and ready to paste.
9. The owner presses "Copy to Clipboard". A toast reading "Copied!" confirms the action.
10. The owner pastes the reply into Google Maps or Instagram. The task is complete.

Flow 2 — Returning owner answers a negative review with de-escalation

1. The owner opens Login and submits their email and password.
2. Verification succeeds and the Dashboard opens. If the credentials are wrong, an inline message appears without disclosing which field failed, and the owner retries or navigates to Sign Up.
3. The owner pastes a 1-star review into the review textarea.
4. The owner selects Apologetic / De-escalation, the tone intended for negative 1-star or 2-star reviews.
5. The owner presses "Generate AI Reply" and waits while the loading line fills.
6. The reply appears in the output box. The owner judges that it is appropriately apologetic and de-escalating.
7. The owner presses "Send via WhatsApp". The reply text is formatted into a WhatsApp share link and WhatsApp opens with the reply ready to send.
8. The owner completes the send inside WhatsApp, an external destination, and returns to the Dashboard.

Flow 3 — Owner recovers from an empty input

1. The owner is on the Dashboard with an empty review textarea.
2. The owner presses "Generate AI Reply" without pasting a review.
3. A visible validation message appears and no generation request is made.
4. The owner pastes the customer review. The message clears.
5. The owner selects a tone and presses "Generate AI Reply" again. The reply appears in the output box.

Flow 4 — Owner recovers from an API timeout

1. The owner has pasted a review and selected a tone on the Dashboard, and has pressed "Generate AI Reply".
2. The backend call to OpenAI times out or returns an error.
3. The loading state is replaced by a visible error state. The review text and the tone selection remain intact.
4. The owner presses "Generate AI Reply" again to retry with the same input.
5. The retry succeeds and the reply appears in the output box, ready to copy or send via WhatsApp.

Flow 5 — Owner reviews the Starter Plan offer

1. The owner is on the Dashboard and scrolls to the pricing section.
2. A single pricing card displays "Starter Plan - ₹499/month".
3. The owner presses "Subscribe Now".
4. The placeholder Razorpay payment gateway URL opens. Because this section is a mockup, no payment is processed and no subscription state is created in zevi-ai.
5. The owner returns to the Dashboard with their access unchanged.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Kenya Hara, and the headline idea is "Emptiness as content: a review inbox that breathes." Review replies are a hospitality act, not a data act, so the interface is set like a well-laid table: one calm object per screen, vast breathing space, whispering type, and natural paper tones. The generic indigo/blue-on-white SaaS template is explicitly forbidden for this project.

Colour tokens (light mode).

No blues, no gradients, no glass. Ink on paper contrast is approximately 13:1 and accent on paper approximately 5.1:1 — both readable at body size.

Typography.

• Headings: Shippori Mincho — refined Japanese serif at light-to-regular weight, wide tracking (0.02em), sentence case, set generously large with abundant leading. Never bold-shouting, never all-caps.
• Body: Zen Kaku Gothic New.
• Scale: 1.25 modular — 40 / 32 / 25 / 20 / 16 / 14.
• Hero headline: clamp(34px, 7vw, 68px).
• Section titles: clamp(24px, 3.4vw, 36px).
• Body: 16px / 1.75.
• Micro-labels: 12px with 0.14em tracking.
• Numerals in the price card are tabular.

Shape language. Square and near-square proportions with 2px radii at most — paper edges, not pills. Thin 1px hairline rules in #DED8CC separate sections. The only filled shapes are the charcoal Generate button (a clean rectangle) and the terracotta tone-chip underline. No blobs, no soft shadows, no rounded-3xl cards; depth comes from a single 1px border and a barely-there 0 1px 0 rgba(34,32,29,0.04) hairline.

Layout. A single centred column capped at 640px for the composer → output flow, inside a wide 1040px outer frame so margins stay vast on desktop. Vertical rhythm is sectioned by full-width hairline rules with generous 96px / 56px padding. Dashboard order: quiet greeting with the business name, review textarea, tone selector as four stacked radio rows (each a label plus a one-line description), full-width Generate button, then the reply sheet appearing below as a second sheet of paper. Pricing sits as one centred card, not a three-column grid. On mobile the layout is the identical single column with 20px gutters, controls full-width and never cropped.

Imagery. No photography of people, no 3D, no illustration. Imagery is material and typographic: a subtle paper grain at 3% opacity over the ground, a single ink-brush stroke used as the divider above the hero headline, and thin topographic-like hairlines in the empty right margin of the desktop hero. The product's own UI is the only "screenshot" — shown as a flat paper sheet with a hairline border and one line of charcoal text.

7. Signature Design Concept

Hero as two sheets of paper.

The public entry is composed as two sheets on unbleached paper, and it could not be mistaken for SaaS.

• Left sheet (7 of 12 columns). A two-line Shippori Mincho headline at clamp(34px, 7vw, 68px) — "Answer every review. / Keep your calm." — set flush-left on the #F4F1EA ground. Above it sits a single 48px terracotta ink-brush rule in #A8442A. Beneath it, one 16px line in muted #8C857A. No centred stack, no subtext-plus-button, no gradient, no device mockup.
• Right sheet (5 of 12 columns). Nothing but a flat paper sheet — #FBF9F5 surface, 1px #DED8CC border — containing a real pasted 1-star review in charcoal, and, under a hairline, a composed reply in the same type. The product is demonstrated as a material object rather than a screenshot with a blue button. This is the only image on the page.
• Mobile. The sheet drops below the headline, full-width, with 20px gutters, and both remain readable in full.

The signature moves carry through the rest of the product: the tone selector is four stacked radio rows whose selected row is marked by a 2px terracotta underline that slides between rows rather than a filled pill; the Generate button is a full-width charcoal rectangle whose only loading state is a thin terracotta line filling beneath it left-to-right, with no spinner and no skeleton; the generated reply appears as a second sheet of paper that rises 4px and fades in, with Copy and WhatsApp as two hairline-outlined text buttons beneath a single rule — never two coloured buttons; and hairline rules in #DED8CC act as the entire section system, with each section label set in 12px tracked muted caps sitting on the line.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

The direction sets a still tempo and a flat depth ceiling deliberately: it keeps the product fast on cheap Android phones and honest about its purpose. Motion is almost none.

Landing Hero Motion Brief

• Focal subject. The bordered reply sheet in the right five columns — a real pasted 1-star review in charcoal with a composed reply beneath a hairline, on #FBF9F5 with a 1px #DED8CC border.
• Input → transformation → outcome thesis. The owner's pasted review is the input; the selected tone shapes the transformation; the composed reply on the sheet is the outcome. The hero shows that transformation as a finished material object rather than animating it, so the promise is legible in the first frame.
• Motion vocabulary. 200ms opacity and 4px rise when a sheet appears; 120ms background shift on button press; a slow 400ms crossfade when the tone selection changes the helper line. Nothing else.
• Composed first frame. Flush-left oversized Shippori Mincho headline on unbleached paper, the 48px terracotta ink-brush rule above it, one muted 16px line beneath, and the bordered reply sheet beside it — all fully rendered, nothing waiting to animate in.
• Reduced-motion state. With prefers-reduced-motion, fades only — no translate. The reply sheet appears without the 4px rise, and the tone helper line changes without the crossfade. The hero is fully readable and complete as a static arrangement.

No 3D or WebGL scene is required or requested; the hero is flat by direction.

9. Non-Functional Requirements

• NFR-1 — Responsive design. The interface must work seamlessly on both mobile phones and desktops. Provenance: explicit. Rationale: the owner works on a phone between customers and on a desktop at the counter. Readable text and controls stay whole at 375px, 768px, and 1280px, wrapping or scaling to fit, and no other element covers any part of them.
• NFR-2 — Fast loading. Pages must load quickly, with smooth micro-interactions including loading indicators and toast notifications. Provenance: explicit. Rationale: the owner answers reviews in short gaps between customers, and the direction's still tempo and flat depth ceiling exist to keep the product fast on cheap Android phones.
• NFR-3 — Secure provider access. AI provider calls must be made securely via a backend API, not directly from the client. Provenance: explicit hard constraint. Rationale: provider credentials must never be exposed in the browser.
• NFR-4 — Model constraint. The AI model must be OpenAI GPT-4o-mini or GPT-3.5-turbo. Provenance: explicit hard constraint. Rationale: the source specifies these models exactly.
• NFR-5 — Reply quality constraint. The generated reply must be short, engaging, culturally appropriate, and ready to copy-paste directly to Google Maps or Instagram. Provenance: explicit hard constraint. Rationale: the reply is the product's entire output and must be usable without editing.
• NFR-6 — Authentication implementation constraint. Authentication may be implemented with Supabase or local state. Provenance: explicit hard constraint. Rationale: the source permits either approach.
• NFR-7 — Mockup subscription constraint. The pricing/subscription section is a mockup that is integration ready; the "Subscribe Now" button links to a placeholder payment gateway URL (Razorpay) rather than a live payment integration. Provenance: explicit hard constraint. Rationale: no live payment processing is in scope, and no subscription state or entitlement is created in zevi-ai.
• NFR-8 — Error handling. Proper error handling is required for empty inputs and API timeouts. Provenance: explicit. Rationale: the owner must always know what went wrong and be able to recover without losing their pasted review or tone selection.
• NFR-9 — Code structure and deployability. The code must be well-structured, modular, and ready to deploy immediately. Provenance: explicit. Rationale: the source requires immediate deployability.
• NFR-10 — Accessibility of motion. With prefers-reduced-motion, motion reduces to fades only, with no translate. Provenance: required_inference from the creative direction's reduced-motion requirement. Rationale: the direction's motion must remain usable for owners who have reduced motion enabled.

10. Tech Stack

• Frontend: React web application styled with Tailwind CSS, using a modern, minimalist interface. Provenance: explicit (Tailwind CSS); required_inference (React as the component framework for a modular, immediately deployable web app).
• Typography: Shippori Mincho for headings and Zen Kaku Gothic New for body text, loaded as web fonts. Provenance: explicit from the creative direction.
• Authentication: Email/password authentication implemented with Supabase or local state. Provenance: explicit hard constraint.
• Backend: A backend API service that holds the OpenAI credentials and performs generation calls server-side. Provenance: explicit hard constraint that provider calls are backend-only.
• AI provider: OpenAI, using GPT-4o-mini or GPT-3.5-turbo. Provenance: explicit hard constraint.
• Storage: Application-owned account identity (email and password credential) must persist so returning owners can log in. Provenance: required_inference from the accepted enrollment and returning-verification journeys. No review history, reply history, or analytics storage is in scope.
• Payments: None. The "Subscribe Now" button links to a placeholder Razorpay payment gateway URL only. Provenance: explicit hard constraint.
• Deployment: The application must be ready to deploy immediately. Provenance: explicit.

11. Assumptions and Constraints

Assumptions.

• The Local Business Owner is the only active human role; there is no team, staff, or shared-workspace usage. [Assumption — derived from the closed persona catalog]
• The owner supplies the review text by pasting it; zevi-ai does not connect to Google Maps, Instagram, or any review platform to import reviews. [Assumption — no import capability is stated in the source]
• The owner has an OpenAI API key available to the backend deployment. [Assumption — required for the explicit backend-to-OpenAI integration]
• The owner has WhatsApp available on the device used to send replies. [Assumption — required for the explicit WhatsApp share action]
• The placeholder Razorpay payment gateway URL is supplied at configuration time. [Assumption — the source specifies a placeholder URL, not a live integration]

Constraints.

• AI provider calls must be made securely via a backend API, not directly from the client. (explicit)
• The AI model must be OpenAI GPT-4o-mini or GPT-3.5-turbo. (explicit)
• Authentication may be implemented with Supabase or local state. (explicit)
• The pricing/subscription section is a mockup that is integration ready; "Subscribe Now" links to a placeholder payment gateway URL (Razorpay) rather than a live payment integration. (explicit)
• The generated reply must be short, engaging, culturally appropriate, and ready to copy-paste directly to Google Maps or Instagram. (explicit)
• The generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit, creative direction)
• No gradients, glassmorphism, coloured blobs, or drop-shadowed cards; no rounded pill buttons or rounded-3xl containers; no stock photography of people or 3D device mockups; no motion beyond a 200ms fade and 4px rise; no bouncing and no parallax; no multiple accent colours or a colour per tone option; no bold all-caps headings or heavy grotesque display type. (explicit, creative direction)
• Readable text and controls stay whole at every viewport; where the direction asks for a cropped or bled gesture, it is carried by imagery or decoration instead. (explicit, creative direction)

Out of scope.

• Live payment processing, billing lifecycle, and subscription entitlement tracking.
• Review-platform integration or automated review import.
• Multi-user, team, or shared-workspace features.
• Role-based permissions or differentiated visibility over shared state.
• Reply history, saved replies, and analytics.

12. Glossary

• zevi-ai — The project name for this application.
• ReviewReply AI — The product name of the application described in this document.
• Local Business Owner — The single active human persona: the operator of a cafe, salon, clinic, or gym who answers the business's public reviews.
• Tone of Reply — The selected style applied to the generated reply. The four options are Professional & Polite (Standard), Friendly & Casual (for cafes/salons), Apologetic / De-escalation (for negative 1-star or 2-star reviews), and Hinglish / Local Style (engaging and warm).
• Generate AI Reply — The prominent Dashboard button that submits the pasted review and selected tone for AI processing.
• Reply sheet — The dedicated output box in which the generated reply is displayed, presented as a second sheet of paper.
• System prompt instruction — The fixed instruction sent with every generation request: "You are an expert customer service manager for local businesses. Write a short, engaging, and culturally appropriate reply to the customer review provided, using the selected tone. Keep it ready to copy-paste directly to Google Maps or Instagram."
• Starter Plan — The mockup subscription offer displayed as "Starter Plan - ₹499/month".
• Placeholder payment gateway URL — The Razorpay URL opened by "Subscribe Now"; it is a placeholder, not a live payment integration.
• Hairline rule — The 1px #DED8CC line that forms the entire section system in the interface.
• Paper ground — The unbleached #F4F1EA background on which all pages are set.