System Requirements Document for divine-3d

1. Introduction

divine-3d is the homepage of a premium car-rental website for Arabic-first leisure and business travellers in North Africa and Gulf-adjacent markets (Morocco, Tunisia, UAE). The product intent is a single, self-contained landing page that presents car rental as a desirable, tactile object: a real-time 3D car on a reflective plinth, a floating glass search capsule, a tilt-and-rotate gallery, a live colour picker, animated trust signals, a scroll-driven "how it works" road, a depth-carousel of customer testimonials, and a closing call to action with a floating WhatsApp button.

The page is delivered as a complete, runnable front-end project (npm run dev) built with React + Vite + Tailwind CSS, Three.js via React Three Fiber and Drei, GSAP + ScrollTrigger, and Framer Motion. It is fully RTL/Arabic by default with a language switch to French and English, responsive across mobile, tablet and desktop, and degrades to a static image when WebGL is unavailable.

The audience is the browsing visitor — a prospective renter evaluating cars, prices and service promises before deciding to book or to reach out over WhatsApp.

2. System Overview

divine-3d is a single-page public marketing and discovery surface. There is no account system, no booking transaction, and no authenticated area: the page is anonymously reachable and every interaction is client-side presentation, filtering and navigation.

Current delivery

• Frontend (React application UI): the entire accepted experience — preloader, 3D hero, glass search capsule, gallery, colour picker, "why us", "how it works", testimonials, final CTA, footer, WhatsApp float, language switch, custom cursor, WebGL fallback.
• Backend (shared FastAPI process): provisioned as the shared application process for APIs and domain modules. The accepted homepage requirements do not define any server-side data operation, so the backend remains available infrastructure for the delivered project without introducing new product capabilities.
• Database (MariaDB): provisioned application-owned persistent storage. No accepted requirement establishes durable domain entities, so no schema, entity model, or persistence behavior is specified by this document.

Actors

• زائر يبحث عن سيارة للكراء — the sole active human persona: an anonymous visitor browsing the homepage.
• WhatsApp (external destination) — the outbound recipient of the floating WhatsApp button; not a persona and not a first-party surface.

Accepted behavior and ownership

All accepted behavior is owned by the single Landing page. The 3D hero, search capsule, gallery, colour picker, trust band, scroll-driven steps, testimonial carousel, CTA, footer, preloader, language switch, custom cursor and WebGL fallback are all sections, states and controls of that one page — not separate destinations.

Narrow exclusions

• Only the homepage is in scope; the rest of the rental website (listing pages, car detail pages, checkout, booking management, accounts) is not requested.
• No booking transaction, payment, availability engine, or reservation record is specified.
• No authentication, user accounts, or role-based permissions are specified.

Removed from scope

• None. No concept was explicitly removed by the user.

2a. Product Interpretation and Delivery Boundary

divine-3d is delivered as a front-end project that runs locally with npm run dev. The homepage is public and anonymous: a visitor arrives, watches the preloader, lands on the 3D hero, and can explore the page freely without signing in or creating an account. Nothing on the page is gated.

The search capsule, gallery, colour picker and testimonial carousel are presentation and exploration controls on the landing page. The search button and the WhatsApp float are the visitor's outward actions; the WhatsApp button hands off to WhatsApp as an external destination owned by that provider. The page itself does not complete a rental, hold a reservation, or store visitor data as part of any accepted requirement.

The provisioned FastAPI backend and MariaDB database are part of the delivered project's runnable infrastructure. Because no accepted requirement defines server-side data or a booking workflow, this document does not assign them product behavior; they remain available for the project without expanding the homepage's scope.

Future ideas that the user did not accept — such as a full rental site, booking flow, or accounts — are not part of the current delivery and are not represented as pages or requirements.

2c. Page Content and Component Coverage

Landing

The single public page of divine-3d. It is anonymously reachable, RTL/Arabic by default, and hosts every accepted section, state and control.

Information and state

