• 🛍️ Personalized Feed - Discover products tailored to your interests
• 🔥 Trending Products - See what's popular in the community
• 🔍 Smart Search & Filters - Find products by category, price, rating
• 🛒 Persistent Cart - Cart saved across sessions
• 💳 Seamless Checkout - Multi-step checkout with simulated payments
• 📦 Order Tracking - Track order status from pending to delivered
• ⭐ Product Reviews - Rate and review purchased products

• 🏪 Instant Store Setup - Start selling in minutes
• 📤 Bulk Product Upload - Upload products via CSV
• 📊 Dashboard Analytics - Track sales, orders, and revenue
• 📋 Order Management - View and fulfill orders
• 🏷️ Inventory Control - Manage stock levels with low-stock alerts

hive/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── main.py         # FastAPI entry point
│   │   ├── config.py       # Configuration settings
│   │   ├── database.py     # Database connection
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── routers/        # API routes
│   │   ├── services/       # Business logic
│   │   ├── middleware/     # Auth middleware
│   │   └── utils/          # Utility functions
│   ├── alembic/            # Database migrations
│   ├── requirements.txt    # Python dependencies
│   └── Dockerfile
│
├── frontend/               # Next.js frontend
│   ├── app/
│   │   ├── (auth)/        # Auth pages (login, register)
│   │   ├── (buyer)/       # Buyer pages (home, cart, orders)
│   │   ├── (seller)/      # Seller pages (dashboard, products)
│   │   ├── layout.tsx     # Root layout
│   │   └── providers.tsx  # Context providers
│   ├── components/        # Reusable components
│   │   ├── ui/           # UI primitives (Button, Input, etc.)
│   │   └── ...           # Feature components
│   ├── lib/              # Utilities & API client
│   ├── store/            # Zustand stores
│   ├── package.json
│   └── Dockerfile
│
├── docker-compose.yml     # Docker orchestration
├── nginx.conf            # Nginx configuration
├── alembic.ini           # Alembic configuration
├── PRD.md                # Product Requirements Document
└── brand-guidelines.md   # Brand & design guidelines

• Node.js 18+ (for frontend)
• Python 3.11+ (for backend)
• Docker & Docker Compose (for containerized deployment)

1. Clone the repository

   git clone <repository-url>
   cd hive

2. Create environment files

   # Backend environment
   cp backend/.env.example backend/.env
   
   # Frontend environment
   cp frontend/.env.local.example frontend/.env.local

3. Configure environment variables (see Environment Variables)

4. Build and start services

   docker-compose up --build -d

5. Run database migrations

   docker-compose exec backend alembic upgrade head

6. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs
   • Nginx Proxy: http://localhost

1. Navigate to backend directory

   cd backend

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Create .env file with required variables

5. Run database migrations

   alembic upgrade head

6. Start the server

   uvicorn app.main:app --reload --port 8000

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Create .env.local file

   NEXT_PUBLIC_API_URL=http://localhost:8000

4. Start development server

   npm run dev

# Database
DATABASE_URL=sqlite:///./data/marketplace.db

# JWT Configuration
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_DAYS=7

# File Uploads
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=5242880  # 5MB

# Email (SMTP) - Required for production email notifications
# Leave SMTP_USER and SMTP_PASSWORD empty for development (emails logged to console)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_FROM=[email protected]

# CORS
CORS_ORIGINS=http://localhost:3000

Hive sends transactional emails for the following events:

Development Mode: If SMTP_USER and SMTP_PASSWORD are empty, emails are logged to the console instead of being sent. This is useful for local development.

Production Mode: Configure your SMTP provider:

• Gmail: Use an App Password (not your regular password). Enable 2FA and create an app password at https://myaccount.google.com/apppasswords
• SendGrid/Mailgun: Use their SMTP credentials
• Custom SMTP: Configure your mail server credentials

NEXT_PUBLIC_API_URL=http://localhost:8000

For detailed API documentation with request/response examples, visit /docs when the backend is running.

• users - Buyer and seller accounts
• products - Product listings
• orders - Order records
• order_items - Items within orders
• carts - Shopping carts
• cart_items - Items in carts
• reviews - Product reviews

Users ──┬── Products (seller_id)
        ├── Orders (buyer_id)
        ├── Carts (user_id)
        └── Reviews (user_id)

Products ──┬── CartItems (product_id)
           ├── OrderItems (product_id)
           └── Reviews (product_id)

Orders ── OrderItems (order_id)
Carts ── CartItems (cart_id)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild containers
docker-compose up --build -d

# Run backend migrations
docker-compose exec backend alembic upgrade head

# Access backend shell
docker-compose exec backend bash

# Access frontend shell
docker-compose exec frontend sh

Copyright©️ Codebasics Inc. All rights reserved.