🏷️ Project Title

Next.js Fullstack Supabase Multi-Step Form Automation System

---

🧾 Executive Summary

• Enterprise-grade full-stack animated multi-step form automation system built with Next.js 16, TypeScript, and Framer Motion v12.
• Handles structured multi-stage data collection, real-time field validation via React Hook Form, secure multi-file uploads to Supabase Storage, and automated email acknowledgments.
• Features a fully animated 4-step wizard UI with directional slide transitions, bezier easing, animated progress indicators, pill-based multi-select components, dark/light theming, and a pre-submission review panel.
• Designed for scalability, automation, and production deployment using Vercel.

Layer	Technology	Purpose
Frontend	Next.js 16 + TypeScript	UI rendering, routing & type safety
Animation	Framer Motion v12	Step transitions, presence animations & easing
Forms	React Hook Form	Validation, field registration & submission
Theming	next-themes + Tailwind CSS	Dark/light mode with CSS variable tokens
Backend	Next.js API Routes	Processing & email logic
Database	Supabase PostgreSQL	Structured data storage
Storage	Supabase Storage	Multi-file upload & retrieval
Email	Nodemailer + Gmail SMTP	Automated acknowledgment delivery
Icons	lucide-react	UI iconography (Sun, Moon, Check, Chevrons)

---

📑 Table of Contents

1. 🧩 Project Overview
2. 🎯 Objectives & Goals
3. ✅ Acceptance Criteria
4. 💻 Prerequisites
5. ⚙️ Installation & Setup
6. 🔗 API Documentation
7. 🖥️ UI / Frontend
8. 🔢 Status Codes
9. 🚀 Features
10. 🧱 Tech Stack & Architecture
11. 🛠️ Workflow & Implementation
12. 🧪 Testing & Validation
13. 🔍 Validation Summary
14. 🧰 Verification Testing Tools
15. 🧯 Troubleshooting & Debugging
16. 🔒 Security & Secrets
17. ☁️ Deployment and DevOps
18. ⚡ Quick-Start Cheat Sheet
19. 🧾 Usage Notes
20. 🧠 Performance & Optimization
21. 🌟 Enhancements & Features
22. 🧩 Maintenance & Future Work
23. 🏆 Project Milestones
24. 🧮 High-Level Architecture
25. 🗂️ Project Structure
26. 🧭 How to Demonstrate Live
27. 💡 Summary, Closure & Compliance

---

🧩 Project Overview

• Animated multi-step public form-based intake system
• Captures structured university participation data across 4 sequential steps
• Validates all inputs in real time using React Hook Form with field-level error display
• Uploads logos, headshots, brochures, and additional documents securely to Supabase Storage
• Sends automated acknowledgment emails via Nodemailer SMTP
• Supports dark and light mode with animated theme toggling

User → Animated 4-Step Form UI → React Hook Form Validation → API Route → Supabase DB + Storage → Email Service

---

🎯 Objectives & Goals

• Enable seamless, guided multi-step form submissions with animated step transitions
• Enforce real-time field validation and structured error feedback at each step
• Automate backend workflows from submission to database insertion to email dispatch
• Ensure secure, UUID-namespaced multi-file upload handling
• Deliver a polished, accessible UI with dark/light theming and motion-enhanced interactions
• Design scalable, maintainable architecture suitable for enterprise deployment

Goal	Outcome
Automation	Reduce manual intervention across all data capture workflows
Scalability	Handle large volumes of submissions with UUID-isolated storage paths
Security	Protected storage, RLS-enforced database, and environment-secured secrets
UX Quality	Animated, accessible multi-step interface with real-time feedback

---

✅ Acceptance Criteria

ID	Feature	Validation
AC1	Multi-Step Form Navigation	Each step validates before advancing; back navigation preserves state
AC2	React Hook Form Validation	Required fields block progression; inline errors appear on invalid input
AC3	Framer Motion Transitions	Directional slide animations play correctly on step advance and back
AC4	Dark / Light Theme Toggle	Theme persists across page loads; animated icon swap renders correctly
AC5	File Upload	Logo, headshot, brochure, and multiple additional files appear in Supabase Storage
AC6	Database Insertion	Full payload including metadata, levels, events, and file URLs stored correctly
AC7	Email Acknowledgment	Confirmation email received at representative's address after submission
AC8	Responsive UI	Form renders correctly across mobile, tablet, and desktop viewports
AC9	Pre-Submission Review	Summary card on Step 4 displays live-watched field values before submit

