Loyalty Points Manager

Scalable starter platform with:

• backend/: Python FastAPI + Pydantic + SQLAlchemy API.
• frontend/: Flutter app for mobile and web.

Core features included

• JWT auth (/auth/login, /auth/register)
• User profile (/users/me)
• Loyalty points flow based on purchase:
  • package
  • quantity
  • cost
  • frequency bonus (recent repeated purchases)
• Tier support in user profile (gold, platinum, black)
• Purchase transaction history
• Redemption partners listing
• Admin metrics dashboard endpoint
• Privacy policy and terms endpoints
• Tests with pytest and unittest

Backend setup

From project root:

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Initialize DB tables:

python -c "from app.db.init_db import init_db_sync; init_db_sync()"

Seed demo users + partners (admin + client):

python -c "from app.db.seed_demo import seed_demo_sync; seed_demo_sync()"

Demo credentials:

• Admin: admin@loyalty.com / Admin1234!
• Client: client@loyalty.com / Client1234!

Run API:

uvicorn app.main:app --reload

API base URL:

• http://localhost:8000/api/v1

Docs:

• http://localhost:8000/docs

Frontend setup

If Flutter scaffold does not exist yet:

flutter create frontend

Then:

cd frontend
flutter pub get
flutter run -d chrome
flutter run -d chrome -t lib/app_entry.dart

frontend/lib/main.dart is already wired to call backend endpoints.

Security and scalability notes

• Uses password hashing (bcrypt) and JWT access token auth.
• Data model is split into users, purchases, points ledger, partners, and redemptions.
• Points ledger is append-style transactions, making auditing easier.
• API is structured with routers/services to add future integrations (e.g., WhatsApp) later without breaking core domains.