🌸 Velar Perfume Explorer

Velar Perfume Explorer is an intelligent, emotion-driven perfume discovery platform that blends AI, scent analytics, and creative design to help users explore, create, and connect with fragrances on a deeper emotional level.

Built as a full-stack Next.js 15 application, Velar provides both an AI-driven user experience and a helpful admin dashboard for managing the growing perfume collection.

---

✨ Core Features

🧭 1. Explore Perfumes (Completed)

Browse, filter, and discover perfumes through an elegant, minimal interface.
Powered by fast data fetching with TanStack Query, and dynamic content from Firestore and Supabase Storage.

---

🧠 2. Memory-Based Discovery (In Development)

Describe a memory or emotion, and Velar’s AI recommends the closest perfumes to that feeling.

Example: “A summer evening near the ocean” → Velar suggests perfumes evoking that mood.

---

⚗️ 3. AI Perfume Combiner (In Development)

Mix two or more perfumes and let the AI generate a hypothetical blend — complete with:

• A unique perfume name
• A generated bottle design
• A scent description

---

🎲 4. Blind Pick (In Development)

An experimental feature that selects a random perfume for users seeking surprise and serendipity.

---

🧩 Tech Stack

Layer	Technologies
Framework	Next.js 15 (App Router)
Language	TypeScript
Database	Firebase Firestore
Storage	Supabase (for perfume images & assets)
Auth	NextAuth.js
Validation	Zod
Forms	React Hook Form
Data Fetching	TanStack Query
Styling/UI	Tailwind CSS + shadcn/ui
Hosting	Vercel

---

🛠️ Admin Dashboard

A secure, intuitive admin panel for managing perfumes:

• ➕ Add new perfumes with image uploads
• 🗑️ Delete or update existing perfumes
• 🔒 Restricted access with NextAuth

---

🧠 Folder Structure Overview

• app/ – Main application entry point using the Next.js App Router.

  • (auth)/login/ – Handles user authentication pages, including login and session flow via NextAuth.
  • admin/ – Protected admin area for managing perfumes.
    • add/ – Interface for adding new perfumes (integrated with React Hook Form + Zod validation).
    • edit/ – Edit and update existing perfume entries.
    • dashboard/ – Central admin overview displaying existing perfumes and management actions.
  • explore/[slug]/ – Dynamic route for exploring individual perfume details and related recommendations.
  • api/ – Server-side API endpoints powering all backend operations.
    • auth/ – Authentication endpoints (NextAuth configuration and session handling).
    • perfumes/ – Handles all CRUD operations on Firestore for perfumes.
    • send/ – Routes for sending or handling user-generated requests.
    • upload/ – Integrates Supabase storage for uploading and managing perfume images.

• components/ – Reusable UI and layout components across the app.

  • custom/ – Project-specific visual components (forms, perfume cards, modals, etc.).
  • ui/ – Base design system components built with shadcn/ui and Tailwind CSS.

• lib/ – Core libraries and configuration utilities (Firebase initialization, Supabase client, etc.).

• providers/ – Context providers for authentication, theming, and TanStack Query state management.

• schemas/ – Zod schemas defining validation and type safety across forms and APIs.

• types/ – Centralized TypeScript type definitions for consistent data modeling.

• utilities/ – Helper functions, constants, and common logic for formatting, data handling, and validation.

Designed with scalability and clean separation of concerns — fully modular and future-proof.

---

🧩 System Architecture

The diagram below shows how data, authentication, and requests flow across the application.

flowchart TD

%% Users
A[👤 User] -->|Login / Register| B[(NextAuth)]
A -->|Explore Perfumes| C[Explore Pages - explore/]
A -->|Memory / Emotion Search| D[AI Feature - In Dev]
A -->|Blind Pick| D

%% Admin
E[🧑‍💼 Admin] -->|Auth Required| B
E -->|Add / Edit / Delete Perfumes| F[Admin Panel - admin/]

%% API Routes
C -->|Fetch Perfume Data| G[API: perfumes]
F -->|Upload Images| H[API: upload]
B -->|Auth Session| I[API: auth]
F -->|Send Notifications| J[API: send]

%% Databases
G -->|CRUD| K[(Firebase Firestore)]
H -->|Image Storage| L[(Supabase Storage)]
I -->|User Sessions| M[(NextAuth Session DB)]

%% Styling and UI
C --> N[shadcn/ui + TailwindCSS]
F --> N
D --> N

%% Data Layer
C --> O[TanStack Query + Zod Validation]
D --> O
F --> O

Loading

---

🧠 What I Learned

Building Velar taught me to combine creative product thinking with strong technical foundations.
From managing scalable Firestore data models to designing dynamic routes with the Next.js App Router, this project helped refine my full-stack skills, API architecture design, and type-safe React development with Zod and TanStack Query.