docs/ARCHITECTURE.md

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 and ACCOUNTS_AND_SERVICES.md.