• Current language (Arabic default, French, English) and text direction (RTL for Arabic, LTR for French/English).
• Preloader progress percentage and completion state.
• Hero car rotation/parallax state and colour selection state.
• Search capsule field values: city, pickup date, return date, car type.
• Gallery card hover/tilt state and per-card car rotation state.
• Testimonial carousel active index.
• WebGL support state (3D enabled vs. static-image fallback).
• Reduced-motion preference state.

Primary and supporting actions

• Rotate/parallax the hero car with mouse or touch.
• Enter city, pickup date, return date and car type; press the glowing search button.
• Hover/tilt gallery cards and rotate each card's car; read price/day, transmission, fuel, seats.
• Select a colour swatch to recolour the car in real time.
• Switch language between Arabic, French and English.
• Navigate the testimonial depth slider.
• Use the final CTA and the floating WhatsApp button.
• Scroll through the page, driving camera and road animations.

Domain entities (presentation-level)

• Car — price per day, transmission, fuel type, seat count, paint colour, 3D model (.glb).
• Search query — city, pickup date, return date, car type.
• Colour swatch — a selectable paint colour.
• Trust promise — comprehensive insurance, free delivery, 24/7 support, no hidden fees.
• How-it-works step — one of three numbered steps.
• Testimonial — customer quote with monogram avatar.

Component responsibilities

• Preloader — animated car driving across a gold progress line with a loading percentage; dismisses when assets are ready.
• Hero3D — R3F canvas: .glb car slowly rotating on a reflective circular plinth, HDRI cinematic lighting, dark gradient background, mouse/touch control, parallax; oversized headline "اكترِ سيارة أحلامك في دقائق".
• SearchBar — floating Glassmorphism capsule with city, pickup date, return date, car type fields and a glowing search button.
• CarGallery — staggered grid of 3D tilt cards; each card rotates its car on hover and shows price/day, transmission, fuel, seats.
• ColorPicker — colour buttons that change the car colour in real time.
• WhyUs — four animated line icons: comprehensive insurance, free delivery, 24/7 support, no hidden fees.
• HowItWorks — three steps with a 3D car moving along a road during scroll (scroll-driven animation).
• Testimonials — depth-effect slider of customer reviews.
• FinalCTA + Footer — closing call to action, footer, and floating WhatsApp button.
• LanguageSwitch — toggles Arabic/French/English and RTL/LTR.
• CustomCursor — custom mouse pointer.
• WebGLFallback — static image shown when WebGL is unsupported.

States

• Loading: preloader visible with animated car and percentage; page content revealed on completion.
• Empty: not applicable — the page presents fixed marketing content; no data-driven empty state is specified.
• Success: preloader completes and hero renders; colour selection updates the car immediately; language switch re-renders text and direction; search button and WhatsApp button respond on activation.
• Error / recovery: if WebGL is unavailable, the static-image fallback replaces the 3D hero so the composition and all text/controls remain usable; if reduced motion is preferred, animations are disabled and a static hero, static road illustration, and fully reachable testimonial row are shown.
• Responsive: single column at 375px with 20px gutters; tablet and desktop layouts per the creative direction; all readable text and controls stay whole at 375px, 768px and 1280px.

3. Functional Requirements

FR-1 — Homepage delivery (explicit) As a visitor I should land on a complete, luxurious, modern 3D-interactive car-rental homepage for divine-3d.

• Trigger: page load.
• Observable result: the full homepage renders with all accepted sections.
• Continuation: the visitor scrolls and interacts.

FR-2 — Technology stack (explicit) As a developer I should have the project built with React + Vite + Tailwind CSS, Three.js with React Three Fiber and Drei, GSAP + ScrollTrigger for scroll-linked motion, and Framer Motion for transitions.

• Observable result: the delivered project uses exactly these technologies.

FR-3 — Performance (explicit) As a visitor I should experience smooth 60fps interaction, with 3D models lazily loaded and mobile supported.

