vibecodeit

Build Calendly

KINDAreplaces $12/mosaves $144/yrback to the verdict

0%0 of 20 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

Build a single-owner Google Calendar booking page with conflict-aware confirmation.

estimated effort multi-daythe files for this build are in the project pack

RuntimePython 3.12+ and FlaskStorageSQLite through Python sqlite3InterfaceJinja HTML templates, CSS and vanilla JavaScriptVerificationPython unittest and browser acceptance fixturesFocused librariesgoogle-api-python-client, google-auth-httplib2, google-auth-oauthlib

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

  1. installPython is free; this local prototype requires no hosting subscription.

    Why The local backend, tests and storage use Python.

    Get it Install Python from python.org. Open a terminal in a new empty project folder. On Windows, use py -3 where this guide says python if python is not on PATH; on macOS/Linux use python3 if needed. Create .venv and activate it before installing packages. open ↗

    Verify python --version reports 3.12+ and python -c "import sqlite3" succeeds.

  2. installNo paid service required for this local step.

    Why You need to view the local interface and edit generated project files.

    Get it Use an installed Chrome, Firefox or Edge browser. Open the empty project folder in your editor; open the terminal there, not in this catalog repository.

    Verify You can create a text file in the project folder and open browser developer tools.

  3. have readyNo paid service required for this local step.

    Why This fixture makes the first end-to-end check reproducible.

    Get it Create synthetic sample data before implementation: A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records.

    Verify The fixture files and expected outcomes exist and can be inspected without a vendor account.

  4. decideNo paid service required for this local step.

    Why The full commercial product is larger than this guide.

    Get it The deliverable is a single-owner Google Calendar booking page with conflict-aware confirmation. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first.

    Verify You can name the primary workflow and the vendor features this version deliberately leaves out.

  5. API keyCheck current Google API quotas and any project billing requirements; this guide assumes no paid quota or production verification exemption.

    Why The booking page must read busy periods and create invited events.

    Get it Follow the official Python quickstart: create a Cloud project, enable Calendar API, configure consent and your test user, and create OAuth credentials. For this web app use a Web application client and register the exact local callback http://127.0.0.1:5000/oauth/callback; use the matching HTTPS callback when deploying. Save the client JSON outside static files. open ↗

    Verify The owner completes consent and the app can read the chosen calendar busy data; revoked consent produces reconnect guidance.

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- event_types(id,title,duration_minutes,buffer_minutes)
- availability(id,weekday,start_local,end_local,timezone)
- bookings(id,start_utc,end_utc,state,guest_email,cancel_token_hash,google_event_id)
- holds(id,start_utc,end_utc,expires_at)
- oauth credentials stored outside public files
- Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them.
- Acceptance fixture: A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

VariableNeededExampleWhere the value comes from
DATA_DIRrequired./data/calendlyA new private folder this application creates on first run; never serve it as static files.
SECRET_KEYsecretrequiredreplace-with-a-random-secretGenerate with python -c "import secrets; print(secrets.token_hex(32))" and save only in .env.
APP_MODErequiredindieUse indie for loopback-only personal work. Product mode must refuse to start until owner login and the deployment gates are configured.
SITE_URLrequiredhttp://127.0.0.1:5000The origin used for local forms and links; replace with the chosen HTTPS origin in product mode.
GOOGLE_CLIENT_FILEsecretrequired./secrets/google-client.jsonDownload the OAuth client JSON from Cloud console; never commit it.
GOOGLE_TOKEN_FILEsecretrequired./secrets/google-token.jsonCreated by the owner authorization flow; restrict file permissions and exclude from backups shared with others.
GOOGLE_CALENDAR_IDrequiredprimaryThe authenticated owner calendar id; choose a dedicated test calendar during development.

The build, in order

  1. Local foundation and data contract

    Create the runnable local foundation for a single-owner Google Calendar booking page with conflict-aware confirmation, including the real schema and acceptance fixture.

    1. Run the venv command first, then stop and activate it before running the remaining commands. Use your OS instructions: Windows .venv\Scripts\activate.bat in cmd, or .venv\Scripts\Activate.ps1 in PowerShell; macOS/Linux source .venv/bin/activate. Then install the listed packages. Create app.py exposing app, load .env with python-dotenv, and add a /healthz route. Freeze tested dependency versions to requirements.txt. Create .env manually from .env.example; replace SECRET_KEY before launch.

      Files app.pyrequirements.txt.env.example.gitignore

      terminal
      python -m venv .venv
python -m pip install Flask Flask-WTF python-dotenv waitress tzdata google-api-python-client google-auth-httplib2 google-auth-oauthlib
python -m pip freeze > requirements.txt
python -m flask --app app run --host 127.0.0.1

    2. For database-backed state create schema.sql and db.py using this model: event_types(id,title,duration_minutes,buffer_minutes); availability(id,weekday,start_local,end_local,timezone); bookings(id,start_utc,end_utc,state,guest_email,cancel_token_hash,google_event_id); holds(id,start_utc,end_utc,expires_at); oauth credentials stored outside public files. Add the auxiliary relationships explicitly used in later phases; use stable ids, foreign keys, parameterized values and transactions. For canonical files use atomic replacement and hashes instead. Implement python manage.py init and python manage.py seed to create only synthetic data: A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Re-running init must not erase data.

      Files schema.sqldb.pymanage.pyfixtures/README.md

      terminal
      python manage.py init
