System Requirements Document for aloha-franchise

1. Introduction

aloha-franchise is a web application for Monin Modi's Aloha franchise: a single, friendly, confident web presence that presents the franchise to visitors. The product's intent is to give the business one public home on the web where customers can learn about the Aloha franchise and its offers, and find how to visit or contact the store.

The audience is twofold. Customers are the public visitors who arrive at the site to discover the franchise, read its content, and find the store's contact and location details. The Franchise Owner is the operator of the Aloha franchise who needs that web presence to represent the business and who checks that visitors can find the store details.

The current delivery is a public, anonymous, read-only marketing presence. There is no customer account, no ordering, no payment, and no owner-facing administration in the current scope; those are not part of the accepted requirements.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The Aloha franchise web app is delivered as a first-party public website. Its single current destination, Landing, is anonymously reachable by anyone — no account, sign-in, or identity establishment is required or offered. Visitors read the franchise content and find contact and location details; nothing on the site changes durable state on the visitor's behalf.

The Franchise Owner's role in the current scope is to have the web presence exist and to verify that visitors can find the store details. The accepted requirements do not include an owner-facing editing, administration, or content-management surface, so none is specified. Content presented on the Landing page is the franchise's published content; how it is authored is outside the current product boundary.

The delivery boundary is therefore: one public page, static in behavior, presenting franchise content, contact details, and location details to anonymous visitors. No authenticated area, no transactional workflow, and no provider-owned surface is part of the current product.

2c. Page Content and Component Coverage

Landing

Information and state

• The Aloha franchise identity: wordmark/name and a short welcoming statement of what the franchise is.
• Franchise content describing the business and its offers, presented as readable sections.
• Contact details for the store (for example a phone number and/or email address as published by the franchise).
• Location details for the store (address and any published directions or hours information).
• No visitor-specific state is stored; the page renders the same published content for every visitor.

Primary actions

• Read the franchise content.
• Find and use the contact details (for example, initiate a call or email from the displayed contact information).
• Find and use the location details (for example, read the address and directions).

Supporting actions

• Navigate between the page's content bands (hero, about/offers, contact, location) via in-page anchors or scrolling.

Domain entities

• Franchise profile: name, description, offers/content sections.
• Contact details: the published ways to reach the store.
• Location details: the published store address and related visit information.

Component responsibilities

• Hero band: oversized headline, welcoming copy, and a call-to-action control that leads the visitor to the contact or location content.
• Content bands: present the franchise description and offers in readable, colour-blocked sections.
• Contact block: display the published contact details as readable, actionable text.
• Location block: display the published store address and visit information.
• Decorative illustration layer: flat spot illustrations (bowls, palm leaves, fruit) and sticker badges that carry the visual gesture without covering readable text or controls.

States

• Loading: the page's published content is fetched; a lightweight placeholder preserves layout while content arrives.
• Empty: if a content section has no published content, that section is omitted rather than shown blank; contact and location blocks show a clear "details coming soon" message if unpublished.
• Success: all published content, contact details, and location details render fully and legibly at 375px, 768px, and 1280px.
• Error: if content cannot be loaded, a friendly message explains the site is temporarily unavailable and offers a retry.
• Recovery: retry re-requests the content; if it still fails, the message persists with the contact details shown if they are available from a cached or static fallback.

3. Functional Requirements

FR-1 — Public franchise presentation

• As a Customer, I should open the Aloha franchise web app and read content that presents the franchise and its offers, so that I understand what the business is and what it offers.
• Provenance: explicit.
• Lifecycle: Trigger — the Customer opens the Landing page. Input — none beyond the visit. Observable result — the franchise identity, description, and offers render as readable content. Access — anonymous, no account. Failure/recovery — if content fails to load, a friendly unavailable message with retry is shown; retry re-requests content. Continuation — the Customer scrolls on to contact and location details.

FR-2 — Find contact details

• As a Customer, I should find the store's contact details on the Landing page, so that I know how to reach the Aloha franchise.
• Provenance: explicit.
• Lifecycle: Trigger — the Customer looks for contact information. Input — none. Observable result — the published contact details are displayed as readable, actionable text. Access — anonymous. Failure/recovery — if contact details are unpublished, a clear "details coming soon" message is shown instead of a blank block. Continuation — the Customer uses the displayed contact method.

FR-3 — Find location details

• As a Customer, I should find the store's location details on the Landing page, so that I know where and how to visit the Aloha franchise.
• Provenance: explicit.
• Lifecycle: Trigger — the Customer looks for where to visit. Input — none. Observable result — the published store address and visit information are displayed. Access — anonymous. Failure/recovery — if location details are unpublished, a clear "details coming soon" message is shown. Continuation — the Customer plans a visit using the displayed details.

