SellerDrafts is a fact-locked draft listing generator for Etsy, Shopify, and Amazon-style marketplaces. It creates a title, description, and tags only from product facts the user supplies. Every result remains a starting draft that requires human review.
The repository name remains ListingForge. The public product and all current user-facing copy use SellerDrafts.
The technical service is live at https://sellerdrafts.com, with database accounts, per-user authorization, PostgreSQL migrations, transactional quotas, Stripe subscription webhooks, abuse controls, legal pages, a public marketing home, a non-root container, CI, and automated tests. It remains an unreviewed commercial pilot: do not intentionally promote it or activate paid acquisition until the separate pilot gates in SHIP_CHECKLIST.md are completed. Changes on a feature branch are not live until reviewed, merged, and deployed.
The paid SellerDrafts v1 path is now the canonical main branch. An earlier local SQLite / guest-identity demo line is retained only in Git history and must not be restored. See the completed merge record.
The logged-out home is a conversion landing page (promise, how it works, trust, plan teaser). It does not invent testimonials, user counts, or marketplace-publish claims. Signed-in users still see plan/usage metrics and draft actions.
SellerDrafts never promises ranking, conversion, or sales. Its visible Pass/Review/Verify/Missing statuses are transparent heuristic checklist prompts only; legacy numeric fields remain internal for saved-record compatibility. The dated first-party sources and qualifications behind the small platform checklist are recorded in docs/PLATFORM_RULES.md; users must verify current category rules before publishing.
- Product facts such as materials, dimensions, origin, certifications, ratings, scarcity, and shipping claims must come from user input.
- An optional LLM is disabled by default. When enabled, it has per-user caps, a timeout, a token ceiling, and a kill switch. The model may select and order only opaque IDs for complete supplied phrases; deterministic code renders the draft, and invalid plans fall back to templates. Free-form model prose never reaches output.
- Every generation and export displays DRAFT — verify before publishing.
- Every listing read, update, delete, and export is filtered by
user_idon the server. - Production refuses SQLite, insecure session configuration, documented default secrets, and localhost public URLs.
- Paid entitlements fail closed: unknown Price IDs, unpaid Checkout, and any subscription status other than
active/trialingkeep Free limits.
All periods use UTC. These values come from core/plans.py, the single source of truth used by UI and enforcement.
| Plan | Per day | Per month | Bulk rows/job | LLM attempts/day |
|---|---|---|---|---|
| Free | 8 | 40 | 5 | 4 |
| Starter | 50 | 1,000 | 25 | 25 |
| Pro | 250 | 5,000 | 100 | 100 |
| Agency | 1,000 | 25,000 | 250 | 500 |
No plan is unlimited.
- Streamlit provides the authenticated product UI under
/app/. - FastAPI owns crawlable public pages, Google-backed production account creation, existing password-account login/logout, HttpOnly session cookies, health checks, and Stripe webhooks. Password registration remains available only in development and tests.
- nginx exposes both processes on one origin and proxies Streamlit WebSockets.
- SQLAlchemy and Alembic manage PostgreSQL. SQLite is allowed only with
ENV=developmentorENV=test. - Stripe-hosted Checkout and Customer Portal handle payment UI; verified, idempotent webhooks control entitlements.
nginx applies per-client request/connection limits using Railway's injected client IP plus a generous container-wide backstop on every public route. Authentication also has a tighter bounded per-source soft limit in FastAPI; add a shared edge/WAF limiter before horizontal scaling.
Minimum tables are users, listings, usage_events, and subscriptions; v1 also uses user_sessions and webhook_events. Optional first-touch UTM labels are stored on a newly created user and never overwrite an existing account.
FastAPI server-renders the public home, pricing, legal page, and three Etsy seller guides. /robots.txt allows public search crawlers and OAI-SearchBot while excluding the authenticated workspace; /sitemap.xml lists canonical public URLs only. Private Streamlit and authentication routes send or receive noindex directives. SellerDrafts does not use llms.txt or claim that indexing, ranking, or AI citation is guaranteed.
Submit https://sellerdrafts.com/sitemap.xml to Google Search Console and Bing Webmaster Tools after verifying the domain. Use each service's URL inspection tool to confirm the public HTML, canonical, and sitemap status.
Campaign links may include utm_source, utm_medium, utm_campaign, utm_content, and utm_term. A signed first-party cookie retains those labels for up to 30 days and attaches them only when a new account is created. It is not a TikTok or X advertising pixel. Aggregate outcomes can be inspected without account identifiers:
python -m scripts.acquisition_report --since 2026-08-27The report measures signups, users with at least one draft, and users who are currently active on a paid plan. It does not measure visits, Checkout starts, or completed Checkouts.
The intended customer channels are [email protected] and [email protected]. Before any public promotion, manually send and receive a test through each channel and confirm the published mailbox routing and reply process; do not treat aliases as working merely because they appear in copy.
Docker is the supported one-command local path:
docker compose up --buildOpen http://localhost:8080. This starts PostgreSQL, runs Alembic migrations, then starts FastAPI, Streamlit, and nginx. Stop with docker compose down; add -v only when you intentionally want to delete the local database volume.
For Python-only generator/test work, create a virtual environment, install the lock, and use the development SQLite fallback:
python -m venv .venv
.venv/bin/pip install -r requirements.txt
ENV=development .venv/bin/alembic upgrade head
ENV=test .venv/bin/pytestOn Windows, use .venv\Scripts\python.exe and .venv\Scripts\pip.exe.
The paid SellerDrafts path is already on main. Use test-mode Stripe first.
The numbered order in SHIP_CHECKLIST.md is authoritative
if anything here disagrees.
- Create a Railway project from the repository. Railway will use
railway.tomland the rootDockerfile. Expose the app only through Railway HTTP Public Networking; do not add a TCP Proxy or another direct public route to container port 8080. - Add a Railway PostgreSQL service and expose its
DATABASE_URLto the SellerDrafts service. - In Stripe test mode, create one Product per plan, each with one monthly recurring USD Price matching the displayed copy: Starter $12, Pro $29, and Agency $79. Copy the
price_...IDs (neverprod_...). Create the separate live Products/Prices later, at the live switch, only after the test-mode Checkout cycle passes. - Create a least-privilege Stripe restricted API key for the Checkout, Customer, Subscription, and Billing Portal operations used here. Start with
rk_test_.../sk_test_.... Do not put keys in Git. - Set the initial production variables from
.env.example:ENV=production(already the image default),DATABASE_URL, the Railway HTTPS origin asPUBLIC_BASE_URL, a 32+ characterSESSION_SECRET,SESSION_COOKIE_SECURE=true,PORT=8080, and the test-mode Stripe credentials. Billing buttons stay disabled until the signing secret is added. A container started without production variables fails closed instead of serving a local SQLite demo. - Deploy. Container startup runs
alembic upgrade head;/healthzbecomes healthy only after the migrated database is reachable. - Add the Railway custom domain, point DNS as Railway instructs, then set
PUBLIC_BASE_URL=https://YOUR_DOMAINand redeploy. - In Stripe test Workbench, add
https://YOUR_DOMAIN/webhooks/stripeand subscribe at leastcheckout.session.completed,checkout.session.async_payment_succeeded,customer.subscription.created,customer.subscription.updated, andcustomer.subscription.deleted. Copy itswhsec_...value toSTRIPE_WEBHOOK_SECRETand redeploy. Recommended extras:invoice.payment_failed,invoice.paid,checkout.session.async_payment_failed,checkout.session.expired. - Enable the Stripe Customer Portal (test mode) for subscription changes, cancellation, and payment-method management. Limit customers to one subscription as defense in depth; SellerDrafts also persists and reuses one open Checkout session per user.
- Review the operator identity, contact email, Ohio jurisdiction, Terms, Privacy Policy, and Acceptable Use Policy before each public legal revision.
- Run
ENV=production python -m scripts.launch_checkagainst the production variable set. Follow the printednext:line and the printedverify:sequence: signup → template draft → history, then test-mode Checkout → webhook → portal. A test-mode key is an expected blocker during verification and can never pass the public-traffic gate. Then switch Stripe variables to live (rk_live_..., liveprice_..., livewhsec_...), redeploy, and re-run launch_check until it printspublic-traffic gate: passand exits 0. - Require the GitHub Actions
testandcontainer-smokejobs on the default branch, then accept paid public traffic.
Do not enable Stripe automatic tax unless the operator has the registrations required for Stripe to calculate and collect tax. Use separate Stripe keys for test and live environments.
Copy .env.example only for local reference. Railway variables should be entered in its secret manager. DATABASE_URL accepts Railway's postgres:///postgresql:// forms and is normalized to psycopg 3.
Email verification is an intentionally disabled v1 stub (EMAIL_VERIFICATION_REQUIRED=false). Do not turn it on until an email delivery adapter is connected. Production therefore supports Google for new accounts and keeps password login only for existing accounts; development/test password signup remains available. Every new account records the current Terms version, and stale accounts must reaccept before using the workspace.
Do not set LISTINGFORGE_SKIP_AUTH, TRUEDRAFT_SKIP_AUTH, LISTINGFORGE_REQUIRE_AUTH, LISTINGFORGE_USER_ID, STRIPE_SUCCESS_URL, or STRIPE_CANCEL_URL. Those names belong to the abandoned local-demo path. Checkout and portal URLs are derived from PUBLIC_BASE_URL.
ruff check .
ruff format --check .
pytest
python -m core.migrate
python -m scripts.smoke
python -m scripts.launch_checkpython -m scripts.launch_check is read-only. In ENV=production it exits 1 unless every public-traffic gate passes. It prints the next operator action and never prints secrets. Add --strict to fail in non-production environments as well.
CI runs lint, migrations, the fact-lock/auth/usage/billing/CSV suite, an import smoke test, and a Docker/PostgreSQL edge smoke. The auth suite proves production password signup is blocked. The container smoke provisions an internal fixture, verifies that the signup surface matches the stack environment, exercises existing-account login/session/logout through nginx, upgrades a Streamlit WebSocket, and checks signed/idempotent webhook delivery.
The final repository security review and residual operator checks are recorded in docs/SECURITY_REVIEW.md. Vulnerabilities should be disclosed privately through SECURITY.md, not a public issue.
- Stripe signatures are verified before parsing event data.
- Processed event IDs are stored transactionally, so retries are idempotent.
- Checkout metadata and, when present, Checkout line-item Prices map a signed event to an immutable SellerDrafts user and a configured Price. The
planmetadata field is never trusted. Line items do not need to be expanded in the Stripe dashboard;metadata.price_idis a signed fallback. - One unexpired Checkout session is stored per user and plan. Repeated clicks reuse its URL; choosing another plan is blocked until that session completes or expires. Paid, failed, and expired Checkout events clear the pending session.
checkout.session.async_payment_succeededis handled the same as a paid completed Checkout so delayed payment methods can still grant entitlements.- Subscription changes derive plan from the current Stripe Price. Unknown Prices fail closed to Free even when Stripe status is
active. - Deleted, unpaid, incomplete, paused, past_due, or otherwise inactive subscriptions fail closed to Free limits. Past-due accounts must use the Customer Portal; a second Checkout session is blocked.
- Older out-of-order events cannot overwrite newer entitlement state.
- Unhandled event types are acknowledged and recorded so Stripe does not retry them, but they never change entitlements. Invoice paid/failed events are acknowledged and deferred to
customer.subscription.updated.
The integration pins Stripe API version 2026-07-29.dahlia and Stripe Python 15.4.0.
MIT. See LICENSE.