Padel Flow

Project Name
PadelFlow

Team Members

Alfin
Hafiz

Problem Statement

Organizing Americano and Mexicano padel tournaments is manual and error-prone. Organizers must hand-schedule matches, track scores, and recalculate leaderboards themselves — a process that gets harder as player count grows, and worse in real time as rounds complete and rankings shift.
Proposed Solution

Main Idea: PadelFlow – an AI-powered padel tournament management platform powered by Google’s open-weights Gemma 4 26B on Model Garden.
Intended Users: Tournament organizers running Americano and Mexicano padel tournaments who need fast setup, fair scheduling, and live scorekeeping.
Core User Experience: Organizer inputs a prompt describing the tournament -> AI extracts tournament details and recommends a venue -> matches are auto-generated -> organizer manages the event live through a dashboard with live scoring and a live leaderboard.
Expected Outcome / Benefit: Instant tournament setup with zero manual scheduling, automated fair match rotation, and real-time leaderboard accuracy.
Gemma Integration
Gemma (gemma-4-26b-a4b-it-maas) is deployed on Google Cloud Vertex AI & Vertex AI Model Garden across 3 specialized agent nodes:

ai_tournament_generator (AI Tournament Generator): Parses natural language inputs, extracts tournament parameters, enforces mandatory information (player count, match type, venue), and runs a multi-turn challenge loop if mandatory info is missing.
ai_venue_finder (AI Venue Finder): Recommends padel venues with court capacity based on user location queries.
tournament_advisor_chat (Tournament Advisor Chat Agent): An expert conversational AI endpoint (/api/ai/chat) answering questions on Americano vs. Mexicano rules, rotation strategies, and player pairing advice.
Agentic Development Workflow
Antigravity Use

Full-Stack Architecture: Scaffolded and built the Python 3.12 FastAPI backend, ADK 2.x agent runners, A2A protocol routes, and Cloud Firestore storage layer.
Tournament Algorithms: Designed Americano pair-rotation matrix math and Mexicano dynamic rank-based scheduling logic in padel_logic.py.
UI Refactoring & Modern Aesthetic: Refactored the frontend into an editorial-grade sports-tech interface with dark/light themes, TV broadcast-style scoreboards, and responsive layout.
Multi-Turn AI Validation: Created a multi-turn challenge loop preventing hallucinated or generic venue names when prompt details are missing.
Skills and MCP Integration

google-agents-cli-workflow & google-agents-cli-adk-code: End-to-end ADK development lifecycle, agent/runner code patterns, and A2A endpoint definitions.
google-agents-cli-deploy: Cloud Run deployment automation and service management.
firebase-firestore: Integration of Cloud Firestore SDK for persistent tournament storage.
web_application_development: Design system tokens, dark/light theme CSS variables, typography, and accessibility best practices.
Development Impact
Achieved a 100% test pass rate (13/13 unit and integration tests), 100% multi-turn reliability preventing hallucinated venue suggestions, 100% score integrity via strict validation, and zero data loss through real-time Firestore persistence across container restarts.
Google Cloud Architecture

Client: Vanilla HTML5, CSS3 Custom Properties (Dark/Light themes with HSL tokens), Modern ES6+ JavaScript (app.js).
AI Backend: Python 3.12 + FastAPI + Google ADK 2.x + google-genai Python SDK calling gemma-4-26b-a4b-it-maas on Vertex AI.
Data Flow: User Prompt -> POST /api/ai/generate-tournament -> Gemma on Vertex AI -> Structured JSON (tournament details) -> padel_logic.py (pairing logic) -> Cloud Firestore Storage -> Dashboard (Schedule, Live Score, Leaderboard).
Functionality

Working Features: AI Tournament Generator, AI Venue Finder, Tournament Advisor Chat Agent, automatic Americano/Mexicano match generation, live match scoring with winner detection and match locking, live leaderboard, tournament dashboard, tournament progress tracking, automatic final standings and champion declaration.
Main User Flow: Organizer describes tournament in natural language -> AI populates tournament form and confirms venue -> matches generate automatically -> organizer tracks live scores per match -> leaderboard updates automatically -> tournament completes with final standings and champion.
Known Limitations: Requires active connection to Google Cloud Vertex AI services for AI prompt generation and venue discovery; requires modern browsers supporting ES6 Modules, Flexbox/Grid, and CSS Variables; total points per match (score_a + score_b) cannot exceed 21.
Project Links

Public repository: https://github.com/alfinwijaya/padel-flow
Deployed application: padel-flow-134929710348.us-central1.run.app (Google Cloud Run, us-central1)
Public YouTube demo: [Insert URL]
The demo must be public, no longer than three minutes, and show the main user flow.
Instructions to Run

uv tool install google-agents-cli
cd /home/devstar9594/padel-flow
agents-cli install

.env: GOOGLE_CLOUD_PROJECT=kodingdeepdive0826-9594, REGION=us-central1, GOOGLE_CLOUD_LOCATION=global

uv run python -m uvicorn app.fast_api_app:app –host 0.0.0.0 –port 8000 –reload # Runs on http://localhost:8000
uv run pytest tests/unit tests/integration
agents-cli deploy -d cloud_run –service-name padel-flow –region us-central1 –project kodingdeepdive0826-9594 –no-confirm-project