python manage.py seed

    3. Install Flask-WTF CSRF protection for forms and same-origin fetches, validate Host and Origin against SITE_URL, bound inputs and escape output. Deliberately public intake endpoints get bounded validation and rate limits; signed provider webhooks use signature checks instead of browser CSRF tokens. All other admin routes stay local until product authentication exists. When a later phase tests viewer/member permissions, implement the users, hashed passwords, expiring server sessions and role checks in this foundation first; product mode must never use a fabricated identity from request input. Add error, empty, keyboard-focus and retry states now.

      Files app.pytemplates/base.htmltest/test_foundation.py

    done when · tick each as it passes
    watch out
    • The Flask development server is for local development only. Loopback binding alone does not replace CSRF and origin validation.
    next phase

  2. Calendar connection before UI

    Calendar connection before UI for Calendly: Follow Google OAuth setup for one test owner, enable Calendar API and authorize only the scopes needed for free/busy and event management.

    1. Follow Google OAuth setup for one test owner, enable Calendar API and authorize only the scopes needed for free/busy and event management.

      Files features/calendar_connection_before_ui.pytemplates/calendar_connection_before_ui.html

    2. Store refresh credentials server-side and implement a free/busy probe with explicit reauthorization guidance.

      Files features/calendar_connection_before_ui.py

    3. Use A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Check: An occupied fixture interval is returned as unavailable. Then check: Revoking access prevents booking confirmation and shows a reconnect state. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_calendar_connection_before_ui.py

      terminal
      python -m unittest discover -s test
    done when · tick each as it passes
    watch out
    • A service account is not a drop-in substitute for a personal calendar OAuth consent flow.
    next phase

  3. Availability and atomic holds

    Availability and atomic holds for Calendly: Compute a fourteen-day window from weekly rules, timezone-aware instants, buffers and current external busy ranges.

    1. Compute a fourteen-day window from weekly rules, timezone-aware instants, buffers and current external busy ranges.

      Files features/availability_and_atomic_holds.pytemplates/availability_and_atomic_holds.html

    2. Create short-lived interval holds in a serialized transaction; recheck overlaps and external busy data immediately before attempting confirmation.

      Files features/availability_and_atomic_holds.py

    3. Use A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Check: Two concurrent guests for one slot produce one active hold. Then check: A slot inside the external busy period cannot be booked by direct POST. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_availability_and_atomic_holds.py

      terminal
      python -m unittest discover -s test
    done when · tick each as it passes
    watch out
    • Local locking cannot eliminate a race with a calendar edited elsewhere; surface that limitation.
    next phase

  4. Event and guest lifecycle

    Event and guest lifecycle for Calendly: Use a valid deterministic Google event id derived from the booking id, add the guest and use sendUpdates for Calendar invitations.

    1. Use a valid deterministic Google event id derived from the booking id, add the guest and use sendUpdates for Calendar invitations.

      Files features/event_and_guest_lifecycle.pytemplates/event_and_guest_lifecycle.html

    2. Handle cancel/reschedule with expiring hashed tokens; on ambiguous creation query the event id before any retry and expire unused holds.

      Files features/event_and_guest_lifecycle.py

    3. Use A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Check: The API timeout followed by reconciliation produces one confirmed event. Then check: An invalid cancel token cannot cancel a booking, and cancellation releases the slot. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_event_and_guest_lifecycle.py

      terminal
      python -m unittest discover -s test
    done when · tick each as it passes
    watch out
    • No separate SMTP, Meet promise, SMS, round-robin or Microsoft adapter is included in this one-calendar build.
    next phase

  5. Portable delivery and clean-start proof

    Finish the Calendly replacement with a documented first-run path and a recoverable export.

    1. Document prerequisites, every configuration variable, data locations and the three domain workflows: Calendar connection before UI; Availability and atomic holds; Event and guest lifecycle. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them.

      Files README.md.env.example

    2. Use sqlite3.Connection.backup for the database in DATA_DIR and pause writers while taking the matching attachment snapshot. Keep schema version, hashes and a manifest for calendly. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A thirty-minute event type, one external busy period, two simultaneous guest requests and a Google API timeout. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy.

      Files OPERATIONS.mdscripts/backup.py

    3. Use a new folder and only README instructions to reach the fixture outcome. Install from requirements.txt, initialize storage, run the tests and exercise the UI at 375px and 1280px; use keyboard-only controls and inspect browser errors. Record exactly what passed; do not mark unrun checks complete.

      Files README.mdverification.md

      terminal
      python -m pip install -r requirements.txt
python -m unittest discover -s test
    done when · tick each as it passes
    watch out
    • Export without an import or restore rehearsal is not verified portability.
what this build does not replace
after v1, if you want it

Need the files? The project pack on the verdict page hands your agent the whole brief · more scheduling.