# Critterly

Imaginary creatures. Real fun.

OurApp is a playful web app for generating one-of-a-kind AI "critters." Pick an adjective, an animal, an action, and a location — OurApp combines them into a prompt and uses AI image generation to bring your creature to life, ready to save, favorite, remix, and share.

![OurApp dashboard](docs/dashboard-screenshot.png)

## Features

- **Critter creation** — combine an adjective, noun, verb, and location into a prompt and generate a unique AI image via Replicate (flux-schnell), with a playful animated loading screen while it's created
- **My Critters dashboard** — a searchable, sortable, filterable grid of everything you've created, with live stat tiles (total / favourites / archived), pagination, and quick status tabs
- **Critter detail popup** — click any critter for a card-style detail view with its recipe, a generated flavor description, the exact AI prompt used, real image metadata (resolution, file size, created date), and Download / Share / Create Similar actions
- **Favorites & archive** — toggle either from the dashboard grid, the detail popup, or the critter's own page, all kept in sync
- **Credits & payments** — new accounts start with credits; more are purchased through Paddle Checkout, applied automatically via a signed webhook
- **Accounts** — register, log in, log out, and reset a forgotten password, all with an emailed confirmation (PHPMailer + SMTP)
- **Guest marketing homepage** — a full-bleed hero, a "how it works" walkthrough, a recently-created carousel, and a call to action for signed-out visitors
- **Responsive, branded UI** — built with Tailwind CSS and a consistent playful visual language (Poppins, a warm gradient palette, Lucide icons) across every page

## Tech stack

| Layer | Technology |
|---|---|
| Language / runtime | PHP 8.5 |
| Database | SQLite (via PDO) |
| Frontend styling | Tailwind CSS v4 |
| Icons | [Lucide](https://lucide.dev) |
| Fonts | Poppins (Google Fonts) |
| AI image generation | [Replicate](https://replicate.com) — `black-forest-labs/flux-schnell` |
| Payments | [Paddle](https://www.paddle.com) Billing (Checkout + webhooks) |
| Email | [PHPMailer](https://github.com/PHPMailer/PHPMailer) over SMTP |
| Local development | [Local by Flywheel](https://localwp.com) (nginx + PHP-FPM) |

## Project structure

```
public/
├── index.php              Guest homepage / signed-in dashboard
├── login.php, register.php, logout.php
├── forgot-password.php, reset-password.php
├── create-critter.php     Critter creation form + AI generation
├── single-critter.php     Standalone critter page
├── processing.php         Credit purchase processing screen
├── receive-purchase.php   Paddle webhook handler
├── api/                   JSON endpoints (critter details, purchase status)
├── lib/                   Shared partials (header, footer, hero, mailer, PHPMailer, etc.)
├── media/                 Tailwind input/output CSS
├── assets/                Marketing images
└── critter-images/        Generated critter images
```

## Getting started

This project is built to run on [Local by Flywheel](https://localwp.com), using its bundled PHP and nginx.

1. Clone this repo into a Local site's `app/public` folder.
2. Install frontend dependencies and build the CSS:
   ```
   npm install
   npm run dev
   ```
3. Configure the following environment variables (set as `env[...]` entries in the site's PHP-FPM pool config):

   | Variable | Purpose |
   |---|---|
   | `REPLICATE_API_TOKEN` | Replicate API token for image generation |
   | `HOOK_SECRET` | Verifies incoming Paddle webhook signatures |
   | `TICKET_SECRET` | Signs short-lived tokens (checkout linking, password reset) |
   | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` | SMTP credentials for outgoing email |
   | `SMTP_FROM_EMAIL`, `SMTP_FROM_NAME` | Sender identity for outgoing email |

4. Start the site in Local and visit it in your browser.

<- AI Davidson CI v1.0.3 classification test -->