Django Appointments Showcase

This repository shows how a mobile service business can handle appointments in Django. It is a sanitized copy, with private details removed for public sharing. The pages are server-rendered, which means Django builds each page before sending it to the browser.

What it demonstrates

• Set regular weekly hours, add one-off changes, close dates, and handle daylight saving time
• Guide customers through a step-by-step booking form, remember their progress, and check availability again before confirming
• Save each booking in a database transaction, so all changes succeed or none do, keep an unchanging snapshot of the chosen service details, and protect against duplicate appointments
• Calculate distance-based prices with optional Google Places and Routes integrations
• Check discount codes, queue email notifications, send follow-up reminders, and keep a clear record of photo consent
• Give the owner a restricted Django Admin area for copying availability and cancelling or rescheduling appointments
• Add privacy-focused response headers, rate limits, and focused Django tests

The customer-facing pages are intentionally in Dutch. This shows localization in a real feature rather than using placeholder text.

Public boundary

This repository contains one feature from a larger Django project, so you cannot run it as a complete website by itself. It includes the appointments app, database migrations, page templates, static files such as CSS and JavaScript, focused tests, and current documentation. You will need to provide the main project settings, URL configuration, site layout, deployment, authentication, and background-job scheduling.

The Django project you add it to must provide:

• the service models and price formatting under apps.showcase_site.diensten;
• the announcement and discount-code models and lookup helpers under apps.showcase_site.acties and apps.showcase_site.kortingscodes;
• a restricted showcase_admin_site and a reusable admin rule, called a mixin, that only allows the owner access;
• Django sessions, email delivery (this example uses Django Post Office), static files, templates, and the URL names used by the views;
• Europe/Brussels as the project timezone, or an intentional adaptation of the scheduling and locale assumptions.

These requirements are listed openly because the feature still follows the structure of the original project. This avoids giving the impression that it is a standalone system.

Integration outline

1. Copy the root appointments/ package into your Django project. Then add appointments.AppointmentsConfig to INSTALLED_APPS.
2. Add or adapt the project parts listed above.
3. Use examples/host_integration/urls.py in your site's URL configuration as a reference. The accompanying integration notes explain what the main project needs and which order to work in.
4. Add the settings documented in docs/tech-backend-web-api.md through your project's usual settings. The safe settings_example.py gives you a starting point you can copy. Keep the Google credentials used by the browser separate from those used by the server.
5. Run migrations, collect static files, and configure the email queue and send_appointment_followups schedule if you enable those integrations.

Documentation

• Feature overview
• Data model
• Services and selectors
• Backend and integration design
• Product behavior
• Security and design decisions
• Locale behavior
• API boundary
• Focused test coverage

Reference frontend

The app includes a cleaned-up example site layout in showcase_site/base.html, along with a header, footer, theme switcher, and a stylesheet that adapts to different screen sizes. The appointment CSS matches the Seb appointment implementation, including its light and dark theme colours. You can replace this example layout while keeping the booking templates and their own static files.

Verification

After adding the feature to a compatible Django project, you can run:

DJANGO_SETTINGS_MODULE=config.settings.local uv run python manage.py test tests
uv run ruff check appointments tests
node --check appointments/static/showcase_site/appointments/js/google-places.js

You cannot run these tests from this repository alone. They rely on the project parts and Django configuration listed above, which are intentionally not included.

Security and privacy

Never commit live API keys or customer data. Limit the browser Google key to the correct website and APIs. Keep the server key private and give it its own restrictions.

Protect the owner Admin with strong authentication, and delete stored data on the schedule set by the documented retention policy. Before using the feature in production, check that the rate limits and email processing suit your hosting environment.

License

Licensed under the MIT License.