PPC Companion — Free Amazon PPC Sampler (by ProjectAmazonPH)

A free, mobile-friendly taste of real Amazon PPC VA work — and the on-ramp to the full Project Amazon PH Academy.

v0.6.0 · Next.js 16 · React 19 · TypeScript 5 · Tailwind v4 · Prisma

---

Overview

PPC Companion is a free sampler built by ProjectAmazonPH for aspiring Filipino Virtual Assistants. It lets a prospective student try a safe, realistic Amazon PPC task — understand the work an Amazon PPC specialist actually does — and then continue into the appropriate Project Amazon PH Academy course for full training.

The app also preserves the original full training platform (structured curriculum, auto-graded exercises, quizzes, PPC tools, and a capstone project) as the underlying content source that feeds the Academy. New visitors meet the sampler first; the complete curriculum lives in the Academy.

---

Features

Positioning: PPC Companion is the free public sampler and companion to the Project Amazon PH Academy — not a standalone competing course. The full curriculum and certification live in the Academy.

Area	Capabilities
Free Sampler	4-step public flow (See the Work → Check the Listing → Make One Safe PPC Decision → See the Career Path) with a retail-readiness scorecard and search-term triage exercise — no Amazon account or prior experience needed
Academy Handoff	Measurable CTA redirect (/sampler → Academy comparison) with campaign attribution (source=ppc-companion, medium=sampler, campaign=va-ppc-starter)
Curriculum	4 phases · 10 modules · structured learning path · 1,779 lines of course data (source content for the Academy)
Exercises	Auto-graded interactive exercises with real PPC scenarios
Quizzes	Checkpoint quizzes per phase with instant scoring
Dashboard	Student progress tracking, module completion, score overview
Admin Panel	Stats dashboard, user management, cohort oversight
Notification Center	In-app notifications with filters, mark-read, delete
Cohorts	Class management with student grouping
Capstone	Multi-week capstone project with milestone tracking
PPC Tools	Campaign Builder, Search Term Analyzer, Metrics Calculator
Downloads	Cheat sheets, templates (keyword research, campaign blueprint, reports)
Audit Trail	Full activity log for instructor monitoring
Profiles	Student + instructor profiles with activity timeline
Auth	bcrypt hashing · JWT tokens · role-based access (student/instructor/admin)
PWA	Standalone manifest · apple-web-app capable

---

Curriculum — 4 Phases (source content for the Project Amazon PH Academy)

Phase	Focus	Modules
🟦 1 — Foundations	How Amazon works, PPC metrics, ACoS, TACoS	3
🟥 2 — Amazon Ads Deep Dive	Ad types, match types, bidding strategies, negatives	3
🟩 3 — Advanced Optimization	Keyword research, campaign structure, data-driven optimization	3
🟪 4 — Portfolio & Client Management	Reporting, client communication, capstone project	2

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
UI	React 19 + shadcn/ui (Radix primitives), migrating to custom "Field Manual" design system
Styling	Tailwind CSS v4 + Geist font
Language	TypeScript 5 (strict mode)
Database	PostgreSQL via Prisma ORM
Auth	bcryptjs + JWT
State	Zustand (persisted localStorage)
Charts	Recharts
Animations	Framer Motion
Rate Limiting	In-memory middleware + node:sqlite-backed limiter
Runtime	Node.js 22+ / Bun 1.3+

---

Quick Start

# Install dependencies
bun install

# Set up env
cp .env.example .env
# Edit .env with your JWT_SECRET and DATABASE_URL

# Start PostgreSQL and run migrations
docker compose up -d db
npx prisma migrate dev
# (keep both schemas in sync manually — there is no generation step between them)

# Generate Prisma client + push schema
bun run db:generate
bun run db:push
# Bootstrap admin account
ADMIN_PASSWORD=your-secret bun run db:seed-students

# Run dev server
bun run dev

Open http://localhost:3000

---

Project Structure

