Perfume Vault

Perfume Vault is a premium full-stack fragrance collection platform built for serious perfume collectors. It combines secure authentication, detailed bottle metadata, virtual shelf management, wishlist tracking, and collection analytics in a polished collector-focused interface.

The application is designed to feel like a digital luxury fragrance rack: structured, elegant, and practical enough for daily use.

What It Does

• Secure user authentication with Laravel Jetstream
• Personal perfume collection management
• Detailed fragrance metadata tracking
• Virtual shelf and rack organization
• Wishlist management with conversion into collection items
• Usage and performance analytics
• Profile management, photo upload, sessions, and optional 2FA
• Versioned API endpoints for future mobile or external clients

Technology Stack

• PHP 8.3+
• Laravel 13
• Laravel Jetstream
• Livewire 3 + Volt
• Laravel Sanctum
• Tailwind CSS
• Alpine.js
• Vite
• Pest
• SQLite by default for local development, with architecture ready for MySQL/PostgreSQL

Key Features

Collection Management

• Create, edit, delete, archive, and duplicate perfumes
• Track:
  • brand
  • house
  • concentration
  • gender category
  • release year
  • batch code
  • retail price and current market value
  • notes and accord breakdown
  • sillage, longevity, projection, and performance
  • number of wears and last worn date
  • bottle size and remaining juice
  • personal notes, memories, and review

Live Rack

• Shelf-based organization
• Section-based arrangement
• Drag-and-drop rack ordering
• Collector-style visual layout

Wishlist

• Add target bottles
• Store target and current prices
• Prioritize wishlist items
• Convert wishlist entries directly into collection records

Analytics

• Collection value
• Favorite brand
• Most worn perfume
• Seasonal and category breakdowns
• Usage trends
• Accord distribution

Architecture

The project is structured around separated application layers:

app/
├── Application
├── Contracts
├── Domain
├── Infrastructure
├── Policies
├── Presentation

High-level responsibilities:

• Domain: core models and enums
• Application: DTOs, actions, and services
• Contracts: repository interfaces
• Infrastructure: Eloquent repository implementations
• Presentation: web controllers, API controllers, requests, and resources

This keeps controller logic thin and business rules out of views.

Local Installation

1. Clone and enter the project

git clone <your-repo-url> perfume-vault
cd perfume-vault

2. Install PHP dependencies

composer install

3. Install frontend dependencies

npm install

4. Create environment file

cp .env.example .env

5. Generate app key

php artisan key:generate

6. Configure the database

For the default local SQLite setup:

touch database/database.sqlite

Then confirm your .env contains something like:

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/project/database/database.sqlite

If you prefer MySQL or PostgreSQL, update the database settings in .env accordingly.

7. Run migrations and seed demo data

php artisan migrate:fresh --seed

Or use the dedicated demo seeder command:

php artisan vault:seed-demo --fresh --with-test-user

8. Link storage for uploads

php artisan storage:link

9. Start the application

For a full local development loop:

composer run dev

That starts:

• Laravel dev server
• queue listener
• log tailing
• Vite dev server

If you want a simpler setup:

php artisan serve
npm run dev

Demo Login

The demo seeder creates this account:

Email: collector@vault.test
Password: password

Demo Seeding

Perfume Vault includes a dedicated demo seeding command:

php artisan vault:seed-demo

Useful options:

php artisan vault:seed-demo --fresh
php artisan vault:seed-demo --with-test-user
php artisan vault:seed-demo --fresh --with-test-user

Seeder files:

• database/seeders/DatabaseSeeder.php
• database/seeders/DemoSeeder.php

Running Tests

Run the full test suite:

php artisan test

Or directly with Pest:

./vendor/bin/pest

Run a specific test:

php artisan test --filter=PerfumeCollectionTest

Frontend Build

Development:

npm run dev

Production build:

npm run build

Important Routes

Web

• /
• /login
• /register
• /dashboard
• /collection
• /rack
• /wishlist
• /analytics
• /settings

API

Authenticated API endpoints are versioned under:

/api/v1/*

Available resources include:

• /api/v1/perfumes
• /api/v1/wishlist
• /api/v1/analytics

API authentication uses Laravel Sanctum.

Useful Commands

php artisan route:list
php artisan migrate:fresh --seed
php artisan vault:seed-demo --fresh --with-test-user
php artisan test
./vendor/bin/pint
npm run build

Code Quality Notes

• Strict typing is used throughout application code
• Business logic lives in services and actions
• Repository interfaces abstract persistence
• DTOs are used for application input/output boundaries
• Policies control ownership-sensitive access

Project Notes

• The UI has been customized away from default Jetstream styling
• The current local setup is optimized for a seeded demo workflow
• Demo content is factory-backed and safe to rebuild repeatedly
• The server can be switched to MySQL/PostgreSQL without restructuring the application

Recommended First Steps After Install

1. Run the demo seeder
2. Log in with the seeded collector account
3. Open /collection
4. Open /rack
5. Open /analytics
6. Add your own bottle and watch how the collection updates

License

This project is open-sourced under the MIT license.