FR-4 — Owner's web presence and verification

• As a Franchise Owner, I should have one public web presence for the Aloha franchise and be able to confirm that visitors can find the store details, so that the business is represented online and reachable by customers.
• Provenance: required_inference (grounded in the accepted persona rationale).
• Lifecycle: Trigger — the Owner reviews the live site. Input — none. Observable result — the Landing page presents the franchise content, contact details, and location details to anonymous visitors. Access — the Owner views the same public page as any visitor; no separate owner surface is in scope. Failure/recovery — if content or details are missing, the Owner observes the empty-state messages described in FR-1 through FR-3. Continuation — the Owner confirms the presence is complete.

4. User Personas

Franchise Owner

The Franchise Owner runs the Aloha franchise and needs one web presence for the business. Their product context is operational: they want the franchise represented online in a way that is warm, confident, and clearly points customers to how to visit or contact the store. Their primary goal is for the web presence to exist and to be verifiably complete — that a visitor can find the store details. Their distinct accepted responsibility is verification: reviewing the public Landing page as a visitor would and confirming the franchise content, contact details, and location details are present and legible. Their relevant input is their own review of the live page; their observable success is a complete, readable public page. They do not have a separate editing or administration surface in the current scope.

Customer

The Customer is a public visitor who wants to learn about the Aloha franchise and its offers. Their product context is discovery: they arrive with no account and no prior relationship to the site. Their primary goal is to understand the franchise and find how to visit or contact the store. Their distinct accepted responsibilities are reading the franchise content, locating the contact details, and locating the location details. Their relevant decisions are which contact method to use and whether to plan a visit. They interact with the Franchise Owner only indirectly — through the published content the Owner verifies. Their observable success is having read the franchise content and obtained usable contact and location details.

5. Core User Flows

Flow A — Customer discovers the franchise and finds how to visit

1. The Customer opens the Aloha franchise web app at the Landing page. No account or sign-in is required.
2. The Landing page loads and presents the franchise identity and welcoming content in the hero band.
3. The Customer reads the franchise description and offers in the content bands.
4. The Customer scrolls or uses in-page navigation to the contact block and reads the published contact details.
5. The Customer scrolls to the location block and reads the published store address and visit information.
6. Success: the Customer has learned about the franchise and holds usable contact and location details.
7. Failure/recovery: if content fails to load, the Customer sees a friendly unavailable message with a retry control; retry re-requests the content. If a section is unpublished, the Customer sees a clear "details coming soon" message rather than a blank area.
8. Continuation: the Customer uses the displayed contact method or plans a visit using the displayed location details.

Flow B — Franchise Owner verifies the web presence

1. The Franchise Owner opens the Landing page as any visitor would.
2. The Owner reads the hero and content bands and confirms the franchise identity, description, and offers are present and legible.
3. The Owner checks the contact block and confirms the published contact details are displayed.
4. The Owner checks the location block and confirms the published store address and visit information are displayed.
5. Success: the Owner confirms the public presence is complete and that a visitor can find the store details.
6. Failure/recovery: if any section shows an empty-state message or fails to load, the Owner observes the gap and the site's retry behavior; the Owner's corrective action on content is outside the current product boundary.
7. Continuation: the Owner re-checks the page after any external content update.

6. Visuals Colors and Theme

The creative direction is authoritative for this section.

• Muse and headline: Haraldur Thorleifsson — "Big-hearted boldness for an Aloha franchise."
• Mode: light.
• Colour tokens (exact hex by role):
  • Background (cream ground, most area): #FFF6E9
  • Surface (chunky cards): #FFE3C2
  • Text (ink, on cream and surface only): #1E1B16
  • Primary (coral orange, brand and calls to action): #F4511E
  • Accent (teal, prices and tags): #0E7C6B
  • Muted: #7A6A58
• Typography:
  • Headings: Sora, weight 700, tight tracking, sentence case, very large sizes.
  • Body: Outfit.
  • Scale: 1.25 modular — 56 / 44 / 32 / 22 / 17, with display sizes from 56px on mobile to 128px on desktop (use clamp() so the mobile size is preserved).
• Shape language: chunky rounded cards at 24px radius; full-width colour bands with soft 32px corners; pill buttons; round sticker badges.
• Layout: colour-blocked bands stack down the page; a two-column menu grid collapses to one column at 375px; generous padding keeps text inside every container.
• Imagery style: custom flat spot illustration of bowls, palm leaves, and fruit; bold icons; no stock photography.
• Motion: lively entrance fades and hover pops at 200ms; one slow loop on the sticker badges; reduced motion shows a static layout.
• Avoid: stock food photography; gradient blobs and glass panels; blue or indigo accents; identical hover-lift card grids; thin hairline borders and grey neutral surfaces.

