# AffiliateHub

A production-oriented affiliate marketing platform: visitors browse products,
affiliates generate trackable links and earn commissions on conversions, and
admins run the whole operation from a dashboard.

Built on **Laravel 12 / PHP 8.4**, MySQL, Blade + Bootstrap 5.3, and Vite.

---

## Status

This repository is being built in phases (see [Roadmap](#roadmap) below).
**Currently delivered: Step 1 (database schema) and Step 1.5 (project
scaffolding — this delivery).**

That means the app will boot, migrate, and serve a placeholder homepage, but
none of the affiliate/admin features exist as code yet — those routes,
controllers, and views arrive in later steps.

---

## Requirements

- PHP 8.2+ (developed against 8.4)
- Composer 2.x
- Node.js 18+ and npm
- MySQL 8+ (or SQLite for quick local testing)

## Setup

```bash
# 1. Install PHP dependencies
composer install

# 2. Install JS dependencies
npm install

# 3. Environment
cp .env.example .env
php artisan key:generate

# 4. Database — edit .env with your MySQL credentials, or switch to SQLite:
#    DB_CONNECTION=sqlite  (and comment out/remove the other DB_* lines)
touch database/database.sqlite   # only if using sqlite

php artisan migrate

# 5. Build frontend assets
npm run dev     # local dev server with hot reload
# or
npm run build    # production build

# 6. Serve
php artisan serve
```

Visit `http://localhost:8000`.

### Deploying to shared hosting (Apache)

Point your document root at `public/`, not the project root. `public/.htaccess`
is already configured to rewrite all requests through `index.php`. After
uploading:

```bash
composer install --no-dev --optimize-autoloader
npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

---

## Tech stack

| Layer | Choice |
|---|---|
| Backend | Laravel 12, PHP 8.4, MVC |
| Auth | Laravel Breeze/Jetstream (Step 4) + Laravel Sanctum for API tokens |
| Database | MySQL 8+, 32 migrations already in `database/migrations/` |
| Frontend | Blade templates, Bootstrap 5.3, vanilla JS/AJAX, Vite build pipeline |
| Fonts / palette | Playfair Display (headings) + Poppins (body); green/blue/red palette — see `resources/sass/app.scss` |

## What's NOT in this repository (and why)

- **`vendor/`, `composer.lock`, `node_modules/`, `package-lock.json`** — these
  are generated by actually running `composer install` / `npm install`
  against live package registries. They aren't included because they were
  built without network access; run the install commands above to generate
  real, correct lock files rather than trusting fabricated ones.
- **Business logic** (models beyond the auth stub, controllers, policies,
  services, real views, seeded data) — arriving in the steps below, so the
  scaffold stays reviewable in digestible pieces instead of one enormous
  drop.

---

## Roadmap

- [x] **Step 1 — Database**: 32 migrations covering auth/roles, catalog,
      affiliate tracking (links/clicks/conversions/commissions), payouts,
      CMS, blog, support, and platform plumbing. See `docs/ER-DIAGRAM.md`.
- [x] **Step 1.5 — Project scaffolding**: this delivery — full Laravel 12
      root (`artisan`, `composer.json`, `package.json`, config/, bootstrap/,
      public/, routes/, a placeholder auth-ready `User` model, tests scaffold).
- [ ] **Step 2 — Eloquent Models**: all 32 tables, relationships, casts,
      query scopes, the real `User` model (roles, referral tree, cached
      balances).
- [ ] **Step 3 — Seeders & Factories**: realistic fake data for every table,
      demo admin + affiliate accounts.
- [ ] **Step 4 — Controllers, Middleware, Routes, Requests**: auth (Breeze),
      affiliate dashboard, admin panel, REST API, role middleware, form
      validation.
- [ ] **Step 5 — Notifications & Payments**: email/in-app notifications,
      withdrawal request flow, commission approval flow.
- [ ] **Step 6 — Console commands**: scheduled payout batches, sitemap
      generation, stale-cart/click cleanup.
- [ ] **Step 7 — Blade views, CSS, JS**: the actual frontend, admin UI,
      SEO markup (meta tags, schema, sitemap, breadcrumbs).
- [ ] **Step 8 — Testing & deployment**: feature/unit test coverage,
      production checklist.

See `docs/ER-DIAGRAM.md` and `docs/FOLDER-STRUCTURE.md` for the full schema
design and directory layout.