• Observable result: models load lazily; animation targets 60fps; the page works on mobile.

FR-4 — 3D hero (explicit) As a visitor I should see a 3D car (.glb) slowly rotating on a reflective plinth, lit with cinematic HDRI lighting against a dark gradient background, under the large headline "اكترِ سيارة أحلامك في دقائق", and I should be able to control the car with mouse or touch.

• Trigger: page load and pointer/touch movement.
• Observable result: the car rotates slowly and responds to pointer/touch; the headline is displayed.
• Failure/recovery: if WebGL is unsupported, a static image is shown (FR-19).

FR-5 — Smart search bar (explicit) As a visitor I should use a floating Glassmorphism search bar with city, pickup date, return date, car type, and a glowing search button.

• Input: city, pickup date, return date, car type.
• Action: press the glowing search button.
• Observable result: the fields accept input and the button responds on activation.

FR-6 — Car gallery (explicit) As a visitor I should browse 3D cards that tilt with mouse movement and whose car rotates on hover, showing price per day, transmission, fuel and seat count.

• Trigger: pointer hover over a card.
• Observable result: the card tilts and its car rotates; the four spec values are visible.

FR-7 — Colour selection (explicit) As a visitor I should press colour buttons that change the car colour in real time.

• Trigger: selecting a colour button.
• Observable result: the car's colour updates immediately.

FR-8 — Why us (explicit) As a visitor I should see a "لماذا نحن" section with animated icons for comprehensive insurance, free delivery, 24/7 support, and no hidden fees.

FR-9 — How it works (explicit) As a visitor I should see three steps with a 3D car moving along a road as I scroll (scroll-driven animation).

• Trigger: vertical scroll through the section.
• Observable result: the car advances along the road in step with scroll progress.

FR-10 — Testimonials (explicit) As a visitor I should browse customer reviews in a slider with a depth effect.

• Trigger: navigating the slider.
• Observable result: the active testimonial changes with a depth effect.

FR-11 — Final CTA, footer and WhatsApp (explicit) As a visitor I should see a closing call to action, a footer, and a floating WhatsApp button.

• Action: activating the WhatsApp button.
• Observable result: the visitor is handed off to WhatsApp as an external destination.

