Aura

Warning

This repository is archived and no longer maintained. It is kept available for reference only. The code is provided as-is, issues and pull requests are disabled, and no further updates will be made.

AI-Driven Fragrance Imagery-to-Recommendation Platform

---

📖 Introduction

Aura is a sophisticated fragrance recommendation engine that bridges the gap between abstract olfactory descriptions and concrete product suggestions. By leveraging Vector Search (pgvector) and Large Language Models (LLMs), Aura interprets nuanced user queries primarily based on imagery and mood—such as "a fresh rainy morning in a pine forest"—and maps them to a curated database of fragrances.

Unlike traditional keyword-based search (e.g., "floral perfume"), Aura understands the vibe, atmosphere, and emotional context of a scent, providing highly relevant and serendipitous discoveries for users.

🏗 Architecture

The system is built as a modern distributed application. In production, a Global Traefik Gateway handles incoming traffic and SSL termination, routing requests to the internal application stack.

graph TD
    Client["User Client"] -->|HTTPS| Traefik["Traefik Gateway"]
    Traefik -->|Routing| Nginx["Internal Nginx"]
    Nginx -->|Static Files| Frontend["Frontend SPA (React)"]
    Nginx -->|API Requests| API["Backend API (FastAPI)"]
    
    subgraph Data Layer
        DB[("PostgreSQL + pgvector")]
        Redis[("Redis Cache/Queue")]
    end
    
    subgraph Compute
        API -->|Read/Write| DB
        API -->|Enqueue Jobs| Redis
        Worker["Celery Worker"] -->|Process Jobs| Redis
        Worker -->|Store Results| DB
    end
    
    subgraph AI Services
        Worker -->|Embeddings & Completion| LLM["OpenAI / External Models"]
    end

Loading

🛠 Tech Stack

Frontend

• Framework: React 19
• Build Tool: Vite
• Styling: Custom Design System (CSS3 Variables, Glassmorphism effects)
• Icons: Lucide React
• Routing: React Router

Backend

• Framework: FastAPI (High-performance Async Python)
• Database: PostgreSQL 16 with pgvector extension for semantic search
• ORM: SQLAlchemy 2.0 (Async) + Alembic for migrations
• Task Queue: Celery + Redis for handling long-running AI inference tasks
• AI Integration: OpenAI API / Custom embeddings

DevOps

• Containerization: Docker & Docker Compose
• Linting & Formatting: Black, Isort, ESLint

🚀 Deployment

For detailed instructions on deploying Aura securely to a production server (Linux + Docker Compose), please refer to the Deployment Guide.

Highlights:

• ✅ Global Gateway: Uses Traefik for auto-HTTPS and multi-project support.
• ✅ One-Command Bootstrap: ./scripts/bootstrap.sh
• ✅ Secure by Default: Strict database isolation & external secrets.
• ✅ Maintenance: Helpers for logs (./scripts/logs.sh) and updates (./scripts/deploy.sh).

🏃‍♂️ How to Run

There are two ways to run Aura: Production Mode (easiest, runs everything in Docker) and Development Mode (for editing code).

🐳 Option 1: Production Mode (Recommended)

Run the entire application (frontend, backend, db, redis) in containers behind the Traefik Gateway.

1. Initialize Gateway (First Time Only)

./scripts/install-global-gateway.sh

2. Start Services

./scripts/bootstrap.sh

3. Access Application

• 🌍 App URL: http://localhost (via Traefik)
• 🔌 API: http://localhost/v1
• 📘 API Docs: http://localhost/docs

Note: In this mode, the frontend is served on port 80, not 5173.

---

💻 Option 2: Development Mode

Run the database in Docker, but run frontend and backend locally for hot-reloading.

1. Start Database & Redis

docker compose -f docker-compose.prod.yml up -d db redis

2. Start Backend (Terminal 1)

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

3. Start Frontend (Terminal 2)

cd frontend
npm install
npm run dev

4. Access Development

• 🎨 Frontend: http://localhost:5173 (Hot Reload)
• 🔌 Backend: http://localhost:8000
• 📘 API Docs: http://localhost:8000/docs

---

🚀 Deployment Guide

For deploying to a remote server (e.g., EC2, DigitalOcean):

1. Prepare Server

# Clone repo
git clone https://github.com/your-repo/aura.git
cd aura

2. Configure Secrets

# Copy example to production env
cp backend/.env.example backend/.env

# EDIT THIS FILE! Set strong passwords and API keys
nano backend/.env

3. Launch

./scripts/bootstrap.sh

4. Verify Access http://<your-server-ip>

---

🛠 Common Commands

Restart Services

To restart all services (useful after config changes):

# Restart everything
docker compose -f docker-compose.prod.yml restart

# Restart specific service (e.g. api)
docker compose -f docker-compose.prod.yml restart api

If you changed environment variables (.env), valid restart requires:

docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

Stop Services

docker compose -f docker-compose.prod.yml down

View Logs

# View all logs
docker compose -f docker-compose.prod.yml logs -f

# View specific service logs
docker compose -f docker-compose.prod.yml logs -f api

---

Manual Production Build

If you prefer to build and run without Docker:

Frontend:

cd frontend
npm install
npm run build          # Creates optimized production build in dist/
npm run preview        # Preview production build locally

Backend:

cd backend

# Setup environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure for production
export ENV=prod
export DATABASE_URL=postgresql+asyncpg://user:pass@host/dbname
export REDIS_URL=redis://host:6379/0

# Run migrations
alembic upgrade head

# Start with production server (Gunicorn)
gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000

---

Troubleshooting

"command not found: python"

• Use python3 instead of python on macOS/Linux

"Docker daemon not running"

• Start Docker Desktop application
• Or use brew services start docker on macOS

"Python 3.14 compatibility issues"

• Downgrade to Python 3.10-3.13: brew install python@3.12
• Create venv with specific version: python3.12 -m venv venv

"Port already in use"

• Frontend (5173): lsof -ti:5173 | xargs kill -9
• Backend (8000): lsof -ti:8000 | xargs kill -9

Database migration fails

• Ensure PostgreSQL is running: docker compose ps
• Reset database: docker compose down -v && docker compose up -d db
• Run migrations: alembic upgrade head

📂 Project Structure

aura/
├── backend/                # FASTAPI Python Backend
│   ├── app/
│   │   ├── api/            # API Route definitions
│   │   ├── core/           # Config, Security, Celery Factory
│   │   ├── db/             # Database models & sessions
│   │   ├── models/         # Pydantic Schemas
│   │   └── services/       # Business Logic & AI integration
│   ├── migrations/         # Alembic migration scripts
│   ├── tests/              # Pytest suite
│   └── requirements.txt
├── frontend/               # React Frontend
│   ├── src/
│   │   ├── assets/         # Static assets
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Page views
│   │   └── hooks/          # Custom React hooks
│   └── package.json
└── docker-compose.yml      # Service orchestration

🧪 Testing

Backend

Runs pytest inside the docker container to ensure isolation.

docker compose exec api pytest

Frontend

Linting check:

cd frontend
npm run lint

📄 License

This project is licensed under the MIT License.