# Tech Stack — Noble Collectable

## Platform: WordPress + WooCommerce

### Why WordPress + WooCommerce?

**Portability & Hosting Freedom**
- Runs on any PHP-capable server (cPanel shared hosting, most VPS providers, any cloud host)
- Database agnostic (MySQL/MariaDB), file-based (no vendor lock-in)
- Client can export DB + `/wp-content/` and move to a different host at any time without rebuilding
- Avoids Shopify/Wix ecosystem lock-in

**Non-Technical Admin Interface**
- WordPress & WooCommerce admin panels are intentionally beginner-friendly
- Adding/editing products, managing inventory, processing orders, viewing analytics — all point-and-click
- Near-parity in usability with Shopify's admin dashboard
- Abundant tutorials and support resources for non-technical users

**Payment Gateway Flexibility**
- WooCommerce supports 50+ payment plugins: Stripe, PayPal, Square, Wise, custom APIs, etc.
- Client can choose any provider without platform friction
- No intermediary SaaS taking a cut if they don't want one

**Scalability & Extensibility**
- Huge plugin ecosystem (themes, payment gateways, SEO, backup, security)
- Can extend with custom post types, taxonomies, REST API endpoints
- Proven for stores from tiny hobby shops to mid-size retailers

### Why Not Alternatives?

| Choice | Pros | Cons | Verdict |
|--------|------|------|---------|
| **Shopify** | Mature, great admin UX | Monthly fee (29–299 USD), no self-hosting, payment lock-in, limited customization | ❌ Fails portability requirement |
| **Wix** | Drag-and-drop, very beginner-friendly | Platform lock-in, no export, expensive, limited integrations | ❌ Fails portability requirement |
| **Custom Next.js + headless CMS** | Full control, modern stack, best performance | High dev cost, complex admin panel, requires ongoing tech support, overkill for "non-techy admin" UX needs | ❌ Over-engineered for this need |
| **Static site + simple cart** | Cheap, portable, fast | Admin must edit code/files to add products, not suitable for non-technical owner | ❌ Fails admin UX requirement |

## Environment & Tools

### Local Development (This Session)

- **Docker:** Available (v29.6.2)
- **Node.js:** Available (v24.11.1)
- **PHP:** Not installed locally (will be in Docker)
- **WP-CLI:** Not installed (will be in Docker)

**Phase 2** will set up a local WordPress + WooCommerce Docker container for theme development and testing before deploying to cPanel.

### Production Hosting Assumptions

- **cPanel** shared hosting (client's current or preferred provider)
- PHP 8.0+ (most modern cPanel hosts offer this)
- MySQL/MariaDB 5.7+ (bundled with cPanel)
- 500 MB–2 GB storage (depending on product count and image library)
- Regular backups (client responsible, or via cPanel's backup tools)

### Deployment

1. **Initial setup:** One-click WordPress installer (available on most cPanel hosts) or manual FTP + database creation
2. **Theme & plugins:** WP child theme (custom HTML/CSS/JS) + WooCommerce + Polylang (FR/EN) + payment gateway plugins
3. **Migration:** Database export, `/wp-content/` folder copy, redeploy to new host (standard WordPress migration)

## Tech Decisions

### Bilingual Support

- **Plugin:** [Polylang](https://polylang.pro/) (free version, or Pro for more features)
- Why: WooCommerce-compatible, easy admin, no coding required for content translation
- Alternative considered: WPML (more features, but heavier and more expensive)

### Payments

- **No single choice yet** — Phase 3 will evaluate:
  - Stripe (popular, developer-friendly, 2.9% + $0.30/transaction)
  - PayPal (trusted, higher fees, 3.49% + $0.49)
  - Square (hybrid online/in-person, good for physical card sales events)
  - Wise (international transfers for EU shipping)
- Client will decide based on target audience and settlement preferences

### CDN & Performance

- Image optimization via WP plugins (Smush, Imagify) or child theme lazy-loading
- Optional: Cloudflare free tier for caching and DDoS protection (client adds DNS records)

### Security

- Regular WordPress core updates (automatic)
- Plugin updates (auto or manual, configurable)
- SSL certificate (free via Let's Encrypt on most cPanel hosts)
- Backup strategy (Phase 3 details)

## Development Workflow (Future Phases)

1. **Local:** Docker WordPress instance on developer machine
2. **Theme development:** Custom PHP/HTML/CSS in a WP child theme
3. **Testing:** Preview on local Docker, verify WooCommerce functionality
4. **Staging:** Optional: deploy to a staging subdomain on cPanel host before go-live
5. **Production:** FTP deploy or git-based (via GitHub Actions or manual sync)
6. **Maintenance:** Client admin in WordPress backend; developer handles updates/theme tweaks

## No Custom API/Frontend-as-a-Service

The store will be server-rendered WordPress (traditional PHP templates), **not** a decoupled headless setup. This keeps hosting simple (any PHP host works) and admin support straightforward (standard WordPress knowledge).

---

**Next Phase:** See [`ROADMAP.md`](./ROADMAP.md) for Docker environment setup and theme scaffolding.