FR-12 — Palette (explicit) As a visitor I should see charcoal black (#0B0B0F), gold/orange (#F5A623) as the accent colour, and soft white.

FR-13 — Typography (explicit) As a visitor I should see Arabic set in Cairo or Tajawal and English in Inter.

FR-14 — RTL and language switching (explicit) As a visitor I should have full RTL and Arabic support with the ability to switch to French and English.

• Trigger: selecting a language.
• Observable result: text and direction update; Arabic is RTL, French/English are LTR.

FR-15 — Shape and glow (explicit) As a visitor I should see rounded corners, soft shadows, and glow on buttons.

FR-16 — Preloader (explicit) As a visitor I should see a preloader with an animated car and a loading percentage.

• Observable result: the percentage advances and the preloader dismisses when loading completes.

FR-17 — Custom cursor (explicit) As a visitor I should see a custom mouse cursor.

FR-18 — Interaction and motion (explicit) As a visitor I should experience mouse-move parallax, a camera that moves smoothly between sections during scroll, and hover effects on every interactive element.

FR-19 — WebGL fallback (explicit) As a visitor on a device without WebGL I should see a static image instead of the 3D scene.

• Trigger: WebGL unsupported.
• Observable result: a static image replaces the 3D hero; all text and controls remain usable.

FR-20 — Quality requirements (explicit) As a developer I should deliver clean code split into reusable components, fully responsive design (mobile, tablet, desktop), and basic SEO and accessibility.

FR-21 — Run instructions (explicit) As a developer I should receive a short explanation of how to run the project and where to place .glb models.

FR-22 — Runnable delivery (explicit) As a developer I should receive the complete project files ready to run with npm run dev.

4. User Personas

زائر يبحث عن سيارة للكراء

Product context. An Arabic-first leisure or business traveller in Morocco, Tunisia or the UAE, browsing on mobile or desktop, evaluating a premium car rental before committing. They may switch to French or English.

Primary goal. Decide whether divine-3d offers the car they want at a transparent price, and take the next step — search, or reach out over WhatsApp.

Distinct accepted responsibilities.

• Watch the preloader and arrive at the 3D hero; rotate and parallax the car with mouse or touch.
• Enter city, pickup date, return date and car type in the glass search capsule and press the glowing search button.
• Explore the gallery: tilt cards, rotate each card's car on hover, and read price per day, transmission, fuel and seats.
• Select a colour to recolour the car in real time.
• Read the "why us" promises, the three "how it works" steps, and the customer testimonials.
• Switch language between Arabic, French and English.
• Act on the final CTA or the floating WhatsApp button.

Inputs and decisions. City, dates, car type; which car and colour appeal; whether the trust promises and testimonials are convincing; whether to contact via WhatsApp.

Interactions with other participants. The WhatsApp button hands off to WhatsApp as an external destination; the visitor is the one who initiates that handoff.

Observable success. The visitor has seen the cars, prices and specs, chosen a colour, understood the service promises, and either searched or opened WhatsApp.

5. Core User Flows

Flow 1 — Arrive and explore the 3D hero

1. The visitor opens divine-3d. The Landing page shows the preloader: an animated car drives across a gold progress line while the loading percentage advances.
2. When loading completes, the preloader dismisses and the hero appears: the .glb car slowly rotating on a reflective plinth, cinematic HDRI lighting, dark gradient background, and the headline "اكترِ سيارة أحلامك في دقائق".
3. The visitor moves the mouse or touches the screen; the car responds with parallax and rotation.
4. Recovery: if the device does not support WebGL, the static image is shown in place of the 3D scene and the visitor continues with all text and controls intact.

Flow 2 — Search for a car

1. On the Landing page the visitor reaches the floating Glassmorphism search capsule.
2. The visitor enters the city, the pickup date, the return date, and the car type.
3. The visitor presses the glowing search button.
4. The button responds on activation; the visitor continues exploring the page.

Flow 3 — Browse the gallery and inspect a car

1. The visitor scrolls to the gallery on the Landing page.
2. The visitor hovers a 3D card; the card tilts with the mouse and the card's car rotates.
3. The visitor reads the price per day, transmission, fuel and seat count.
4. The visitor moves to other cards, each tilting and rotating in turn.

Flow 4 — Choose a colour

1. The visitor reaches the colour selection on the Landing page.
2. The visitor presses a colour button.
3. The car's colour changes in real time.
4. The visitor tries other colours until satisfied.

Flow 5 — Build confidence

1. The visitor reads the "لماذا نحن" section with its animated icons: comprehensive insurance, free delivery, 24/7 support, no hidden fees.
2. The visitor scrolls through "كيف يعمل": three steps, with the 3D car moving along the road as the page scrolls.
3. The visitor browses the customer testimonials in the depth slider, moving between reviews.

Flow 6 — Switch language

1. The visitor selects French or English (or returns to Arabic) on the Landing page.
2. The page text and direction update: Arabic renders RTL, French and English render LTR.
3. The visitor continues browsing in the chosen language.

Flow 7 — Take the next step

1. The visitor reaches the final CTA and footer on the Landing page.
2. The visitor activates the floating WhatsApp button.
3. The visitor is handed off to WhatsApp as an external destination to make contact.

6. Visuals Colors and Theme

The creative direction is authoritative: Sensual dark-luxe motion — glossy charcoal voids, molten gold, cars as candy-coloured sculpture. Muse: Karim Rashid; headline idea: product as desirable object under light.

Colour tokens (dark mode)

Car paint swatches form their own palette — gold, pearl white, candy pink, lime, graphite — as small 40px circular chips.

Typography

• Arabic display: Tajawal 700–800, tight 0.98 line-height.
• Latin display: Inter 600–700 with -0.03em tracking.
• Body: Cairo (Arabic), Inter (Latin).
• Numbers (prices, dates, seats): Inter with tabular figures.
• Scale (1.333 modular): mobile 40/30/22/17/15; tablet 72/48/32/20/16; desktop 112/64/40/22/17.
• Display headline clamp(40px, 8.5vw, 112px); section headings clamp(30px, 4.5vw, 64px); body 16–18px, line-height 1.75 Arabic / 1.65 Latin.
• Latin micro-labels: 11px, 0.18em tracking, all caps.

Shape language. Continuous-curve radii: cards 28px, panels 36px, buttons full pill; capsule inputs in the glass search bar; blob-soft section transitions with a gold hairline curve; the circular plinth as recurring motif (echoed by colour chips and testimonial dots); nothing sharp except thin 1px gold rules separating spec rows.

Spacing rhythm. 12-column editorial grid; 20px gutters at 375px; generous vertical rhythm between sections.

Imagery style. One hero subject: a glossy 3D car on a reflective charcoal plinth under warm HDRI (studio softbox + gold rim light). Supporting imagery is product-only: macro crops of wheel spokes, headlight glass, stitched leather, paint-swatch gloss spheres. No stock people or lifestyle photography in the hero; testimonial avatars are soft gold monogram circles on charcoal. WebGL fallback: a pre-rendered 3/4 studio PNG of the hero car on the same plinth with identical gradient background.

7. Signature Design Concept

The public entry is a dark stage with one lit sculpture and an editorial headline beside it.

• Full-bleed charcoal #0B0B0F void with a radial warm gradient (rgba(245,166,35,0.14) → transparent) blooming behind the car.
• The 3D car sits on a circular mirror plinth at roughly 62% of viewport width on desktop, bleeding off the right edge, with the gold rim light tracing its roofline.
• The oversized Arabic headline "اكترِ سيارة أحلامك في دقائق" stacks in three lines on the RTL start side at clamp(40px, 8.5vw, 112px) Tajawal 800 in soft white, with the word "دقائق" in gold as the only coloured word.
• Beneath the headline: a small gold eyebrow ("تأجير فاخر · توصيل مجاني"), one 18px muted subline, and a single gold pill CTA with a soft outer glow (box-shadow: 0 0 40px rgba(245,166,35,0.35)).
• The floating glass search capsule straddles the hero/gallery seam, overlapping the plinth's bottom edge.
• At 375px the car scales to 92vw and sits above the headline; the headline wraps to four lines and never clips.

Signature moves carried through the page: the circular plinth motif (hero plinth → colour swatch ring → testimonial depth dots); the glass search capsule with backdrop-blur(24px) over #16161C at 55% opacity and a 1px gold hairline; gallery cards that tilt and rotate their car 180° on hover with hairline-ruled spec sheets; the pinned "how it works" road with a gold dashed centreline scrolling horizontally; an oversized gold final-CTA line at clamp(48px, 9vw, 128px); and a glossy gold WhatsApp capsule that morphs from circle to labelled pill on hover.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the glossy .glb car on its reflective circular plinth, lit by warm HDRI with a gold rim light.
• Input → transformation → outcome thesis: pointer/touch movement and scroll drive a damped parallax and turntable on the car, while a scrubbed GSAP ScrollTrigger timeline dollies the camera between sections — the visitor's motion reveals the car as a lit sculpture and carries them through the page.
• Motion vocabulary: slow 0.08rad/s turntable; mouse/touch parallax ±6° yaw, ±3° pitch, damped with lerp 0.06; camera dolly between sections on scroll; gallery tilt with spring (stiffness 180, damping 22) and 180° car rotation on hover; "how it works" road translating with scroll progress; preloader car driving across a gold progress line; entrance reveals 600–800ms with cubic-bezier(0.22, 1, 0.36, 1); search button glow pulsing once on mount.
• Composed first frame: charcoal void, warm radial bloom, the car on its plinth bleeding off the right edge, the three-line Arabic headline with "دقائق" in gold on the RTL start side, gold eyebrow, muted subline, glowing gold pill CTA.
• Reduced-motion state: turntable, parallax, tilt and scroll-scrub disabled; static hero render, static road illustration, and a swipeable/scrollable testimonial row with every card fully reachable.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A real-time R3F scene: one glossy car model on a circular reflective plinth, warm HDRI environment (studio softbox + gold rim light), soft elliptical contact shadow, dark radial-gradient backdrop. The scene shows the product's defining state — the car as a desirable object under light — and responds to pointer/touch with damped parallax and a slow idle turntable. Lazy-load the .glb; fall back to a pre-rendered 3/4 studio PNG when WebGL is unavailable.

9. Non-Functional Requirements

• Performance (explicit): target 60fps; lazy-load 3D models; support mobile devices.
• Responsiveness (explicit): full responsive design for mobile, tablet and desktop; single column at 375px with 20px gutters; readable text and controls stay whole at 375px, 768px and 1280px.
• Accessibility (explicit): basic accessibility — semantic structure, keyboard-reachable controls, and a reduced-motion arrangement that keeps every item reachable.
• SEO (explicit): basic SEO — meaningful title, meta description, and semantic headings.
• Internationalization (explicit): full RTL/Arabic support with a switch to French and English; direction follows language.
• Graceful degradation (explicit): static-image fallback when WebGL is unsupported.
• Code quality (explicit): clean code split into reusable components.
• Runnability (explicit): the project runs with npm run dev.

10. Tech Stack

• Frontend: React + Vite + Tailwind CSS.
• 3D: Three.js with React Three Fiber and Drei.
• Scroll animation: GSAP + ScrollTrigger.
• Transitions: Framer Motion.
• Backend: shared FastAPI process (provisioned infrastructure; no accepted homepage requirement adds server-side behavior).
• Database: MariaDB (provisioned application-owned storage; no accepted requirement defines a schema).
• Delivery: complete project files runnable with npm run dev, including a short explanation of how to run it and where to place .glb models.

11. Assumptions and Constraints

• Hard constraint (explicit): only the homepage is required, not the whole website.
• Hard constraint (explicit): the project must run with npm run dev.
• Hard constraint (explicit): a static-image fallback must be provided when WebGL is unsupported.
• Hard constraint (explicit): RTL and Arabic must be fully supported with a switch to French and English.
• Hard constraint (explicit): 60fps performance, lazy-loaded models, and mobile support.
• Hard constraint (explicit): fully responsive design for mobile, tablet and desktop.
• Assumption: the visitor is anonymous; no account, login, or permission model is required by any accepted requirement.
• Assumption: the search button and WhatsApp button are outward actions on the landing page; no booking transaction or reservation record is specified.
• Assumption: the provisioned FastAPI backend and MariaDB database are infrastructure for the delivered project and do not introduce product behavior beyond the accepted homepage.
• Assumption: car data, testimonials and trust promises are presentation content of the landing page; no authoritative content source was supplied.

12. Glossary

• divine-3d — the project name of the car-rental homepage.
• Hero — the top section with the 3D car, headline and CTA.
• Plinth — the reflective circular platform the 3D car sits on.
• HDRI — high-dynamic-range image used for cinematic lighting.
• .glb — the 3D model file format for the car.
• Glassmorphism — frosted-glass visual effect used by the search capsule.
• Tilt effect — 3D card lean that follows the mouse.
• ScrollTrigger — GSAP plugin that ties animation to scroll progress.
• RTL — right-to-left text direction used for Arabic.
• WebGL fallback — static image shown when 3D rendering is unavailable.
• Preloader — loading screen with an animated car and percentage.
• Custom cursor — a styled mouse pointer replacing the default.