System Requirements Document

Batangas Lowkey Eatery

1. Introduction

1.1 Purpose

This System Requirements Document (SRD) defines the requirements for Batangas Lowkey Eatery, a free, mobile-first, installable web directory (PWA) that helps people discover verified, hidden local eateries in Batangas City. The system centers on small eateries, street food stalls, and turo-turo spots that delivery apps and tourist-focused platforms overlook, and it is built for locals with barangay-level detail.

The requirement set in this document is derived from the project's Value Proposition Canvas / Lean Canvas submission and the explicit capability specification provided by the project team.

1.2 Problem Statement

The system exists to address the following stated problems:

• Small local eateries are missing or invisible online.
• Facebook posts about food spots are scattered and disorganized.
• Delivery apps charge fees and markups that do not serve a discovery-only need.
• Existing reviews feel tourist-focused rather than local.
• It is hard to tell which food-spot information is trustworthy.

1.3 Scope Summary

The system is a directory only. It provides discovery, verification, sharing, reviews, favorites, and promotion surfaces. It explicitly does not provide online ordering, delivery, or payment processing. Revenue is generated through promoted listings and featured vendor spotlights.

1.4 Intended Readership

This SRD is written for the project team building and deploying the application, and for reviewers validating that the delivered product matches the agreed capabilities.

2. System Overview

Batangas Lowkey Eatery is a responsive, mobile-first, PWA-installable web application organized around three user roles:

The system maintains a curated, verifiable catalog of eateries with barangay-level location detail, locally sourced reviews, and a trust signal in the form of a "Locally Verified" badge awarded by Admin after review. Discovery is organized around categories (Eatery, Street Food, Turo-turo), barangay proximity, budget-friendly price range, and a verified-only filter.

Content surfaces include a Discover Hidden Gems section and a Featured / Promoted section that is clearly labeled as promoted. Every eatery has a shareable, QR-code-friendly URL.

The application is delivered as a mobile-first progressive web app with a bottom navigation bar on mobile and a top navbar on desktop, optimized for fast loading on slow mobile data.

3. Functional Requirements

Functional requirements are expressed as user stories. Each distinct capability is captured as its own story.

3.1 Diner — Discovery & Home

• FR-1 — As a diner, I want a home page with a search bar so that I can immediately look for an eatery by name.
• FR-2 — As a diner, I want category chips for Eatery, Street Food, and Turo-turo so that I can narrow the listing to the type of food spot I want.
• FR-3 — As a diner, I want a "Near my barangay" filter so that I can see dining options closest to where I am.
• FR-4 — As a diner, I want a "Discover Hidden Gems" section so that I can find small, lesser-known local eateries that are not surfaced by mainstream apps.
• FR-5 — As a diner, I want a "Featured / Promoted" section that is clearly labeled as promoted so that I can distinguish paid placement from organic listings.
• FR-6 — As a diner, I want the home page to render a card grid of eateries so that I can scan multiple options at once.

3.2 Diner — Search & Filtering

• FR-7 — As a diner, I want to search eateries by name so that I can find a specific spot I already know about.
• FR-8 — As a diner, I want to filter by category so that I can restrict results to eateries, street food, or turo-turo.
• FR-9 — As a diner, I want to filter by barangay so that I can limit results to a specific local area.
• FR-10 — As a diner, I want to filter by price range (budget-friendly) so that I only see meals I can afford.
• FR-11 — As a diner, I want a "Verified only" filter so that I can restrict results to listings that have been validated by the platform.

3.3 Diner — Eatery Detail Page

• FR-12 — As a diner, I want the eatery detail page to display photos so that I can see what the food and the place look like before going.
• FR-13 — As a diner, I want the eatery detail page to display a description so that I understand what the eatery offers.
• FR-14 — As a diner, I want the eatery detail page to display the address so that I know where to go.
• FR-15 — As a diner, I want the eatery detail page to display the barangay so that I can judge how near it is to me.
• FR-16 — As a diner, I want the eatery detail page to display opening hours so that I do not travel to a closed eatery.
• FR-17 — As a diner, I want the eatery detail page to display the price range so that I can confirm it fits my budget.
• FR-18 — As a diner, I want the eatery detail page to display menu highlights so that I know what is worth ordering.
• FR-19 — As a diner, I want the eatery detail page to display contact info so that I can reach the eatery directly.
• FR-20 — As a diner, I want the eatery detail page to display a map link so that I can navigate to the eatery.
• FR-21 — As a diner, I want the eatery detail page to display a "Locally Verified" badge so that I can trust that the listing information has been checked.

