MABlytic：基于多臂老虎机的智能广告推荐系统

MABlytic is a full-stack Progressive Web Application (PWA) designed to demonstrate modern AdTech (Advertising Technology) complete tech stack. It evolves from rule-based preference matching to Multi-Armed Bandit (MAB) reinforcement learning algorithms (using Thompson Sampling) to achieve personalized ad delivery and real-time effect optimization. Key tech stack includes FastAPI (backend), PWA (frontend), Firebase Hosting, and Google Cloud Run. The project covers core AdTech links: user registration, interest modeling, ad serving, interaction tracking, effect analysis, and algorithm optimization, making it a valuable reference for developers in AdTech, recommendation systems, or full-stack development.

Project Background & Origin

• Original Author/Maintainer: Rajlohith
• Source Platform: GitHub
• Original Title: mablytic (formerly ADWise)
• Original Link: https://github.com/Rajlohith/mablytic
• Release Time: 2026-06-13

MABlytic aims to showcase a complete AdTech pipeline. Its core goal is to implement personalized ad delivery using machine learning algorithms based on user preferences and choices. The project adopts a phased evolution approach: Phase 2 uses rule-based preference matching, while Phase 3 plans to upgrade to MAB reinforcement learning algorithms. The project's value lies not only in its final recommendation function but also in demonstrating the entire AdTech process from user registration to algorithm optimization.

Technical Architecture Overview

The project uses a layered, front-end and back-end separated architecture for maintainability and scalability.

Backend Tech Stack

• FastAPI: Python framework with asynchronous processing and auto-generated API docs (based on Starlette and Pydantic).
• SQLAlchemy ORM: Version 2.0 for data persistence (SQLite for development, with path to PostgreSQL migration).
• Pydantic: Data validation and serialization for API safety.
• Password Security: SHA-256 hash storage (not plaintext).
• Push Notifications: pywebpush and py-vapid integration with Web Push API.

Frontend Tech Stack

• PWA: Pure JavaScript (ES2022) with Service Worker (offline cache, background updates), Web App Manifest (add to home screen), responsive design (HTML5/CSS3).

Deployment & Hosting

• Frontend: Firebase Hosting (global CDN, HTTPS).
• Backend: Google Cloud Run (serverless container deployment, auto-scaling).

Core Function Modules

User Registration & Authentication

• Multi-step registration (username, password, personal info: name, email, gender, age, interest preferences) for user profiling.
• Password policy: 6-8 characters (letters/digits only).
• Role separation: ordinary users vs admins (admin access to dashboard and global stats).
• Preference-based user grouping (interests like tech, games, fitness, etc.).

Ad Content Management

• A/B testing support (2 variants per ad for effect testing).
• Category tags for ad-user preference matching.

Recommendation Algorithms

• Phase 2: Rule-based matching (random selection from ads matching user interests).
• Phase3 (Planned): MAB with Thompson Sampling:
  • Each ad is an "arm"; clicks are positive rewards, no clicks are no reward.
  • Thompson Sampling uses Beta(α, β) distribution (α=clicks+1, β=unclicked shows+1) to balance exploration (try new ads) and exploitation (use best-performing ads).
  • Advanced: Per (ad ID, user preference) group Beta parameters for fine-grained personalization.

Interaction Tracking & Analysis

• Real-time event records (view/click) stored in interactions table.
• CTR (Click-Through Rate) calculation as core effect metric.
• Admin dashboard for global KPI, ad CTR trends, user activity analysis.

Data Storage & API Design

Data Storage

• Development DB: SQLite with 3 core tables:
  • users: User info (auth, profile, interests, role, creation time).
  • ads: Ad content (title, description, image URL, categories, A/B variant).
  • interactions: User-ad interactions (user ID, ad ID, type, timestamp).
• Phase3: BanditStats table for MAB parameters (α, β per ad-user group).
• Production Suggestion: Migrate to Firebase Firestore (NoSQL) or Cloud SQL PostgreSQL.

API Design

RESTful API modules (auto-generated Swagger docs via FastAPI):

• Auth: /auth/register, /auth/login, /auth/profile/{id}.
• User Management: /users/ (list/create), /users/{id} (query/delete).
• Ad Management: /ads/ (list/create), /ads/{id} (query/delete).
• Recommendation: /serve-ad/{user_id} (rule-based), /serve-ad-ml/{user_id} (MAB, phase3).
• Interaction: /interactions/ (record/query).
• Admin: /admin/dashboard-stats, /admin/analytics, /admin/users, /admin/ads.

Deployment & Operation

Local Development

• Backend: Install dependencies via pip, start with uvicorn.
• Frontend: Use Python's http.server for static files.
• Data: Run seed_data.py to initialize test data.

Cloud Deployment

• Firebase Hosting: Install firebase-tools CLI, login, initialize project, deploy (global CDN).
• Cloud Run: Create Dockerfile, deploy via gcloud run deploy, update frontend API config with Cloud Run URL.

CI/CD

GitHub Actions for auto-deployment: Push to main branch triggers Firebase Hosting update.

Technical Highlights & Limitations

Highlights

• Algorithm Evolution: Clear path from rule-based to MAB (Thompson Sampling) with educational value.
• Engineering Best Practices: FastAPI + PWA stack, complete PWA features (installable, offline, push).
• Deployment: Firebase + Cloud Run (serverless) with CI/CD.
• Product Design: A/B testing, user grouping, real-time analysis reflecting core AdTech considerations.

Limitations & Improvements

• Algorithm: Phase3 MAB not yet implemented.
• Security: SHA-256 hash is suboptimal (use bcrypt/Argon2 instead).
• Data: SQLite for dev only (need production DB migration).
• Privacy: Lack of GDPR/CCPR compliance (required for real deployment).
• Cold Start: No strategy for new users/ads (need initial exploration).

Improvement directions: Complete MAB implementation, upgrade password hash, migrate DB, add privacy compliance, design cold start strategy.

MABlytic is a well-structured, fully documented full-stack ad recommendation system project. It not only implements basic functions but also demonstrates the evolution from simple rule-based matching to machine learning algorithms, covering the entire modern web application tech stack. For developers interested in AdTech, recommendation systems, or full-stack development, MABlytic provides a valuable reference and learning resource.