🌸 FloraFlow

A full e-commerce and back-office system for a flower distribution business, from storefront to purchasing to receipts.

Showcase repository. The full source is private. This repo contains the overview, architecture notes, screenshots/branding and a few small, generic front-end pieces so you can see how the project is built and what it does.

The idea

Small wholesale businesses usually juggle a storefront, a spreadsheet for inventory, a notebook for vendors and a calculator for margins. FloraFlow puts all of that in one multi-tenant platform: customers order online, staff run the shop from an admin panel, and the numbers reconcile themselves.

What it does

Storefront (bilingual EN/ES): catalog with categories and filters, product modals, cart drawer, Stripe Checkout, order history, reviews, loyalty rewards, coupons, and an AI chat bubble.

Admin operations

• Inventory & availability with low-stock alerts and daily email digests
• POS for walk-in sales, plus live sales dashboards streamed over Server-Sent Events
• Orders with printable tickets, delivery scheduling and pickup notifications with sound alerts
• Purchasing & receiving: vendors, inbound shipments, vendor spend tracking
• Margins: cost vs. price analysis per product
• Audit log with undo for risky changes
• Users, roles & security: admin/staff/customer roles, ban enforcement, 2FA-style security codes, login throttling
• Onboarding & demo mode that seeds sample data for new tenants
• Receipts generated and emailed, abandoned-cart and background jobs on a worker

Architecture

        Cloudflare Tunnel
              |
   +----------+-----------+
   |  Nginx  (React SPA)  |  proxies /api, /media, SSE
   +----------+-----------+
              |
   +----------+-----------+        +---------+
   |  FastAPI backend     |<------>|  Redis  |  SSE fan-out + job queue
   |  tenant middleware   |        +----+----+
   +----------+-----------+             |
              |                    +----+----+
   SQLite / Postgres 16            | Worker  |  emails, receipts, alerts
                                   +---------+

• Multi-tenancy: a tenant context is enforced on every read and write.
• Payments: Stripe Checkout + webhooks, with inventory released when a session expires.
• AI: local Ollama models for storefront copy translation and the chat assistant.
• Quality: pytest suites (auth, ban enforcement, Stripe inventory release, vendor spend, 2FA), Vitest component tests and Playwright end-to-end runs in Docker.

Stack

React · Vite · Tailwind · FastAPI · SQLAlchemy · SQLite/PostgreSQL · Redis · Nginx · Stripe · Ollama · Docker Compose · Playwright · Cloudflare Tunnel

What's in this repo

Path	What
docs/	logo and project structure overview
frontend/src/components/ui/	the small UI primitive set (button, card, badge, input, toast)
frontend/src/lib/phoneFormat.js (+ test)	phone number formatting helper