3.4 Diner — Engagement & Sharing

• FR-22 — As a diner, I want to post local reviews and ratings, with login required to post, so that other locals get authentic, non-tourist-focused feedback.
• FR-23 — As a diner, I want to save favorites, with login required, so that I can keep a personal shortlist of eateries to return to.
• FR-24 — As a diner, I want a share button supporting Facebook, Messenger, and copy link so that I can send an eatery to friends and family easily.
• FR-25 — As a diner, I want a QR-code-friendly URL for each eatery so that I can share or scan a listing in person without typing.

3.5 Vendor

• FR-26 — As a vendor, I want to register and log in so that I can manage my presence on the platform.
• FR-27 — As a vendor, I want to claim an existing eatery listing or submit a new one so that my eatery appears on the directory.
• FR-28 — As a vendor, I want a dashboard to edit my eatery details so that my listing stays accurate.
• FR-29 — As a vendor, I want to manage my eatery photos from the dashboard so that diners see current images of my food and stall.
• FR-30 — As a vendor, I want to edit my opening hours from the dashboard so that diners know exactly when I am open.
• FR-31 — As a vendor, I want to edit my menu highlights from the dashboard so that diners know my specialty dishes.
• FR-32 — As a vendor, I want to view basic stats (page views, searches, saves) so that I can see how much attention my listing is getting.
• FR-33 — As a vendor, I want to request a promoted listing or featured spotlight so that I can gain extra visibility.

3.6 Admin

• FR-34 — As an admin, I want to review submitted listings and approve or reject them so that only legitimate eateries appear in the directory.
• FR-35 — As an admin, I want to mark listings as "Locally Verified" with verification notes so that the trust badge carries documented justification.
• FR-36 — As an admin, I want to manage categories so that the directory taxonomy stays accurate.
• FR-37 — As an admin, I want to manage barangays so that location filtering remains complete and consistent.
• FR-38 — As an admin, I want to manage users so that abusive or invalid accounts can be handled.
• FR-39 — As an admin, I want to manage promoted listings so that paid placements are correct, current, and clearly labeled.
• FR-40 — As an admin, I want a dashboard showing monthly active users so that I can track platform reach.
• FR-41 — As an admin, I want the dashboard to show the number of verified listings so that I can track catalog trust coverage.
• FR-42 — As an admin, I want the dashboard to show searches per user so that I can gauge how actively diners are searching.
• FR-43 — As an admin, I want the dashboard to show the number of vendors with promoted listings so that I can track the promotion revenue channel.

3.7 Responsive Layout & Navigation

• FR-44 — As a user, I want a mobile-first layout that scales up across 360px, 768px, 1024px, and 1280px breakpoints so that the app works well on phones, tablets, and desktops.
• FR-45 — As a mobile user, I want a bottom navigation bar so that primary destinations are reachable with my thumb.
• FR-46 — As a desktop user, I want a top navbar so that navigation suits a large screen.
• FR-47 — As a user, I want the eatery card grid to reflow to 1 column on mobile, 2 on tablet, and 3–4 on desktop so that scanning density matches my screen.
• FR-48 — As a user, I want touch-friendly buttons of at least 44px, readable fonts, and high-contrast colors so that the app is easy and comfortable to use.

3.8 Performance on Mobile Data

• FR-49 — As a user on slow mobile data, I want images to lazy-load so that pages become usable quickly.
• FR-50 — As a user on slow mobile data, I want compressed assets so that page weight stays low.
• FR-51 — As a user on slow mobile data, I want skeleton loaders so that I understand content is still loading.

3.9 Progressive Web App

• FR-52 — As a user, I want a web app manifest so that the app presents proper name, icons, and theme when installed.
• FR-53 — As a user, I want a service worker so that the app caches resources and loads reliably.
• FR-54 — As a user, I want to install the app via "Add to Home Screen" so that I can launch it like a native app.
• FR-55 — As a user, I want a basic offline page so that I get a clear message instead of a browser error when I have no connection.

3.10 Accessibility

• FR-56 — As a user relying on assistive technology, I want semantic HTML so that content structure is correctly conveyed.
• FR-57 — As a user relying on assistive technology, I want alt text on images so that food and eatery photos are described.
• FR-58 — As a keyboard user, I want full keyboard navigation so that I can use the app without a pointer.
• FR-59 — As a user relying on assistive technology, I want ARIA labels on interactive controls so that their purpose is announced.

4. User Personas

Personas are limited to active product roles with materially distinct workflows.

4.1 Diner (Public — Browse Without Login)

