Spaces:
Running
Running
| # Architecture | |
| ## Overview | |
| Meme Jockey is a two-part system: a **FastAPI** backend that does image/GIF | |
| processing + auth + storage, and a **React Native** mobile app. | |
| ``` | |
| ┌─────────────────────┐ HTTPS / JSON · form-encoded ┌──────────────────────────┐ | |
| │ Mobile app (RN) │ ───────────────────────────────────────▶ │ FastAPI backend │ | |
| │ Android (0.80) │ Bearer JWT on every protected call │ (Hugging Face Space, │ | |
| │ │ ◀─────────────────────────────────────── │ Docker, port 8000) │ | |
| └─────────────────────┘ └────────────┬─────────────┘ | |
| │ | |
| ┌───────────────────────┬──────────────┼───────────────┐ | |
| ▼ ▼ ▼ ▼ | |
| ┌────────────┐ ┌──────────────┐ ┌───────────┐ ┌────────────┐ | |
| │ PostgreSQL │ │ Object store │ │ OpenAI │ │ Giphy │ | |
| │ (Neon) │ │ (Backblaze │ │ (captions)│ │ (GIF search)│ | |
| │ users, │ │ B2 / MinIO) │ └───────────┘ └────────────┘ | |
| │ otps, │ │ uploads + │ | |
| │ media, │ │ generated │ | |
| │ subs │ │ memes │ | |
| └────────────┘ └──────────────┘ | |
| ``` | |
| ## Backend layout (`backend/`) | |
| | Path | Responsibility | | |
| |---|---| | |
| | `main.py` | App wiring, middleware, meme/media/profile/admin endpoints | | |
| | `routers/auth.py` | OTP, PIN, refresh, Google login, profile (`/auth/*`) | | |
| | `routers/subscriptions.py` | Razorpay order/verify/status, receipts, history, PDF, config-check (`/subscriptions/*`) | | |
| | `utils/receipt.py` | Renders a payment receipt as a PDF (Pillow-only) | | |
| | `auth/security.py` | JWT mint/verify, phone normalize, hashing, guest config | | |
| | `auth/deps.py` | `current_user_id` dependency (Bearer → user id) | | |
| | `auth/sms_provider.py`, `utils/sms_fast2sms.py` | OTP delivery (Fast2SMS, or log) | | |
| | `utils/ai_overlay.py` | OpenAI suggestions + Giphy/Tenor search | | |
| | `utils/storage_minio.py` | S3-compatible put/get/presign | | |
| | `db/postgres_client.py` | All DB access (asyncpg + SQLAlchemy), per-request session | | |
| | `db/database.py` | Engine/driver selection from env | | |
| | `db/models.py` | SQLAlchemy models (users, otps, media_assets, …) | | |
| | `db/init.sql` | Schema bootstrap (run in Neon SQL editor) | | |
| > `db/supabase_client.py` is legacy/unused — the app uses `postgres_client`. | |
| ## Data model (key tables) | |
| - **users** — `id`, `phone_e164` (unique key; Google users keyed `google:<sub>`), | |
| `name`, `email`, `avatar_url`, `pin_hash`, `is_active`, `is_guest`, | |
| `account_type`, and subscription fields: `subscription_plan` (default `free`), | |
| `subscription_status` (default `inactive`), `subscription_expires_at`. | |
| - **otps** — hashed OTPs with `expires_at` / `consumed`. | |
| - **media_assets** — `object_key`, `content_type`, `kind` (`upload` | `meme`), owner. | |
| - **memes** — links input→output assets + `format`; drives daily-quota counts. | |
| - **payments** — one row per successful Razorpay payment (`plan`, `amount` paise, | |
| `currency`, `status`, `method`, `razorpay_order_id`, `razorpay_payment_id`, | |
| `expires_at`). Powers the receipt PDF and transaction history. | |
| ## Request auth flow | |
| 1. App calls `/auth/request-otp` → `/auth/verify-otp` → gets `access` + `refresh`. | |
| 2. App stores tokens; an axios interceptor adds `Authorization: Bearer <access>`. | |
| 3. On `401`, the interceptor calls `/auth/refresh` once and retries; if that | |
| fails, the session-expired handler logs the user out. | |
| 4. Returning users can `/auth/set-pin` then `/auth/login-pin` to skip OTP. | |
| 5. Guests (`GUEST_MODE_ENABLED`) get a short-lived guest session and skip PIN. | |
| ## Meme generation flow | |
| 1. `POST /upload` (image) → stored in object storage + initial suggestions. | |
| 2. App opens the editor; user places GIF/image overlays. | |
| 3. `POST /compose/layout` with the JSON layout → server renders the meme, | |
| stores it (`kind=meme`), returns `object_key` + URL. | |
| 4. `GET /memes` lists creations; `GET /memes/{object_key}` serves them via a | |
| permanent cached proxy URL. | |
| ## Deployment | |
| - **Backend** → Hugging Face Space (Docker, `app_port: 8000`). Push to the Space | |
| repo to rebuild. Secrets/Variables set in Space settings. | |
| - **Database** → Neon (run `db/init.sql` once; re-run after schema changes — it's | |
| idempotent `add column if not exists`). | |
| - **Object storage** → Backblaze B2 (S3-compatible) with a bucket-scoped | |
| Read+Write app key. | |
| - See [DEPLOYMENT.md](../DEPLOYMENT.md) and [ACCOUNTS_AND_SERVICES.md](ACCOUNTS_AND_SERVICES.md). | |