7. Signature Design Concept

The public entry is a full-bleed coral band (#F4511E) that fills the first screen. An oversized Sora headline in cream sits left, spanning 56px on mobile up to 128px on desktop. A large flat illustrated poke bowl — custom spot illustration, not photography — overlaps and bleeds off the right edge of the hero. A cream pill call-to-action sits under the headline and leads the visitor to the contact or location content. Round sticker badges rotate slowly near the hero corners. Below the hero, section bands alternate cream, coral, and teal with 32px rounded edges; menu items sit in chunky cream cards on a teal band with coral price tags. All readable text and controls remain whole and inside the viewport and their containers at 375px, 768px, and 1280px; the bleed and overlap gestures are carried by imagery and decoration only.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: the oversized Sora headline in cream on the coral band, with the flat illustrated poke bowl bleeding off the right edge.
• Input → transformation → outcome thesis: on page load, the hero band and headline fade in and settle (200ms entrance), the illustrated bowl slides in from the right edge to its overlapping position, and the sticker badges begin their single slow rotation loop — the outcome is a composed, warm first screen that invites the visitor to read on and use the cream pill CTA.
• Motion vocabulary: lively entrance fades, hover pops at 200ms, one slow loop on sticker badges.
• Composed first frame: coral band filling the screen, cream headline left, bowl overlapping right, cream pill CTA beneath the headline, sticker badges near the corners.
• Reduced-motion state: all entrance and loop motion is removed; the hero renders as a static composed layout with the bowl in its final overlapping position and badges stationary.

9. Non-Functional Requirements

• NFR-1 — Anonymous public access: the Landing page is reachable without an account or sign-in; no identity establishment is required (explicit, from the accepted access contract).
• NFR-2 — Readability at every viewport: headlines, wordmark, labels, numbers, card text, and controls stay entirely inside the viewport and their containers at 375px, 768px, and 1280px, wrapping or scaling (for example clamp()) to fit; no element covers readable text or controls (explicit, from the creative direction's readability rule).
• NFR-3 — Reduced motion: with prefers-reduced-motion, the site provides a usable static arrangement with no entrance fades or badge loops (explicit, from the creative direction).
• NFR-4 — No stock photography: imagery is custom flat spot illustration only (explicit, from the creative direction).
• NFR-5 — Palette fidelity: the specified hex tokens are used by role; blue/indigo accents, gradient blobs, glass panels, and grey neutral surfaces are avoided (explicit, from the creative direction).
• NFR-6 — Content availability: published content, contact details, and location details are served to every visitor consistently; failures surface a friendly message with retry (required_inference, to make FR-1 through FR-3 usable).

10. Tech Stack

• Frontend: React application UI.
• Backend: shared FastAPI process for application APIs and domain modules (serves the published franchise content, contact details, and location details to the Landing page).
• Database: MariaDB for application-owned persistent data (stores the published franchise content, contact details, and location details).
• Containerization: Docker / docker-compose with the provisioned services — frontend, backend, database.

11. Assumptions and Constraints

• A-1: The current product is a public, anonymous, read-only marketing presence; no customer account, ordering, payment, or owner administration surface is in scope (explicit boundary from the accepted requirements and access contract).
• A-2: The Landing page is the single current destination; no additional pages are in scope (page contract).
• A-3: Franchise content, contact details, and location details are the franchise's published content; how the Owner authors or updates that content is outside the current product boundary (required_inference boundary).
• A-4: The Franchise Owner and Customer personas are the closed active-human set; no additional personas are introduced.
• A-5: The creative direction's palette, fonts, shape language, layout, imagery, and motion are binding; unspecified presentation details follow the direction.
• A-6: The provisioned database stores only the published content needed for the Landing page; it does not imply authentication or additional domain entities.

12. Glossary

• Aloha franchise: the local food franchise operated by Monin Modi that this web app represents.
• Landing: the single public page of the web app where visitors read franchise content and find contact and location details.
• Franchise Owner: the operator of the Aloha franchise who needs the web presence and verifies it.
• Customer: an anonymous public visitor who reads the franchise content and finds how to visit or contact the store.
• Contact details: the published ways to reach the store (for example phone and/or email).
• Location details: the published store address and related visit information.
• Sticker badge: a round decorative badge that rotates slowly near the hero corners.
• Colour band: a full-width section with soft 32px rounded corners in cream, coral, or teal.