• Profile: Students, young workers, and families in Batangas City looking for cheap, filling meals nearby.
• Goals: Find an affordable, trustworthy eatery in or near their barangay; avoid delivery fees and markups; see local, not tourist, perspectives.
• Capabilities: Search, filter by category/barangay/price/verified, browse Home, Hidden Gems, and Promoted sections, open eatery detail pages, follow map links, share listings, and use QR-code-friendly URLs.
• Authenticated actions: Posts reviews and ratings and saves favorites only after logging in.

4.2 Vendor (Registered / Authenticated)

• Profile: Owner or operator of a small eatery, street food stall, or turo-turo spot.
• Goals: Get free online exposure, keep listing details accurate, and optionally buy additional visibility.
• Capabilities: Register/login, claim or submit a listing, edit details/photos/hours/menu highlights, view page views, searches, and saves, and request a promoted listing or featured spotlight.

4.3 Admin (Internal, Restricted Access)

• Profile: Platform operator responsible for catalog trust and content integrity.
• Goals: Keep the directory trustworthy, complete, and free of invalid listings.
• Capabilities: Review and approve/reject listings, mark listings "Locally Verified" with notes, manage categories, barangays, users, and promoted listings, and monitor platform metrics.

4.4 System Actors and External Recipients

• Supabase (Auth, Storage, PostgreSQL): System actor providing authentication, file storage, and data persistence.
• Map provider (Google Maps link or Leaflet/OpenStreetMap): System actor supplying map references and navigation links.
• Facebook and Messenger: Outbound-only share destinations. These are recipients of shared links, not personas.

5. Core User Flows

5.1 Diner — Find a Nearby Eatery

1. Diner opens the app on a phone; the Home page loads with skeleton loaders followed by the eatery card grid.
2. Diner taps the "Near my barangay" filter, or selects a category chip (Eatery / Street Food / Turo-turo).
3. Diner refines results with price range (budget-friendly) and optionally toggles "Verified only".
4. Diner scans the card grid (1 column on mobile) and taps a card to open the Eatery Detail page.
5. Detail page shows photos, description, address, barangay, opening hours, price range, menu highlights, contact info, and the map link. A "Locally Verified" badge appears if the listing is verified.
6. Diner taps the map link to navigate, or taps the share button to send the listing to Facebook, Messenger, or copy the link.
7. If the diner wants to leave a review or save the eatery, they are prompted to log in; after logging in they post the review/rating and save the favorite.

5.2 Diner — Discover a Hidden Gem

1. Diner scrolls to the "Discover Hidden Gems" section on the Home page.
2. Diner opens a hidden gem listing.
3. Diner shares the eatery's QR-code-friendly URL with a friend in person.
4. Diner logs in and saves the eatery to favorites.

5.3 Vendor — List and Manage an Eatery

1. Vendor registers or logs in.
2. Vendor claims an existing listing or submits a new eatery listing.
3. Listing enters the review queue with status pending (no verified badge, no promoted placement).
4. After Admin approval, the vendor opens the dashboard and edits details, photos, hours, and menu highlights.
5. Vendor reviews basic stats: page views, searches, and saves.
6. Vendor optionally requests a promoted listing or featured spotlight.

5.4 Admin — Verify and Operate

1. Admin logs into the restricted admin surface.
2. Admin opens the review queue and approves or rejects each submitted listing.
3. Admin marks approved listings as "Locally Verified" and records verification notes.
4. Admin manages categories and barangays as the catalog grows.
5. Admin manages users and manages promoted listings, ensuring promoted content remains correctly labeled.
6. Admin reviews the dashboard metrics: monthly active users, number of verified listings, searches per user, and vendors with promoted listings.

5.5 Any User — Install and Use Offline

1. User visits the app; the manifest and service worker register.
2. User chooses "Add to Home Screen" and installs the app.
3. On a later visit without connectivity, the user sees the basic offline page.

6. Visuals, Colors, and Theme

The design direction is warm, friendly, and local, with a food-inspired feel, clean cards, big food photos, simple icons, and short plain-language copy. A mix of English with light Filipino/Batangueño tone is expected in UI text.

The project-wide creative direction is "Big-hearted barangay boldness" (muse: Haraldur Thorleifsson): a hand-painted carinderia sign blown up to poster scale — big friendly type, confident colour blocking, chunky rounded cards, and character. Trust must read as "kapitbahay vouched for this", not "platform-certified". The generic indigo/blue-on-white SaaS template is forbidden for this project.

6.1 Color System (Light Mode)

