bench get-app https://github.com/bwhtech/apna_slot

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=bwhtech%2Fapna_slot)](https://frappegems.com/gems/apps/bwhtech/apna_slot)

ApnaSlot

Slot booking made simple. ApnaSlot is a Frappe app that lets venue owners publish their turfs, courts and halls online, and lets customers browse, pick a time slot and pay, all in one place.

A venue owner (called a publisher) sets up weekly hours and prices once. Customers find the venue, see live prices per slot, hold one or more slots and pay through a mock gateway. The booking confirms only after payment, and a slot can never be booked twice.

Table of Contents

• Who it is for
• Features
• Screenshots
  • For customers
  • For venue owners
• How it works
  • No double booking
  • Server side pricing
  • Ten minute hold
• Data model
• Tech stack
• Project structure
• Installation
• Running the app
• Testing
• Roadmap
• License

Who it is for

• Customers browse venues, check availability and book slots. No account is needed to book. They can create an account after paying if they want to.
• Publishers (venue owners) manage their venues, hours, prices and resources, and watch bookings and earnings from a dashboard.

Features

• Public marketplace to browse venues by city or name.
• Venue page with cover image, rules, gallery, multiple resources (for example Court A, Turf 1) and a live slot grid with prices.
• Multi slot cart. Pick several slots and pay once.
• Server side pricing with base price plus weekend and peak hour surcharges.
• Slot locking so the same slot can never be double booked.
• Ten minute hold on selected slots, freed automatically if payment does not complete.
• Mock payment gateway (built to be swapped for a real one later).
• Confirmation email to the customer and the publisher.
• Reviews and star ratings, allowed only after a confirmed booking.
• Publisher dashboard with today's bookings, weekly and monthly revenue, and a per venue breakdown.
• Publisher venue editor with tabs for details, resources, weekly hours, pricing rules, gallery and publish status.
• Role based access so a publisher only ever sees their own venues and bookings.

Screenshots

For customers

Marketplace. Customers land on the home page and browse published venues. They can search by name or filter by city.

Venue page. Each venue shows a cover, address, contact, rules and its resources. Pick a resource and a date to see the slots. Prices change for peak hours. Here the evening slots cost more than the daytime ones.

Selecting slots. Tapping slots adds them to a cart at the bottom of the page. The cart shows every slot, the total price and a book button.

Checkout. The customer reviews the slots and enters name, phone and an optional email. Email is only needed if they want an account later.

Payment. A mock gateway confirms the amount. A timer shows how long the slots stay held before they are released.

Confirmation. After paying, the customer sees the confirmed order and can leave a star rating and a comment.

For venue owners

My Venues. A publisher sees a list of their own venues with each venue's city, resource count and publish status.

Dashboard. Quick numbers at the top (today's bookings, this week's bookings, weekly and monthly revenue), an upcoming bookings list and a per venue breakdown.

Bookings. All bookings grouped by order, with filters for venue and status.

Venue editor. Six tabs to set up a venue: details, resources, availability, pricing, gallery and publish.

Weekly hours. On the availability tab the publisher sets open and close times and the slot length for each weekday, plus one off date exceptions.

How it works

No double booking

Every active booking (held or confirmed) writes a slot_key made of the resource, the date and the start time. This key has a unique index in the database. If two people try to hold the same slot at the same time, the second write fails and that request loses the race cleanly. When a booking is cancelled or expires, its key is rewritten so the slot is free again.

A multi slot order is all or nothing. If any one slot in the order is already taken, the whole order rolls back and no partial booking is left behind.

Server side pricing

The client never sends a price. The server computes it on every hold:

price(slot) = base_price + sum of matching surcharge rules

A rule matches on day type (all days, weekdays or weekends) and a time band. For example, base 500 rupees, a weekend rule of plus 200, and a peak rule of plus 300 for 6 pm to 10 pm makes a Saturday 7 pm slot cost 1000 rupees.

Ten minute hold

When slots are held, the order gets a ten minute expiry. A scheduled job runs every minute, finds holds that have passed their expiry, marks them expired, frees the slots and fails the pending payment. So abandoned checkouts never block a slot for long.

Data model

DocType	Purpose
Venue	A place with hours, prices, gallery and rules. Owned by a publisher.
Venue Resource	A bookable unit inside a venue (for example Court A, Turf 1).
Venue Weekly Availability	Open and close time and slot length per weekday (child table).
Venue Availability Exception	Date level override, either closed or special hours (child table).
Venue Pricing Rule	A surcharge for a day type and time band (child table).
Venue Gallery	Extra images for a venue (child table).
Booking Order	Groups one or more slots into one checkout and one payment.
Booking	One slot line inside an order. Holds the slot_key lock.
Payment Transaction	One payment per order. Mock now, real gateway later.
Venue Review	A star rating and comment, tied to one confirmed booking.

For the full schema, the locking mechanism and the pricing rules, see specs/00-architecture.md.

Tech stack

• Backend: Frappe Framework (Python). DocTypes, whitelisted APIs, permission hooks and a scheduled job.
• Frontend: One Vite plus Vue 3 single page app built with the frappe-ui component library and its design tokens.
• Database: MariaDB (a unique index on slot_key enforces no double booking).
• Tests: Python unit and integration tests, plus Playwright end to end tests.

Project structure

apna_slot/
  apna_slot/
    api/            Guest and publisher APIs (public.py, publisher.py)
    engine/         Pricing and slot generation (pricing.py, slots.py)
    doctype/        The ten DocTypes listed above
    permissions.py  Query and single doc permission rules
    tasks.py        Scheduled hold expiry job
    notifications.py Confirmation emails
    tests/          Python tests
  frontend/         Vite + Vue 3 + frappe-ui single page app
  e2e/              Playwright end to end tests
  specs/            Design specs, one per build phase
  PROGRESS.md       Phase by phase build status

The frontend serves two route groups. Public routes live under /v (browse, venue page, checkout, confirmation). Publisher routes live under /manage (venues, editor, bookings, dashboard) and need a Frappe login.

Installation

Install with the bench CLI:

cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch main
bench install-app apna_slot

Build the frontend (the built assets are not committed):

yarn --cwd apps/apna_slot/frontend build

Running the app

• Public site root serves the marketplace at /.
• A venue page is at /v/, for example /v/sunrise-sports-club.
• The publisher area is at /manage and needs a login.

To develop the frontend with hot reload:

cd apps/apna_slot
yarn dev

Testing

Python tests (unit and integration, 53 tests today):

bench --site apnaslot.localhost run-tests --app apna_slot

End to end tests (Playwright). First seed the demo data, then run:

bench --site apnaslot.localhost execute apna_slot.e2e_seed.setup_e2e_data
cd apps/apna_slot
npm install && npx playwright install chromium && npm run test:e2e

CI runs the same flow on every push.

Roadmap

The core booking product (phases 0 to 4) and the marketplace browse (phase 5.1) are done. Planned next steps, tracked in PROGRESS.md:

• Customer account area with a "My Bookings" view.
• More notification channels beyond email.
• A real payment gateway in place of the mock one.
• Customer self cancellation and refunds.
• Platform commission and monetization.
• Per resource custom schedules.
• Operational hardening.

License

MIT