| --- |
| title: Etsy Listing Optimizer |
| emoji: 🏷️ |
| colorFrom: yellow |
| colorTo: pink |
| sdk: gradio |
| sdk_version: 5.12.0 |
| app_file: server.py |
| pinned: false |
| license: mit |
| --- |
| |
| # Etsy Listing Optimizer |
|
|
| A micro-SaaS tool that generates SEO-optimized Etsy listing titles, tags, and |
| descriptions from a plain-language product description — with every AI |
| output programmatically validated (character limits, exact tag count, zero |
| duplicate words, no truncation) before it's ever shown to a user. |
|
|
| Built on an entirely free tier: Gradio + FastAPI on Hugging Face Spaces, |
| Supabase for auth/database, Groq (with Gemini fallback) for AI generation, |
| Stripe for billing. |
|
|
| **New here? Read `DEPLOY.md` first** — it's the step-by-step guide to |
| getting every account/API key and going live. This README is the map of |
| what's in the codebase. |
|
|
| ## Quickstart (local, no API keys needed) |
|
|
| The app runs in **demo mode** — in-memory storage, a deterministic mock AI |
| provider — whenever real credentials aren't configured, so you can try the |
| whole flow before signing up for anything. |
|
|
| ```bash |
| pip install -r requirements.txt |
| uvicorn app.main:app --reload --port 7860 |
| ``` |
|
|
| Open http://localhost:7860 — sign up with any email/password (10+ chars, |
| letters + numbers), generate a listing, poke around the tabs. Data resets |
| every time you restart the process. |
|
|
| To go live with real accounts/AI/payments, follow `DEPLOY.md`. |
|
|
| ## Project structure |
|
|
| ``` |
| server.py HF Spaces (Gradio SDK) entry point - runs the app on port 7860 |
| app/ |
| main.py FastAPI app: wires up all routers + mounts Gradio UI |
| ui.py Gradio Blocks UI (calls the FastAPI routes in-process) |
| config.py Tier/pricing definitions, feature flags, demo-mode detection |
| security.py Input sanitization / prompt-injection hygiene |
| |
| llm/ |
| prompts.py System prompt + few-shot examples (edit wording here) |
| provider.py Groq / Gemini / Mock provider abstraction + fallback |
| validation.py Programmatic validation of generated output |
| generator.py Orchestrates generate -> validate -> retry -> critic pass |
| |
| auth/ |
| service.py Supabase Auth wrapper + in-memory demo auth |
| deps.py FastAPI dependency: resolve current user from Bearer token |
| |
| db/ |
| store.py Supabase-backed store + in-memory demo store (same interface) |
| |
| payments/ |
| stripe_service.py Checkout session creation + webhook verification/handling |
| |
| routes/ |
| auth_routes.py /auth/signup, /auth/login, /auth/logout, /auth/password-reset |
| generate.py /generate — the core feature, tier/quota-gated |
| brand_voice.py /brand-voice CRUD |
| history.py /history, /history/export.csv |
| account.py /account/export, /account/delete (GDPR) |
| payments.py /billing/checkout/{tier}, /billing/webhook |
| bulk.py /bulk/generate (Business tier, CSV upload) |
| |
| legal/ |
| pages.py /legal/privacy, /legal/terms, /legal/refunds (draft text) |
| |
| middleware/ |
| rate_limit.py Per-IP (auth) and per-account (/generate) rate limits |
| |
| tests/ |
| test_validation.py Unit tests for the validation logic (run: pytest tests/ -q) |
| |
| supabase_schema.sql Run this in the Supabase SQL editor - tables + RLS policies |
| requirements.txt Pinned dependency versions |
| .env.example Every environment variable, with a comment on where to get it |
| DEPLOY.md Step-by-step deployment + API key walkthrough |
| ``` |
|
|
| ## How generation is kept honest |
|
|
| `/generate` never trusts the model's output at face value: |
|
|
| 1. `llm/generator.py` calls the LLM (Groq, falling back to Gemini on a 429). |
| 2. `llm/validation.py` checks, in code: exact tag count (13), character |
| limits (140 for titles, 20 for tags), no duplicate words across |
| tags/title, no mid-word/mid-sentence truncation, and the API's own |
| `finish_reason` isn't `"length"` (which would mean the response was cut |
| off by the token limit). |
| 3. If anything fails, the generator re-prompts the model with the *specific* |
| violation, up to 2 retries. |
| 4. Once formally valid, a second cheap "critic" LLM call checks whether each |
| tag is actually relevant to the submitted product (catches hallucinated |
| tags) — if any are flagged, only those specific tags are regenerated, not |
| the whole listing. |
|
|
| All of this is exercised by `tests/test_validation.py` and was manually |
| regression-tested end-to-end (signup, generation, tier gating, quota |
| enforcement, rate limiting, GDPR export/delete, Stripe error handling) before |
| being handed off. |
|
|
| ## Tiers |
|
|
| Defined in one place, `app/config.py` — nowhere else in the codebase |
| hardcodes a limit or a price. See the table there (or the Account tab in the |
| UI) for the current Free/Starter/Pro/Business feature matrix. |
|
|
| ## Security & compliance notes |
|
|
| - Passwords never touch application code — Supabase Auth handles hashing |
| (bcrypt); the demo-mode fallback used when Supabase isn't configured hashes |
| with a salt purely as a sandbox safeguard and is explicitly **not** |
| production-grade (see the warning in `auth/service.py`). |
| - Row Level Security is enabled on every table in `supabase_schema.sql`. |
| - Every generation request is checked against the monthly quota **before** |
| calling the LLM, so rejected requests never burn API spend. |
| - Stripe webhooks are rejected outright if signature verification fails. |
| - `/account/delete` removes both the database rows and the underlying auth |
| user/session — a deleted account's token stops working immediately. |
| - See `DEPLOY.md` for the GDPR / legal-pages disclaimer: the shipped |
| Privacy Policy / Terms / Refund Policy are a starting checklist, not legal |
| advice — have them reviewed before real customers sign up. |
|
|
| ## Known v1 limitations (by design, per the "keep it simple" brief) |
|
|
| - Rate limiting is in-memory (`slowapi`) — fine for a single HF Space |
| instance, won't work correctly if you scale to multiple instances without |
| switching to a Redis-backed store. |
| - Bulk generation (`/bulk/generate`) processes rows synchronously with a |
| 25-row cap per request — adequate for a v1 CPU-tier deployment, not meant |
| for large batch jobs. |
| - Resend (transactional email) is stubbed, not wired up — Supabase's default |
| auth emails cover signup confirmation/password reset for free in the |
| meantime. |
|
|