The palette uses a cream ground with deep Batangas green as the brand colour and coral as the hot accent. Cream #FFF6E9 is the ground everywhere (never white-first); pure white is used only for cards and sheets.

Colour rules:

• Body text on cream and on green must stay at ink/white respectively; coral is never used behind body copy.
• Coral is used on roughly 8% of any screen at most.
• Sunflower #F5B31E and lake blue #2E7FA8 appear only as category code colours (Eatery / Street Food / Turo-turo) on chips and thin card rules.
• Blue/indigo primary or accent anywhere in the UI is forbidden.

6.2 Typography

• Headings: Sora at 700–800, tight tracking (-0.02em), sentence case with occasional all-caps for small labels. Headlines run large and friendly, wrapping to 2–3 lines, never thin. Barangay names and eatery names get the same bold weight so a place name feels like a headline.
• Body: Outfit.
• Scale: 1.25 modular on mobile, 1.333 from 768px up: 40/32/24/18/16 mobile, 72/48/28/18/16 desktop.
• Display headline clamp(40px, 9vw, 88px); section headings clamp(26px, 4vw, 40px); card titles 20–24px; body 16–17px with 1.6 line-height; micro-labels 12px uppercase +0.08em tracking.
• Plain, short sentences; no jargon. Inter, Roboto, Poppins, Manrope, and system-ui are forbidden for headings and body.

6.3 Shape Language

• Chunky and rounded: cards at 20–24px radius, buttons and chips fully pill (999px), photos inside cards rounded 16px with a 2px ink outline on the hero card only.
• Colour blocks are hard-edged rectangles that butt against each other like painted carinderia signage; no soft blobs, no glass, no thin hairlines except the 2px ink rules that separate sections.

6.4 Layout

• Mobile-first single column at 360px with a fixed bottom nav (Home, Search, Saved, Vendor) and a sticky search pill under the top bar.
• At 768px the card grid goes 2-up and the bottom nav becomes a top navbar; at 1024px 3-up with a left filter rail; at 1280px 4-up with the filter rail pinned and a wider hero.
• Sections are full-bleed horizontal bands alternating cream and a solid colour block (green or coral), each band opening with an oversized flush-left heading rather than a centred one.
• Cards never lift on hover — they get a 2px ink border and a colour flip instead.

6.5 Imagery

• Big, warm, unstyled food photography shot like a neighbour's phone: steaming turo-turo trays, lomi bowls, ihaw-ihaw smoke, sari-sari store fronts, hand-painted signage.
• Photos are full-bleed inside cards and cropped hard at the top or bottom, never in neat frames.
• Supporting graphics are thick-line icons and simple flat character spot illustrations of vendors and diners (not stock people), plus a hand-drawn "Locally Verified" stamp motif.
• No gradient blobs, no glass panels, no 3D renders. No photography of models or stock people instead of real carinderia food and storefronts.
• Alt text on every image.

6.6 Accessibility Contrast

All text/background pairings meet high-contrast expectations, and color is never the only signal — the "Locally Verified" badge and the "Promoted" label always carry visible text as well.

6.7 Readable Text and Controls at Every Viewport

Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration and motion may be cropped, bled off an edge, rotated, overlapped or cut exactly as the direction asks, as long as it covers no readable text or control. Moving and scrollable content (marquees, tickers, carousels, horizontally scrollable rows) may cross the viewport or container edge by design: judge it by whether it actually moves or scrolls and whether every item becomes fully readable as it passes, never by the item cut at the edge in a still frame. With prefers-reduced-motion, provide a usable static arrangement: wrap items into rows or allow horizontal scrolling so each item can be brought fully into view. A scrollable row need not show every item fully at once, including in reduced-motion mode. Where a direction, requirement, brief or finding asks readable text or a control to be cropped, clipped, covered or run off an edge, keep it whole and carry the gesture with imagery or decoration instead; for readable text and controls this rule takes precedence.

7. Signature Design Concept

"The Locally Verified Seal."

The defining visual and trust concept of Batangas Lowkey Eatery is the Locally Verified seal — a compact, hand-stamped-looking badge applied to eatery cards and detail pages only after Admin review, paired with the admin's verification notes. It is the product's answer to the stated problem that "it is hard to tell which info is trustworthy."

Supporting this concept:

• Barangay ribbon: each card carries a barangay tag so locality is legible at a glance.
• Price dots: a simple\x20\xe2\x82\xb1 /\x20\xe2\x82\xb1\xe2\x82\xb1 budget indicator, rendered visually and with text.
• Promoted stamp: promotions use a deliberately different treatment from the verification seal so paid placement is never confused with trust — both always labeled in plain words.
• Gems treatment: the "Discover Hidden Gems" section uses a distinct card accent to separate undiscovered local spots from the main grid.

