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.
- Who it is for
- Features
- Screenshots
- How it works
- Data model
- Tech stack
- Project structure
- Installation
- Running the app
- Testing
- Roadmap
- License
- 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.
- 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.
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.
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.
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.
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.
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.
| 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.
- 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_keyenforces no double booking). - Tests: Python unit and integration tests, plus Playwright end to end tests.
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.
Install with the bench CLI:
cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch main
bench install-app apna_slotBuild the frontend (the built assets are not committed):
yarn --cwd apps/apna_slot/frontend build- Public site root serves the marketplace at
/. - A venue page is at
/v/<slug>, for example/v/sunrise-sports-club. - The publisher area is at
/manageand needs a login.
To develop the frontend with hot reload:
cd apps/apna_slot
yarn devPython tests (unit and integration, 53 tests today):
bench --site apnaslot.localhost run-tests --app apna_slotEnd 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:e2eCI runs the same flow on every push.
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.
MIT