HomeBook Documentation

Everything you need to test the platform in five minutes — and everything behind the scenes once you want to go deeper. HomeBook lets a family share its houses with relatives and trusted guests: hosts list properties, users request reservations, moderators validate accounts and expenses, admins run the site.

https://homebook.freeboxos.fr · UI languages: EN · FR · DE

Part 1 · Quick test — basic features

1.1Open the app

The site is a single-page application: everything happens on one page and the header adapts to your role. Visitors can browse everything; reserving requires an account.

• From any device — computer, phone or tablet: https://homebook.freeboxos.fr

1.2Browse & search

The Browse view lists every active property with photo, nightly price and badges for the property type and booking mode. The filter bar lets you combine:

• Search text — matches title, description and location.
• Property type — house, chalet, apartment…
• Guests — properties whose capacity covers your party.
• Price range — max nightly rate.
• Dates — only properties free for the whole period.

Click a card to open the property page: photo gallery, amenities, availability windows, already-booked dates (or co-occupants for shared stays) and the reservation panel.

1.3Test accounts

The database ships with demo accounts covering every role. Sign in with the username (not the e-mail):

1.4Create an account

Click Sign up. Registration asks for exactly the information the platform needs later — that is why the reservation form itself stays minimal:

• Username — 3–30 characters, must start with a letter (letters, digits, _, -). Availability is checked live.
• First & last name, e-mail (unique), phone (optional).
• Password — minimum 6 characters, stored salted & hashed.
• Preferred language — EN, FR or DE.

New accounts start awaiting validation: they can browse but cannot reserve until a moderator or admin validates them (see §2.6). Demo accounts are pre-validated, except cousin.

1.5Place a reservation

On a property page the booking panel only asks for what actually drives the booking:

1. Check-in / check-out dates — must fall inside one of the property's availability windows.
2. Party size — capped by the property's max guests; for shared stays it also sets your share of the cost.

A live price summary updates as you pick dates (seasonal rate and family discount included). Submitting creates a PENDING request that the host must approve — nothing is confirmed instantly, and your contact details are attached automatically from your profile.

1.6Validate it (host)

Sign in as family / owner123 and open the Host panel (building icon in the header). Each product lists its reservation requests:

• Approve — the dates are locked for everyone else and the request becomes APPROVED.
• Reject — the requester sees the status in My Trips and the dates stay free.

The guest contact shown to the host comes straight from the requester's profile — no retyping.

1.7My Trips & cancelling

The My Trips view (calendar icon) splits your reservations into upcoming and past, each with its status: PENDING awaiting the host, APPROVED confirmed, REJECTED refused by the host, CANCELLED withdrawn. You can cancel a pending or approved trip yourself; freed dates become bookable again.

1.8Language & theme

The header carries a language switcher (English, Français, Deutsch) — your choice is remembered per account — and a theme toggle for light/dark mode. Registered users get the UI in their preferred language automatically.

Part 2 · Advanced features — in depth

2.1Roles & permissions

Every API call re-checks permissions server-side; the UI simply hides what you cannot do. Four roles build on each other:

User groups (set at validation, on top of roles): FAMILY — relatives sharing the family houses, eligible for per-property family discounts and tracked as expense payers; GUEST — external renters at the standard seasonal rate.

2.2PRIVATE vs SHARED bookings

Each property is bookable in exactly one of two modes, shown as a badge everywhere:

• PRIVATE — exclusive use. One reservation owns the whole property; once approved, overlapping requests are impossible. Nightly price is the flat seasonal rate regardless of party size.
• SHARED — several parties can book the same dates. Capacity is shared per day (sum of party sizes ≤ max guests) and the daily cost is split prorata per person per day.

Worked example — apartment at 160/night, max 4 guests, party A (2 people) and party B (1 person) overlap for 3 nights:

occupants per day   = 2 + 1 = 3
party A per night   = 2/3 × 160 = 106.67
party B per night   = 1/3 × 160 = 53.33
party A total (3n)  = 320.00      party B total = 160.00

The property page shows the projected co-occupants and your computed share before you submit, so there are no surprises at approval time.

2.3Seasonal pricing & family discounts

Three price levers combine on every reservation:

• Base rate — the low-season nightly price.
• High-season rate — applied to any day inside a season range defined on the property (e.g. “Christmas holidays”, “Ski season”). Hosts create as many ranges as needed.
• Family discount % — per-property percentage off for FAMILY-group users, on top of the seasonal rate.