├── src/
│   ├── app/
│   │   ├── (app)/              # Authenticated route group (per-feature page.tsx → section components)
│   │   ├── api/                # REST endpoints (auth, students, cohorts, sampler, etc.)
│   │   ├── globals.css         # Tailwind + design system
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Public landing / entry
│   ├── components/
│   │   ├── layout/            # App shell, sidebar
│   │   ├── sections/          # Feature sections (dashboard, admin, etc.)
│   │   ├── shared/            # Shared UI components
│   │   └── ui/                # shadcn/ui primitives (+ Field Manual custom components)
│   ├── hooks/                 # Custom hooks (use-mobile, use-toast)
│   ├── lib/
│   │   ├── auth-server.ts     # JWT utilities (requireAuth, requireRole)
│   │   ├── course-data.ts     # Full curriculum content
│   │   ├── db.ts              # Prisma client singleton
│   │   ├── db-queries/        # Database query helpers
│   │   ├── design-tokens.ts   # Design system tokens
│   │   ├── env-validate.ts    # Startup env validation
│   │   ├── rate-limit.ts      # Persistent SQLite rate limiter
│   │   ├── store.ts           # Zustand state management
│   │   └── utils.ts           # Misc utilities
│   ├── middleware.ts          # JWT auth + CSRF + rate limiting
│   └── styles/                # Design system CSS
├── prisma/
│   ├── schema.prisma          # PostgreSQL (prod) schema — source of truth
│   └── migrations/            # Database migrations
├── public/downloads/          # Cheat sheets, templates, PDFs
├── scripts/                   # Seed scripts
├── stitch-designs/            # UI design references
└── .env.example               # Environment template

---

API Endpoints

Endpoint	Method	Auth	Description
/api/auth/login	POST	Public	Login
/api/auth/signup	POST	Public	Register
/api/auth/csrf	GET	Public	CSRF token
/api/auth/me	GET	JWT	Current user
/api/auth/change-password	POST	JWT	Password change
/api/students	GET	JWT	Student list
/api/students/[id]	GET/PUT	JWT	Student detail/update
/api/students/[id]/progress	GET	JWT	Student progress
/api/students/[id]/activity	GET	JWT	Student activity
/api/cohorts	GET/POST	JWT	Cohort management
/api/cohorts/[id]	GET/PUT/DELETE	JWT	Cohort detail
/api/progress	GET	JWT	Progress overview
/api/curriculum	GET	JWT	Curriculum content
/api/exercises	GET	JWT	Exercise list
/api/exercises/submissions	GET/POST	JWT	Exercise submissions
/api/exercises/submissions/[id]/grade	POST	JWT	Grade submission
/api/quizzes	GET	JWT	Quiz list
/api/quizzes/attempts	POST	JWT	Quiz attempts
/api/capstones	GET/POST	JWT	Capstone projects
/api/notifications	GET/POST/PUT/DELETE	JWT	Notifications
/api/audit	GET	Admin	Audit trail
/api/tags	GET	JWT	Tags
/api/admin/stats	GET	Admin	Admin dashboard stats
/api/sampler	GET	Public	PPC Companion → Project Amazon PH Academy starter sampler funnel
/api/sampler/event	POST	Public	Sampler funnel event tracking
/api/health	GET	Public	Health check

---

Security

• Server-side JWT — All protected routes verify tokens via requireAuth()/requireRole()
• CSRF protection — Origin/Referer check on cookie-authenticated mutating requests; Bearer token auth bypasses
• Persistent rate limiting — SQLite-backed (Node 22 node:sqlite), survives restarts, in-memory fallback (kept for legacy compatibility)
• Env validation — Startup check for JWT_SECRET, DATABASE_URL
• Ownership enforcement — Users can only access their own data (admins/instructors bypass)
• Password hashing — bcryptjs

---

Production

# Build
bun run build

# Deploy to Vercel
vercel --prod

Requirements:

• JWT_SECRET — Strong random secret (64+ chars)
• DATABASE_URL — PostgreSQL connection string
• APP_URL — Deployed app URL (for CORS/CSRF)

---

License

Internal training program. Proprietary.