---

💻 Prerequisites

• Node.js (v18+)
• npm or yarn package manager
• Supabase project with a configured PostgreSQL database and Storage bucket
• Gmail account with an App Password configured for SMTP
• Vercel account for production deployment

---

⚙️ Installation & Setup

1. Clone the repository
2. Install all dependencies (includes Framer Motion, React Hook Form, next-themes, lucide-react)
3. Configure all environment variables in .env.local
4. Run the development server

Step	Command / Action	Description
1	git clone <repo-url>	Clone repository locally
2	npm install	Install all dependencies including animation and form libraries
3	Edit .env.local	Set Supabase URL, Anon Key, Storage Bucket, and Gmail SMTP credentials
4	npm run dev	Start Next.js development server at localhost:3000

Required Environment Variables

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_SUPABASE_BUCKET=your_storage_bucket_name
SMTP_USER=your_gmail_address
SMTP_PASS=your_gmail_app_password

---

🔗 API Documentation

Endpoint	Method	Input	Output
/api/send-email	POST	toEmail, universityName, representativeName	200 Success / 400 Bad Request / 500 SMTP Failure

Request Payload

{
  "toEmail": "rep@university.edu",
  "universityName": "University of Melbourne",
  "representativeName": "Jane Smith"
}

Processing Flow

1. Receive POST request at /api/send-email
2. Validate presence of required fields
3. Initialize Nodemailer transporter with Gmail SMTP credentials
4. Compose acknowledgment email with university and representative details
5. Dispatch email via SMTP
6. Return 200 on success or appropriate error code on failure

Non-Fatal Invocation

The email API is called as a best-effort, non-fatal side effect after successful
database insertion. A failure in email dispatch does not roll back or block the
form submission — the user is redirected to /thank-you regardless.

---

🖥️ UI / Frontend

Pages

• /page.tsx → Entry point, renders the main Form component
• /thank-you → Post-submission confirmation page with ThankYouContent component
• /confirm/[token] → Token-based confirmation route

Components

Component	Responsibility	Key Features
Form.tsx	Main wizard logic, state, and submission	4-step flow, Framer Motion transitions, React Hook Form, Supabase integration, dark/light toggle
FileUpload.tsx	File selection and preview	Single and multi-file support, accept filtering, remove capability
PhoneInput.tsx	International phone number capture	Formatted phone input with required validation
ThemeProvider.tsx	Dark/light mode context wrapper	next-themes integration with SSR hydration guard
ThankYouContent.tsx	Post-submission confirmation UI	Confirmation message and next-steps display

Multi-Step Form Structure

Step	Title	Fields	Validation
1	🏛️ University	University name, logo upload, city, state, country	All fields required; logo optional
2	👤 People	Rep name, designation, email, phone, headshot; submitter name and contact	Rep fields required; phone validated outside RHF; submitter optional
3	📊 Recruitment	Levels (pill multi-select), events (pill multi-select), time slots (pill optional), highlights, deposit link	At least one level and one event required
4	📎 Documents	Brochure upload, additional documents (multi), remarks, summary review card, consent checkbox	Consent required; summary displays live-watched values

Animated Step Progress Indicator