The effective nightly rate is snapshot onto the reservation when it is created — later price or season edits never change an existing booking. The PRIVATE total sums the daily effective rate over the stay; for SHARED stays the snapshot applies to your per-person share (§2.2).

2.4Availability & conflict rules

Hosts define availability windows — the only periods during which a property can be booked at all. On top of that:

• A stay must fit entirely inside one window (partial overlaps are refused).
• PRIVATE: the stay must not overlap any APPROVED reservation (“Those dates are already booked”).
• SHARED: each day's total occupancy (approved parties + yours) must stay ≤ max guests (“Those dates are already at capacity”).
• Start dates in the past are rejected; only hosts/admins see cancelled or rejected history.

Approving a pending reservation is the act that locks the dates — pending requests reserve nothing.

2.5Host panel

The Host panel (and the List a property button) is the host's workshop. Per property:

Property editor

Title, description, location, property type, booking mode (PRIVATE/SHARED), bedrooms/bathrooms/max guests, base & high-season rates, family discount %, amenity tags, active toggle.

Image manager

Upload photos (stored under /uploads), set captions and reorder them — the first image is the card cover. Images can be replaced or deleted without touching the listing text.

Availability manager

Create the windows during which booking is allowed (§2.4). Overlapping windows are merged visually on the property page.

Season manager

Define named high-season ranges (§2.3). Days outside every range use the base rate; ranges may span year boundaries (ski seasons do).

Reservation validation

Approve or reject incoming requests per property, with requester contact and party size at a glance.

2.6Moderation & expenses

Moderators (and admins) get two extra views in the header.

Validation queue

New sign-ups land here. Validating a user unlocks reservations; at the same time the moderator assigns the group — FAMILY or GUEST — which drives discounts and expense attribution. Try it live with cousin / cousin123.

Expenses & payments dashboard

Shared houses have shared bills. Expenses are attached to a property and typed:

• FIXED — recurring: taxes, electricity, gas, internet, subscriptions… with an optional billing period.
• PUNCTUAL — one-offs: maintenance, repairs, custom labels.

Each expense carries a due date and a status PENDING → PAID. When marking as paid you record which FAMILY member paid, when and how (cash, bank transfer, card, other). The dashboard aggregates this into a “who paid what, when” overview with pending totals — designed so reimbursement is a lookup, not an argument.

2.7Notifications

Important events fan out to configurable channels (e-mail addresses and WhatsApp numbers managed in the Admin console), and each channel can subscribe to specific event types. Event types: USER_SIGNUP, USER_VALIDATED, GUEST_INVITED, RESERVATION_REQUEST, RESERVATION_APPROVED, RESERVATION_REJECTED, BOOKING_ADDED, EXPENSE_ASSIGNED, EXPENSE_PAID, TEST. Every channel can be verified with a one-click test dispatch.

2.8Admin console

The shield icon opens the super-admin area:

• Stats overview — users, properties, reservations by status, revenue-relevant totals.
• Users — full table with role, group, validation state; edit any profile, change roles, deactivate or delete. User creation/editing uses the same encrypted PII pipeline as sign-up.
• Reservations — every reservation on the platform with host validation powers.
• Notification channels — add/remove e-mail and WhatsApp targets (§2.7).

2.9Preview as user (impersonation)

Admins can test every feature with real permissions — without juggling passwords. In the user menu (top right), pick “Preview as user” and choose an account; the app immediately behaves as that person: their role, their data, their limits.

• An amber banner “Previewing as …” appears above the header with an Exit preview button.
• The preview lives in a separate session cookie that is only honored while your admin session is valid — logging out or letting the session expire kills it everywhere.
• Other admin accounts can't be previewed; start/stop events are logged for audit.

2.10Security & privacy

• Passwords — salted scrypt hashes, constant-time comparison. Plaintext is never stored or logged.
• PII at rest — username, names, e-mail and phone are encrypted per-field with AES-256-GCM (random IV per field, auth-tag protected). Deterministic SHA-256 hashes beside the ciphertexts power login lookups and uniqueness without decryption.
• Sessions — database-backed tokens in httpOnly cookies (7-day expiry, SameSite=Lax, secure flag in production). Logout destroys the server-side session.
• Authorization — every endpoint re-derives role and ownership from the session; the frontend never decides permissions.
• Anonymous visitors — collect nothing; the reservation form only exists behind authentication.

Part 3 · Reference

3.1Troubleshooting & FAQ