Senior Python/Flask Developer

Senior Python/Flask Engineer – Urgent SaaS Architecture Upgrades & WhatsApp API Integration (Potential Long-Term Collaboration) Description: 1. Project Overview & Current Architecture We are looking for a highly skilled Senior Backend/Full-Stack Python Engineer with immediate availability to overhaul and optimize our multi-tenant appointment booking SaaS platform ("RispondiTu"), built specifically for hair salons and barbershops. The platform is live in a multi-tenant production environment hosted on Railway.  Our current architecture relies on a strict data fallback hierarchy: PostgreSQL (Primary DB) ➡️ Google Sheets ➡️ DEMO_SHOPS. The database layer is implemented using SQLModel / SQLAlchemy, and the local setup features a legacy directory named intentionally with a typo: ⁠postrgres/⁠ (which MUST be preserved in code references).  The app includes integrations with Google Calendar API (for operator schedules) and Meta Cloud API (for automated WhatsApp onboarding and conversational flows). The codebase is tightly managed via ⁠uv⁠ and strictly bound to an automated testing suite using Pytest.  Hard Deadline: June 28th, 2026. Long-Term Opportunity: If you deliver clean, well-tested code before the deadline, this will convert into an ongoing, high-paying retainer/collaboration role to continuously expand our SaaS platform. 2. Detailed Technical Requirements Task 1: Dynamic White-Label Landing Page (⁠shop_id⁠ Scoping) Currently, the system needs to dynamically serve customized booking pages for each individual salon based on multi-tenant tenant detection (⁠shop_id⁠).  Backend Updates: You must fetch tenant-specific records from the PostgreSQL database using ⁠db_service.py⁠ and feed them to the Jinja2 templates via Flask.  Dynamic Frontend Assets: The landing page must dynamically load: Salon Logo, Business Name, and Short Description. Custom Brand Colors (primary/secondary CSS variables) and Cover/Background images. Weekly Business Hours. Core Action Buttons: The page must cleanly display three distinct, responsive call-to-actions: 1. Book Appointment (triggers the booking workflow). 2. Manage My Bookings (allows users to view/edit existing slots). 3. Chat on WhatsApp (directly linked to the specific salon's business phone number). Task 2: Booking Flow UX Optimization (Asynchronous Calendar) The booking flow frontend needs significant optimization to prevent user drop-offs. Step 1 (Services): Maintain the existing system logic handling ⁠enable_multi_service⁠ and ⁠show_operator⁠ configuration constraints.  Step 2 (Asynchronous Calendar): Days on the UI calendar grid must be conditionally disabled or rendered non-clickable if they are completely sold out (no slots available). If a user clicks or hovers over a fully booked day, display a precise message: "Non ci sono disponibilità, siamo al completo". Crucial: The system must never block navigation or rendering of other days, weeks, or months, allowing the user to seamlessly look for openings further out. Step 3 (Immediate Slot Rendering): The moment a user clicks on an available date, the matching time slots for that specific day and selected service must instantly populate the screen asynchronously via a clean ⁠Fetch/AJAX⁠ call without reloading the entire page. Task 3: Bulletproof WhatsApp Interactive Reminders & Notifications We need to ensure highly reliable notification loops utilizing our current Meta Cloud API infrastructure.  B2B Alerts: Send an immediate backend alert notification (Push/Email/System webhook) to the salon owner as soon as a client finalizes a booking. B2C Interactive WhatsApp Workflows: Instantly trigger an automated WhatsApp confirmation message to the customer right after booking.  The message must dynamically contain appointment details (date, time, salon name). Interactive Quick Replies: The message must include Meta Quick Reply buttons or distinct interactive links enabling the customer to Reschedule or Cancel their appointment instantly from within WhatsApp. Webhook Handling: You will update our WhatsApp webhook blueprint (⁠blueprints/webhook.py⁠) to catch these button interaction payloads, process the cancellation or rescheduling request directly in PostgreSQL, and update the associated Google Calendar slot.  3. Mandatory Skills & Expertise Python 3.12+ & Flask: Master-level understanding of Flask blueprints, factory patterns, and request/session lifecycles.  Database & ORM: Advanced experience with PostgreSQL, SQLAlchemy, and SQLModel in multi-tenant configurations.  Meta Cloud API (WhatsApp Business API): Proven track record of handling Meta interactive templates, quick reply buttons, incoming webhook payloads, and token management.  Google APIs: Integration experience with Google Calendar and Google Sheets API fallback mechanisms.  Testing: Absolute commitment to Test-Driven Development (TDD). Every route and service modification must pass through ⁠./run_all_tests.sh⁠.  Modern Tooling & Devops: Experience with ⁠uv⁠ package management, Git/GitHub repository branching, and Git-triggered deployments on Railway.  4. Guidelines & Deliverables We run a very strict engineering environment. Our project contains precise markdown instructions that you must follow completely: ⁠AGENTS.md⁠ / ⁠GEMINI.md⁠: Contains our system architecture guidelines, strict decoupling parameters, and explicit folder structure requirements (e.g., maintaining the legacy ⁠postrgres/⁠ folder name).  Zero Breaking Changes: Code restructuring must never bypass our ⁠db_service.py⁠ data flow rules.  How to Apply: To filter out generic template proposals and automated bots, please answer the following screening questions in your cover letter: 1. What is the specific framework we use to test our code, and what script file executes it in our environment? 2. Explain your past experience handling interactive quick-reply buttons and return webhook logic with the Meta WhatsApp Cloud API. Full configuration logs, ⁠pyproject.toml⁠ dependencies, and complete architectural write-ups will be shared immediately via private chat with shortlisted candidates.