7.1 Signature Moves

• A full-width deep-green hero block with an oversized flush-left headline that wraps to three lines and ends in a coral word, with the search pill and category chips living inside the same colour block rather than floating over a photo.
• A coral ticker band that cuts diagonally across the hero and continuously scrolls promoted eateries as "PROMOTED" labels in ink caps — the only marquee in the product, and it wraps into rows under prefers-reduced-motion.
• Cards that never hover-lift: on hover/focus the card's bottom strip flips from cream to green, the eatery name inverts to cream, and a 2px ink border snaps on — a painted-sign gesture, not a shadow.
• The "Locally Verified" badge as a rotated hand-stamped sticker (ink ring, Sora caps, slight -3° rotation) pinned to the top-left corner of the photo, with the verifier's note revealed in a cream tooltip on focus.
• Barangay as a first-class visual unit: a horizontal row of barangay "signage tabs" (hard-edged colour blocks with all-caps names, each in a different code colour) that acts as the near-me filter and bleeds off both viewport edges as a scrollable row.

7.2 Hero Direction

• The first screen is a stacked colour-block poster, not a centred SaaS hero.
• Top: a full-width deep green #0F5B4C block, edge to edge, carrying an oversized flush-left Sora headline in cream — "Ang sarap na lowkey, hanapin dito." — sized clamp(40px, 9vw, 88px) with the last word in coral #FF5A3C.
• Directly beneath it, still inside the green block, a full-width white search pill with the search icon and placeholder "Hanapin ang kainan sa barangay mo", plus a row of three category chips (Eatery / Street Food / Turo-turo) that horizontally scroll and bleed off the right edge.
• The block is cut diagonally at the bottom by a coral band 48px tall holding the scrolling promoted ticker.
• Below the fold-line, a cream band starts with the "Near my barangay" pill row and the first card grid.
• Dominant element is the headline; the only imagery on the first screen is a single tall portrait food photo bleeding off the right edge at 768px and up, overlapping the green block and cropped by the viewport — never covering the headline, search pill or chips.

7.3 Landing Hero Motion Brief