- Track background rendered as absolute-positioned div
- Animated fill uses Framer Motion scaleX driven by (step - 1) / (totalSteps - 1)
- Each step node animates backgroundColor, borderColor, and boxShadow between states:
    Active   → blue  (#0f62fe) with blue glow shadow
    Complete → green (#22c55e) with green glow shadow
    Inactive → CSS variable (--bg-card) / (--border)
- Completed nodes render animated Check icon via AnimatePresence

Directional Slide Transition System

- Direction state (dir) tracks +1 (forward) or -1 (backward)
- stepVariants object defines enter, center, and exit states
- Bezier easing typed as [number, number, number, number] tuple for framer-motion v12 compatibility
- AnimatePresence with mode="wait" ensures clean enter/exit sequencing
- Each step motion.div receives custom={dir} to pick directional offset

Dark / Light Theme Architecture

- ThemeProvider wraps the application via next-themes
- CSS custom properties (--bg-surface, --text-primary, --brand-primary, etc.) toggle per theme
- Theme toggle button uses AnimatePresence mode="wait" to swap Sun / Moon icons
- Mounted state guard prevents SSR hydration mismatch

State Flow

User Input → React Hook Form State + Custom State (phone, pills, files)
    → Per-Step trigger() Validation
    → Step Advance / Error Display
    → Final handleSubmit → Supabase Upload + DB Insert → Email API → Router Push

Where to Change Styles

• globals.css → CSS variable tokens, dark/light theme overrides, global component classes
• Form.tsx → Inline style props for motion-dependent values
• tailwind.config.js → Tailwind theme extensions and breakpoints

---

🔢 Status Codes

Code	Description	Scenario
200	OK	Email dispatched successfully via SMTP
400	Bad Request	Missing or invalid input fields in API request
500	Server Error	SMTP transport failure or Supabase insert error

---

🚀 Features

• Animated 4-step multi-step form wizard with directional slide transitions powered by Framer Motion v12
• Real-time per-step field validation using React Hook Form with inline animated error messages
• Animated step progress indicator with active, complete, and inactive node states
• Pill-based animated multi-select UI for levels, events, and time slot selection
• International phone number capture with custom PhoneInput component
• Multi-file upload system supporting logo, headshot, brochure, and additional documents
• UUID-namespaced Supabase Storage paths for collision-free file isolation per submission
• Supabase lazy singleton pattern for optimized client initialization
• Pre-submission live-watched summary review card on final step
• Animated error banner system with height-animated entrance and exit
• Dark/light mode theming via next-themes with animated Sun/Moon icon swap
• Automated acknowledgment email dispatch via Nodemailer SMTP (best-effort, non-fatal)
• Submission payload enriched with client_metadata (timestamp, user agent, platform) and system_metadata (form version, submission UUID)
• Consent gate checkbox with validation before final submission
• Loading state with spinner and disabled button during async submission
• Full TypeScript coverage with strict tuple typing, typed helpers, and no implicit any

Category	Feature	Technical Implementation
Animation	Step Transitions	Framer Motion stepVariants with custom direction, bezier tuple EASE, AnimatePresence mode="wait"
Animation	Progress Bar	motion.div scaleX animated to (step-1)/(total-1) fraction with easeInOut
Animation	Theme Toggle	AnimatePresence mode="wait" with rotating Sun/Moon icon swap
Animation	Pill Selection	AnimatePresence on Check icon inside each pill; whileTap scale feedback
Forms	Validation	useForm with mode="onChange"; per-step trigger(); custom phone and pill validation
Forms	Summary	watch() on university_name, rep_name, rep_email for live review display
Storage	File Uploads	UUID-based folder paths; parallel Promise.all for primary files; sequential loop for extras
Backend	API Automation	Next.js API Route with Nodemailer; non-fatal fire-and-forget pattern
Database	Data Insertion	Supabase insert with full payload including arrays, URLs, metadata objects
TypeScript	Type Safety	FormValues interface; FileSetter/UrlSetter aliases; EASE tuple; typed processFile helper

---

🧱 Tech Stack & Architecture

Layer	Technology	Version	Responsibility
Framework	Next.js	^16.0.8	SSR, routing, API routes, build optimization
Language	TypeScript	5.2.2	Static typing, interface definitions, tuple enforcement
UI Rendering	React	18.2.0	Component model, hooks, state management
Animation	Framer Motion	^12.38.0	Step transitions, presence animations, progress bar, icon swaps
Forms	React Hook Form	latest	Registration, validation, trigger, watch, submission handling
Theming	next-themes	^0.4.6	Dark/light mode persistence and SSR-safe hydration
Styling	Tailwind CSS	^3.3.6	Utility-first styling, responsive grid, spacing
Icons	lucide-react	^0.560.0	Sun, Moon, Check, ChevronLeft, ChevronRight icons
Database	Supabase PostgreSQL	^2.87.1	Structured submission data storage with RLS
Storage	Supabase Storage	^2.87.1	UUID-namespaced file upload and public URL generation
Email	Nodemailer	^8.0.4	SMTP-based acknowledgment email delivery

[Client Browser]
      ↓
[Next.js UI Layer — 4-Step Animated Form Wizard]
      ↓ (React Hook Form validation per step)
[Framer Motion AnimatePresence — Directional Slide Transitions]
      ↓
[Next.js API Routes Layer — /api/send-email]
      ↓
[Supabase PostgreSQL DB] ←→ [Supabase Storage — UUID-namespaced folders]
      ↓
[Nodemailer SMTP Email Service — Gmail]
      ↓
[Vercel Production Deployment]

---

🛠️ Workflow & Implementation

1. User accesses form via frontend route; ThemeProvider initializes dark/light mode
2. Step 1 renders with Framer Motion enter animation; user fills university details
3. React Hook Form trigger() validates Step 1 fields before advancing to Step 2
4. Step 2 captures representative details including phone (custom state) and optional headshot upload
5. Step 3 uses animated Pill components for multi-select of levels, events, and time slots
6. Step 4 renders file upload fields, a live-watched summary review card, and consent checkbox
7. On submit, crypto.randomUUID() generates a unique submission ID and folder namespace
8. Primary files (logo, headshot, brochure) are uploaded in parallel via Promise.all
9. Additional documents are uploaded sequentially; all public URLs are collected
10. Full structured payload (including arrays, file URLs, and metadata objects) is inserted into Supabase PostgreSQL
11. Acknowledgment email is dispatched via /api/send-email as a best-effort, non-fatal side effect
12. User is redirected to /thank-you confirmation page via Next.js router

---

🧪 Testing & Validation

ID	Area	Method	Expected Output	Explanation
TC01	Step Navigation	Attempt advance with empty required fields	Inline errors appear; step does not advance	Validates React Hook Form per-step trigger() enforcement
TC02	Phone Validation	Attempt Step 2 advance with empty phone	Error banner: "Phone number is required."	Validates custom phone state guard outside RHF
TC03	Pill Validation	Attempt Step 3 advance without selecting levels or events	Error banner displayed; step blocked	Validates pill selection minimum requirement
TC04	Theme Toggle	Click Sun/Moon button	Theme switches; icon animates; preference persists on reload	Validates next-themes integration and AnimatePresence icon swap
TC05	File Upload	Upload logo, headshot, brochure, and extra documents	Files appear in Supabase Storage under UUID-namespaced folder	Validates upload pipeline and public URL generation
TC06	Database	Complete full form submission	Row inserted with all fields, arrays, URLs, and metadata	Validates full payload structure and Supabase insert
TC07	Email	Submit form with valid representative email	Acknowledgment email received at rep address	Validates Nodemailer SMTP dispatch
TC08	Summary Card	Fill Steps 1–3 then view Step 4	Summary card displays university, rep name, email, levels, events	Validates React Hook Form watch() live data binding
TC09	Consent Gate	Attempt submit without checking consent	Inline error: "You must consent to proceed"	Validates RHF required checkbox enforcement
TC10	Framer Motion	Navigate forward and backward through all steps	Correct directional slide transitions play on each navigation	Validates stepVariants custom direction and AnimatePresence exit/enter

---

🔍 Validation Summary

• All four form steps validated independently before progression is permitted
• React Hook Form trigger() enforces field-level rules; custom guards enforce pill and phone state
• File upload pipeline validated for single files, multi-file accumulation, and URL passthrough
• Database payload validated for correct field mapping including array fields and nested metadata
• Email dispatch validated as non-blocking; failures logged as warnings without interrupting submission
• TypeScript compilation validated with no type errors after EASE tuple fix
• System validated for production readiness on Vercel

---

🧰 Verification Testing Tools & Command Examples

Tool	Usage
Browser DevTools (Network tab)	Inspect Supabase API calls, file upload requests, and /api/send-email POST
Browser DevTools (Console)	Monitor non-fatal email warning logs and submission error messages
Supabase Dashboard (Table Editor)	Verify inserted row structure, array fields, metadata objects, and file URL columns
Supabase Dashboard (Storage)	Confirm UUID-namespaced folder creation and uploaded file presence
Postman	Direct POST to /api/send-email with JSON body to test SMTP independently
TypeScript Compiler (tsc --noEmit)	Validate zero type errors across all components including tuple-typed EASE constant

---

🧯 Troubleshooting & Debugging

• Verify all five required environment variables are present in .env.local and Vercel dashboard
• If SMTP fails, confirm Gmail App Password is active and 2FA is enabled on the Google account
• If Supabase upload returns "Upload returned no data", check bucket name in NEXT_PUBLIC_SUPABASE_BUCKET and bucket public access policy
• If TypeScript reports ease-related type errors, ensure EASE is declared as const EASE: [number, number, number, number] — not inferred as number[]
• If theme toggle causes hydration mismatch, confirm mounted state guard wraps all theme-dependent renders
• If Framer Motion AnimatePresence does not animate on step change, confirm each step motion.div has a unique key prop (s1, s2, s3, s4)
• Inspect Supabase Row Level Security policies if inserts are silently rejected
• Use tsc --noEmit to surface TypeScript errors before deployment

---

🔒 Security & Secrets

• All secrets stored in .env.local and injected via Vercel environment variable configuration — never committed to source control
• .gitignore explicitly excludes .env.local and .env files
• Supabase Row Level Security (RLS) enforced on the university_participation table
• Supabase Storage bucket policies restrict unauthorized read/write access
• Supabase client initialized as a lazy singleton — anon key is public-safe by design; no service role key exposed to the frontend
• File upload paths are UUID-namespaced (crypto.randomUUID()) preventing path enumeration or collision
• SMTP credentials secured via server-side API route — never exposed to the client bundle
• No sensitive data serialized into client-side state or localStorage

---

☁️ Deployment

1. Push code to GitHub repository (nextjs-multistep-registration-portal)
2. Import project into Vercel and connect to the GitHub repository
3. Configure all five environment variables in Vercel project settings
4. Trigger production deployment via Vercel dashboard or git push to main
5. Validate live application: complete a full form submission and verify database, storage, and email

Stage	Action	Detail
Build	Compile Next.js project	next build — TypeScript checked, pages and API routes compiled
Configure	Set environment variables	Supabase URL, Anon Key, Bucket, SMTP user and password in Vercel dashboard
Deploy	Host on Vercel	Automatic deployment on push to main branch
Validate	Test live system end-to-end	Submit form → check Supabase DB, Storage, and email inbox

---

⚡ Quick-Start Cheat Sheet

Step	Action	Command / Location	Outcome
1	Clone repository	git clone <repo-url>	Local project directory ready
2	Install dependencies	npm install	All packages installed including Framer Motion, RHF, next-themes
3	Configure environment	.env.local	Supabase and SMTP credentials secured
4	Run development server	npm run dev	App accessible at localhost:3000
5	Verify TypeScript	npx tsc --noEmit	Zero type errors confirmed
6	Deploy to Vercel	Push to main / Vercel dashboard	Live production application

---

🧾 Usage Notes

• All required fields on each step must be completed before the Continue button will advance the form
• At least one Level and one Event must be selected on Step 3 via the pill selectors
• Phone number must be entered on Step 2; it is managed outside React Hook Form and validated separately
• File uploads accept the formats specified per field; additional documents can be added one-by-one and accumulate in state
• The summary review card on Step 4 displays live values — verify university name, representative, email, levels, and events before submitting
• Consent checkbox is required and must be checked before the Submit Confirmation button becomes functional
• Theme preference (dark/light) is persisted across sessions via next-themes local storage mechanism
• Email acknowledgment is best-effort; if SMTP is misconfigured the submission still completes successfully

---

🧠 Performance & Optimization

• Supabase client initialized as a lazy singleton — client is created once and reused, avoiding redundant instantiation on every function call
• Primary file uploads (logo, headshot, brochure) run in parallel using Promise.all, minimizing total upload time
• React Hook Form watch() scoped to only three fields (university_name, rep_name, rep_email) to minimize re-renders on the summary card
• Pill component defined outside the Form function to prevent re-creation on every parent render cycle
• AnimatePresence mode="wait" ensures only one step is mounted at a time, keeping the DOM minimal during transitions
• Framer Motion EASE constant declared once as a typed tuple — evaluated at module load, not on each render
• useEffect-gated mounted flag prevents unnecessary theme reads during SSR, eliminating hydration flicker
• Tailwind CSS purged in production build — only used utility classes are included in the final CSS bundle

Area	Optimization	Benefit
Supabase Client	Lazy singleton pattern	Single instantiation, reduced overhead
File Uploads	Promise.all parallelization	Faster multi-file upload completion
Form State	Scoped watch() on 3 fields	Reduced unnecessary re-renders
Animation	AnimatePresence mode="wait"	Single mounted step, minimal DOM footprint
Components	Pill defined outside Form	Stable reference, no re-creation on parent render
CSS	Tailwind production purge	Minimal CSS bundle size

---

🌟 Enhancements & Features

• ✅ Animated 4-step wizard with directional Framer Motion transitions (implemented)
• ✅ React Hook Form per-step validation with inline animated error messages (implemented)
• ✅ Animated step progress indicator with active/complete/inactive node states (implemented)
• ✅ Pill-based animated multi-select for levels, events, and time slots (implemented)
• ✅ Dark/light mode theming with animated Sun/Moon icon swap via next-themes (implemented)
• ✅ UUID-namespaced Supabase Storage with parallel and sequential upload strategies (implemented)
• ✅ Pre-submission live-watched summary review card (implemented)
• ⬜ Admin panel for viewing, filtering, and exporting form submissions
• ⬜ Real-time analytics dashboard for submission volume and event popularity
• ⬜ AI-assisted field suggestions and programme highlight generation
• ⬜ Email template upgrade with HTML formatting and branding
• ⬜ Webhook integration for CRM or Slack notification on new submission

---

🧩 Maintenance & Future Work

• Keep framer-motion, react-hook-form, next-themes, and lucide-react dependencies up to date — review changelogs for breaking animation API changes between major versions
• Monitor Supabase Storage bucket usage and implement lifecycle policies for old submission files
• Upgrade Nodemailer SMTP configuration to a transactional email provider (SendGrid, Resend, or AWS SES) for production-scale email delivery
• Add unit tests for validation logic and integration tests for the Supabase insert pipeline
• Implement structured logging and error monitoring (Sentry or Axiom) for production observability
• Extend the submission payload schema to support additional recruitment data fields as requirements evolve

---

🏆 Project Milestones

• ✅ Initial project setup with Next.js, TypeScript, and Tailwind CSS
• ✅ Supabase PostgreSQL and Storage integration with RLS-enforced security
• ✅ React Hook Form integration with per-step field validation and inline errors
• ✅ Framer Motion v12 animated 4-step wizard with directional slide transitions
• ✅ Animated step progress indicator with bezier-eased fill bar and node state transitions
• ✅ Pill-based multi-select components with AnimatePresence Check icon animations
• ✅ Dark/light mode theming with next-themes and animated icon swap
• ✅ UUID-namespaced multi-file upload pipeline with parallel and sequential strategies
• ✅ Pre-submission live-watched summary review card
• ✅ Nodemailer SMTP email automation with best-effort non-fatal dispatch
• ✅ Full TypeScript coverage with EASE tuple fix resolving all ts(2322) errors
• ✅ Production deployment via Vercel validated end-to-end

---

🧮 High-Level Architecture

🔹 System Overview

• Client-side UI built with Next.js renders an animated 4-step multi-step wizard powered by Framer Motion v12
• React Hook Form manages field registration, per-step validation triggering, and final submission handling
• Custom state manages phone number, pill multi-selections, and file accumulation outside RHF scope
• next-themes provides SSR-safe dark/light mode switching with CSS variable token architecture
• API Routes layer processes email dispatch via Nodemailer SMTP as a non-fatal side effect
• Supabase handles structured PostgreSQL storage and UUID-namespaced file storage with public URL generation

🔹 Architecture Flow Diagram

[User Browser]
      ↓
[Next.js Frontend — Animated 4-Step Form Wizard]
      ↓ Framer Motion AnimatePresence (directional slide transitions)
[React Hook Form — Per-Step trigger() Validation]
      ↓
[Next.js API Routes — /api/send-email]
      ↓                              ↓
[Supabase PostgreSQL DB]    [Supabase Storage — UUID folders]
      ↓
[Nodemailer SMTP — Gmail]
      ↓
[User Redirected to /thank-you]

🔹 Component Responsibilities

Component	Role	Responsibility
Form.tsx	Wizard Orchestrator	Step state, direction, validation, upload, insert, and routing
FileUpload.tsx	File Layer	File selection, preview, removal, and onSelect callback dispatch
PhoneInput.tsx	Input Component	Formatted phone capture with required validation support
ThemeProvider.tsx	Theme Layer	next-themes context wrapper with SSR hydration guard
API Route	Logic Layer	SMTP email composition and dispatch via Nodemailer
Supabase DB	Data Layer	Structured submission storage with array and metadata fields
Supabase Storage	File Layer	UUID-namespaced upload and public URL generation
Email Service	Notification Layer	Automated acknowledgment delivery to representative email

🔹 Data Flow (Step-by-Step)

1. User completes each step; React Hook Form trigger() validates required fields before advance
2. Custom state tracks phone, pill selections, and accumulated file objects independently
3. On final submit, crypto.randomUUID() generates a unique submission ID and storage folder path
4. Primary files uploaded in parallel (Promise.all); additional documents uploaded sequentially
5. Full payload assembled — including arrays, file URLs, client_metadata, and system_metadata
6. Payload inserted into Supabase PostgreSQL via supabase.from().insert()
7. Email dispatch triggered as best-effort POST to /api/send-email (non-fatal on failure)
8. User redirected to /thank-you via Next.js router.push()

---

🗂️ Project Structure (Tree)

🔹 Project Directory Structure

root/
├── app/
│   ├── api/
│   │   └── send-email/
│   │       └── route.ts          ← Nodemailer SMTP API route
│   ├── confirm/
│   │   └── [token]/
│   │       └── page.tsx          ← Token-based confirmation route
│   ├── thank-you/
│   │   ├── page.tsx              ← Post-submission confirmation page
│   │   └── ThankYouContent.tsx   ← Confirmation UI component
│   ├── layout.tsx                ← Root layout with ThemeProvider
│   └── page.tsx                  ← Entry point rendering Form component
├── components/
│   ├── Form.tsx                  ← 4-step animated wizard (main component)
│   ├── FileUpload.tsx            ← Single and multi-file upload component
│   ├── PhoneInput.tsx            ← International phone input component
│   └── ThemeProvider.tsx         ← next-themes SSR-safe context wrapper
├── lib/
│   └── supabaseClient.ts         ← Supabase client (if used outside Form)
├── public/                       ← Static assets
├── globals.css                   ← CSS variable tokens, dark/light overrides
├── package.json
├── tailwind.config.js
├── next.config.js
└── tsconfig.json

🔹 Folder Responsibilities

Folder / File	Purpose
app/	Next.js App Router pages, layouts, and API routes
components/	Reusable UI components including animated wizard, file upload, and phone input
lib/	Shared utility and service integrations
public/	Static assets served at root URL
globals.css	CSS custom property tokens for dark/light theming and global component classes

🔹 Execution Flow Mapping

User Action → app/page.tsx → components/Form.tsx (4-step wizard)
    → React Hook Form validation
    → Framer Motion AnimatePresence transitions
    → Supabase Storage upload (UUID-namespaced)
    → Supabase DB insert (full structured payload)
    → app/api/send-email/route.ts (Nodemailer SMTP)
    → app/thank-you/page.tsx

---

🧭 How to Demonstrate Live

1. Open the deployed Vercel URL in a browser
2. Toggle between dark and light mode using the theme button — observe the animated Sun/Moon icon swap
3. Complete Step 1: enter university name, upload a logo, and fill city/state/country
4. Complete Step 2: fill representative name, designation, email, phone, and optionally upload a headshot
5. Complete Step 3: select levels and events using the animated pill buttons; optionally select time slots
6. Observe the animated progress indicator advancing and completing nodes as you move through steps
7. On Step 4: upload a brochure, add remarks, and verify the live summary review card reflects your Step 1–3 entries
8. Check the consent checkbox and click Submit Confirmation — observe the loading spinner
9. Verify the inserted row in the Supabase Table Editor including arrays, file URLs, and metadata
10. Verify uploaded files appear in the Supabase Storage bucket under the UUID-namespaced folder
11. Confirm the acknowledgment email was received at the representative email address

---

💡 Summary, Closure & Compliance

• System delivers a production-grade animated multi-step form automation pipeline from UI through database and email
• All advanced UI interactions — step transitions, progress animation, pill selection, theme toggle, error banners — are powered by Framer Motion v12 with correct TypeScript tuple typing
• React Hook Form provides robust per-step validation with inline error feedback; custom state guards cover phone and pill inputs outside RHF scope
• Supabase integration covers both structured PostgreSQL storage and UUID-namespaced file storage with parallel upload optimization
• Email automation is implemented as a best-effort, non-fatal side effect — submission integrity is never dependent on SMTP availability
• Full TypeScript coverage enforced with zero type errors; EASE tuple pattern resolves framer-motion v12 BezierDefinition compatibility
• Secure by design: RLS-enforced database, environment-secured secrets, UUID-isolated storage paths, and no server-side credentials exposed to the client
• Compliant with modern Next.js App Router architecture, React 18 patterns, and Vercel deployment standards
• Ready for enterprise-level enhancements including admin dashboard, AI-assisted validation, and transactional email provider upgrade