• Tempo: restrained (per the creative direction's Motion Tempo: restrained); hero dimensionality: layered 2D; hero drama: bold.
• Implementation: a product-specific 2D DOM/SVG/CSS composition using Motion for React (motion/react) or GSAP — no Canvas, no R3F, no Drei.
• Input → transformation → outcome thesis: the diner's own barangay context (a tapped barangay signage tab / the "Near my barangay" pill) transforms the hero's colour-block poster into a locally-scoped listing — the headline block stays, the ticker and first card grid re-key to that barangay, so the outcome is "these are the lowkey spots near me."
• Focal subject: the oversized flush-left Sora headline "Ang sarap na lowkey, hanapin dito." with its final coral word, sitting inside the deep green block.
• Visible layers (back to front): (1) full-bleed deep green #0F5B4C block; (2) the headline and the white search pill + category chip row inside the same block; (3) the coral 48px diagonal ticker band with continuously scrolling "PROMOTED" ink-caps labels; (4) the cream band below the fold-line with the barangay signage tabs and first card grid; (5) at 768px and up, a single tall portrait food photo bleeding off the right edge, overlapping the green block and cropped by the viewport.
• Loop: one contained loop at restrained tempo — cards rise 12px and fade in staggered 60ms as they enter view; category chips snap their fill colour on tap; the promoted ticker slides continuously; the save heart does a single 180ms pop. No parallax, no gradient drift, no spring physics.
• Composed first frame: the green block already filled edge to edge with the headline fully set and the search pill and chips in place, the coral ticker band already mid-scroll, and the first card row already at rest — nothing waits on a trigger to become legible.
• Optional interaction: tapping a barangay signage tab or the "Near my barangay" pill re-keys the ticker and first card grid to that barangay; tapping a category chip snaps its fill colour.

• Responsive behavior: single column at 360px with the headline wrapping to 2–3 lines and the chip row scrolling off the right edge; at 768px the portrait food photo bleeds in from the right and the grid goes 2-up; at 1024px 3-up with a left filter rail; at 1280px 4-up with the filter rail pinned and a wider hero. Headline, search pill, chips and ticker labels stay whole and inside the viewport at 375px, 768px and 1280px.
• Reduced-motion fallback: all motion resolves to instant static states — the ticker becomes a wrapped row of "PROMOTED" labels, cards appear without stagger, and the heart has no pop.

8. Interaction Model & Motion Direction

8.1 Interaction Model

• Mobile-first, thumb-driven: bottom navigation bar on mobile; top navbar on desktop.
• Chip-based filtering: category and barangay filters are tap chips; the "Verified only" toggle is a single tap.
• Card-first browsing: the eatery card is the primary object; tapping anywhere on the card opens the detail page.
• Progressive disclosure on detail pages: photos and essentials first, then hours, price, menu highlights, contact, and map link.
• Low-friction sharing: share actions are reachable from the detail page and support Facebook, Messenger, and copy link.
• Gated actions are explicit: reviews and favorites clearly indicate that login is required.
• Offline-aware: when connectivity drops, the user lands on a clear offline page rather than a browser error.

8.2 Motion Direction

• Motion is functional, not decorative: motion communicates loading, filtering, and state change.
• Skeleton loaders appear during data fetch and are replaced by content with a short, soft fade — never a jarring pop-in.
• Image fade-in on lazy load to avoid layout jump on slow connections.
• Chip selection and filter changes produce immediate, brief state feedback.
• Navigation indicator moves between bottom-nav items to show the active destination.
• Restraint for performance: animations are short, lightweight, and non-blocking, so the experience stays fast on slow mobile data.
• Restrained but alive (creative direction): one purposeful entrance per band (cards rise 12px and fade in staggered 60ms as they enter view), category chips snap their fill colour on tap, the promoted ticker slides continuously, and the save heart does a single 180ms pop. No parallax, no gradient drift, no spring physics.
• Reduced motion respected: with prefers-reduced-motion all of it resolves to instant static states and the ticker becomes a wrapped row.

9. Non-Functional Requirements

9.1 Performance

• NFR-1 — The app must load quickly on slow mobile data connections.
• NFR-2 — Images must be lazy-loaded, compressed, and served at appropriate sizes for the viewport.
• NFR-3 — Skeleton loaders must appear while content is being fetched so the interface never appears frozen.
• NFR-4 — The service worker must cache assets so repeat and offline-tolerant visits are fast.

9.2 Responsiveness

• NFR-5 — The layout must be mobile-first and function correctly at 360px, 768px, 1024px, and 1280px breakpoints.
• NFR-6 — The card grid must render 1 column on mobile, 2 on tablet, and 3–4 on desktop.

9.3 Usability & Accessibility

• NFR-7 — Interactive controls must be touch-friendly with a minimum target size of 44px.
• NFR-8 — Typography must be readable and color contrast must be high across all surfaces.
• NFR-9 — The app must use semantic HTML, provide alt text for images, support keyboard navigation, and expose ARIA labels on interactive elements.
• NFR-10 — Copy must be short and in plain language, with light Filipino/Batangueño tone acceptable.

9.4 Reliability & Availability

• NFR-11 — A basic offline page must be available when the user has no network connection.
• NFR-12 — Installed PWA behavior must be stable via manifest and service worker.

9.5 Security & Access Control

• NFR-13 — Review posting and saving favorites must require an authenticated user.
• NFR-14 — Vendor listing management must be restricted to the authenticated vendor who owns or claimed the listing.
• NFR-15 — Admin verification, moderation, and management functions must be restricted to authorized admin users only.
• NFR-16 — Because the platform hosts a trust badge, listing modification must be access-controlled so that verification status cannot be self-assigned by vendors.

9.6 Data Integrity

• NFR-17 — Eateries must belong to a valid category and barangay from the managed taxonomy.
• NFR-18 — Reviews and favorites must be linked to the authenticated user who created them.
• NFR-19 — Page views and search activity must be logged to support vendor stats and admin metrics.

9.7 Shareability & Discoverability

• NFR-20 — Each eatery must have a stable, shareable URL usable as a QR-code target.
• NFR-21 — Shared links must resolve directly to the eatery detail page.

10. Tech Stack

10.1 Frontend

• Next.js (React) — application framework for pages, routing, and rendering.
• Tailwind CSS — styling, responsive breakpoints, and design tokens.
• Motion for React (motion/react) or GSAP — the restrained hero and band entrance motion described in the Landing Hero Motion Brief.
• PWA layer — web app manifest, service worker, installability ("Add to Home Screen"), and a basic offline page.

10.2 Backend / Data

• Supabase providing:
  • PostgreSQL — relational data store.
  • Auth — authentication for diners (reviews, favorites), vendors, and admins.
  • Storage — eatery photo storage.

10.3 Maps

• Google Maps link or Leaflet / OpenStreetMap for map links and location reference.

10.4 Hosting

• Vercel — deployment and hosting for the Next.js application.

The team has stated this stack may be swapped.

10.5 Database Tables (Minimum Required)

• users (including role)
• eateries (name, category, barangay, address, price_range, hours, description, contact, status, is_verified, is_promoted)
• eatery_photos
• menu_items
• reviews
• favorites
• barangays
• categories
• promotions
• page_views
• search_logs

10.6 Required Deliverables

1. Project folder structure.
2. Database schema (SQL) with sample Batangas City data covering at least 10 eateries across different barangays.
3. Full working code for all pages and components, explained step by step.
4. Setup and deployment instructions.
5. A short list of improvements for a future native mobile app phase.

10.7 Build Order

1. Confirm the project folder structure and the database schema first.
2. Then build page by page, beginning with the Home page and the Eatery Detail page.

11. Assumptions and Constraints

11.1 Assumptions

• Diners can browse the entire directory without creating an account; login is only needed to post reviews and save favorites.
• Vendors are the legitimate owners or operators of the eateries they claim or submit.
• Admin review is the sole path to earning the "Locally Verified" badge.
• Barangay is the correct granularity for "near me" locality in Batangas City.
• The promoted/featured placement channel is the mechanism that funds the free directory.

11.2 Constraints

• No online ordering, no delivery, and no payment processing. This is a directory only.
• Revenue derives solely from promoted listings and featured vendor spotlights.
• The product must be usable by locals on mobile devices and slow mobile data.
• Promoted content must always be clearly labeled as promoted.
• Verification must be documented with admin verification notes.
• The app must be installable as a PWA and provide a basic offline page.
• The delivered design must satisfy the specified responsive breakpoints and accessibility requirements.

11.3 Out of Scope

• Online ordering, delivery dispatch, and payment processing.
• Tourist-oriented review framing.
• Any functionality not listed as a capability in Section 3.

12. Page Content and Component Coverage

This section defines what each page owns. Independent visual responsibilities get top-level section ownership; tightly coupled visual regions stay as named nested subcomponents under their one mutable-state owner.

12.1 Home page

• Purpose: anonymous directory entry with search, filters, discovery content, promoted content, and eatery cards.
• Sections:
  • Hero colour-block poster — deep green block, oversized flush-left Sora headline "Ang sarap na lowkey, hanapin dito." with the last word in coral, full-width white search pill (placeholder "Hanapin ang kainan sa barangay mo"), and a horizontally scrolling row of three category chips (Eatery / Street Food / Turo-turo).
    • Nested subcomponents: HeroHeadline, SearchPill, CategoryChipRow.
  • Promoted ticker band — coral 48px diagonal band with continuously scrolling "PROMOTED" ink-caps labels; wraps into rows under prefers-reduced-motion.
  • Barangay signage tabs — horizontal scrollable row of hard-edged all-caps barangay colour blocks acting as the "Near my barangay" filter, bleeding off both viewport edges.
  • Discover Hidden Gems — curated band surfacing small, lesser-known local eateries with a distinct card accent.
  • Featured / Promoted — band of promoted eateries, every item carrying a visible "Promoted" label.
  • Eatery card grid — 1 column mobile, 2 tablet, 3–4 desktop; cards never hover-lift (bottom strip flips cream→green, name inverts to cream, 2px ink border snaps on).
• Actions: search by name, tap category chip, tap barangay signage tab, toggle "Verified only", open an eatery card, open the share button.
• States: skeleton loaders during fetch; empty results; offline fallback.

12.2 Discover Hidden Gems

• Purpose: dedicated discovery destination for lesser-known local eateries.
• Sections: gems band heading, gems card grid with the distinct gems card accent, barangay signage tabs.
• Actions: open an eatery card, share a listing.
• States: skeleton loaders; empty state.

12.3 Featured / Promoted

• Purpose: clearly labeled destination for promoted and featured eateries.
• Sections: promoted band heading, promoted card grid where every card carries a visible "Promoted" label, promoted ticker band.
• Actions: open an eatery card, share a listing.
• States: skeleton loaders; empty state.

12.4 Search Results

• Purpose: revisitable results context for name, category, barangay, price, and verification filtering.
• Sections: sticky search pill, category chip row, barangay signage tabs, price-range (budget-friendly) filter, "Verified only" toggle, results card grid, left filter rail at 1024px and up.
• Actions: refine by name, category, barangay, price range, and verified-only; open an eatery card.
• States: skeleton loaders; no-results state; offline fallback.

12.5 Eatery Detail page

• Purpose: shareable eatery destination containing listing information, trust badge, map link, and sharing actions.
• Sections:
  • Photo header — full-bleed photos cropped hard at the top or bottom, with the rotated hand-stamped "Locally Verified" sticker (ink ring, Sora caps, -3° rotation) pinned top-left when verified, revealing the verifier's note in a cream tooltip on focus.
  • Essentials — description, address, barangay, opening hours, price range, menu highlights, contact info, map link.
  • Reviews and ratings — locally sourced reviews with star ratings; posting requires login.
  • Share actions — Facebook, Messenger, copy link, and the QR-code-friendly URL.
• Actions: follow the map link, share, copy link, save favorite (login required), post a review and rating (login required).
• States: skeleton loaders; unverified listing (no badge); offline fallback.

12.6 Reviews and Favorites

• Purpose: authenticated diner workspace for posting ratings and reviews and saving personal favorites.
• Sections: review composer with star rating, the diner's own review list, favorites shortlist.
• Actions: post a review and rating, edit/remove own review, save/unsave a favorite.
• States: login-required prompt; empty favorites; empty reviews; submission feedback.

12.7 Listing Submission

• Purpose: vendor workspace for claiming an existing listing or submitting a new pending listing.
• Sections: claim-existing-listing picker, new-listing form (name, category, barangay, address, price range, hours, description, contact), photo upload.
• Actions: claim an existing listing, submit a new listing.
• States: pending status after submission (no verified badge, no promoted placement); validation errors.

12.8 Vendor Dashboard

• Purpose: owner-restricted workspace for editing approved listing details, photos, hours, and menu highlights.
• Sections: listing details editor, photo manager, opening-hours editor, menu-highlights editor.
• Actions: edit details, manage photos, edit opening hours, edit menu highlights.
• States: pending-listing notice; save feedback; owner-restricted access.

12.9 Vendor Stats

• Purpose: owner-restricted destination for page views, searches, and saves.
• Sections: page-views metric, searches metric, saves metric.
• Actions: review basic stats.
• States: loading; no-data state.

12.10 Promotion Request

• Purpose: vendor destination for requesting promoted listing or featured spotlight treatment.
• Sections: promotion request form, current promotion status.
• Actions: request a promoted listing or featured spotlight.
• States: request submitted; request pending admin management.

12.11 Review Queue

• Purpose: admin destination for approving or rejecting submitted listings.
• Sections: pending listing queue, listing detail preview, approve/reject controls.
• Actions: approve a listing, reject a listing.
• States: empty queue; decision feedback.

12.12 Verification

• Purpose: admin destination for recording verification notes and awarding the Locally Verified badge.
• Sections: approved-listing list, verification-notes composer, badge award control.
• Actions: mark a listing "Locally Verified" with verification notes.
• States: unverified listing; verified listing with notes shown.

12.13 Taxonomy

• Purpose: admin destination for managing categories and barangays.
• Sections: category manager (Eatery, Street Food, Turo-turo), barangay manager.
• Actions: add/edit/remove categories; add/edit/remove barangays.
• States: validation errors; in-use taxonomy guard.

12.14 Admin Management

• Purpose: admin destination for managing users and promoted listings with required labeling.
• Sections: user manager, promoted-listing manager with the required "Promoted" label.
• Actions: manage users; manage promoted listings so paid placements stay correct, current, and clearly labeled.
• States: empty lists; action feedback.

12.15 Admin Dashboard

• Purpose: admin metrics destination covering active users, verified listings, searches per user, and promoted vendors.
• Sections: monthly active users metric, number of verified listings metric, searches per user metric, vendors with promoted listings metric.
• Actions: review platform metrics.
• States: loading; no-data state.

12.16 offline page

• Purpose: basic offline fallback shown when the installed or visited PWA has no network connection.
• Sections: offline message in plain language.
• Actions: retry.
• States: offline.

12.17 Login

• Purpose: shared returning-verification surface for diners, vendors, and authorized admins; protected actions and durable records require authentication.
• Sections: credential form, link to Sign Up.
• Actions: sign in.
• States: invalid credentials; success redirect to the originating protected action.

12.18 Sign Up

• Purpose: self-service enrollment for diners who independently begin authenticated reviews or favorites and vendors who begin listing management.
• Sections: enrollment form.
• Actions: create an account.
• States: validation errors; success.

12.19 Admin Login

• Purpose: role-appropriate returning-verification surface for the internal admin lifecycle; it does not provide public enrollment.
• Sections: credential form.
• Actions: sign in to the restricted admin surface.
• States: invalid credentials; success redirect to the admin surface.

13. Glossary