System Requirements Document for barbershop-appointments

1. Introduction

This document specifies the system requirements for barbershop-appointments, a website for a barbershop where customers can book appointments online. The product intent is a first-party web presence for the shop that lets a customer browse the shop, choose a service and an available time slot, and submit a booking online — without calling or visiting — and lets the barbershop owner review the appointments that were booked online so the chair schedule stays accurate.

The audience is twofold: customers of the barbershop (18–45, mostly mobile, choosing a barber by vibe and by the cut) who want to grab a slot before it goes, and the barber / shop owner who runs the shop and needs to know who is coming and when. The site is delivered as a custom web application with application-owned identity, a shared backend, and durable appointment records.

2. System Overview

The current delivery is a single custom web application with a shared backend:

• An anonymous Landing page presents the barbershop and its online appointment booking.
• A customer establishes identity through Sign Up (self-service first-use enrollment) and returns through Login; the barber / shop owner also returns through Login.
• An authenticated customer selects a service and an available time slot and submits the booking on Book Appointment, then receives acceptance on Booking Confirmation.
• The barber / shop owner reviews the appointments booked online on Appointments.
• Submitted bookings are persisted as durable appointment records so they can be reviewed later.

Actors are the two accepted human personas — Customer and Barber / Shop Owner — plus the application backend as a non-persona system actor that persists appointment records and enforces access to protected pages.

Narrow exclusions: this document does not add payment processing, customer messaging or notifications, staff/barber roster management, inventory or product sales, loyalty programs, or multi-location support. Nothing in the source authorizes those capabilities, and they are not inferred here.

2a. Product Interpretation and Delivery Boundary

The barbershop's website is the shop's own first-party surface. The public entry (Landing) is anonymously reachable and explains the shop and its online booking. Because a customer must privately own and resume their own booking state, and because a submitted booking is a commitment bound to the correct customer and must remain visible to the shop owner, the application owns identity: a customer establishes it once through self-service enrollment on Sign Up, and both customers and the barber / shop owner return through Login. Protected state — the booking flow, the confirmation, and the owner's appointment list — is unavailable until identity is established.

Current horizon: the Landing page, self-service enrollment, returning verification, the booking flow, the booking confirmation, and the owner's appointment review, all backed by durable appointment records. No future-horizon capabilities are specified in the source; none are added here.

2b. Source Content Inventory

Not applicable — no reference directive with content_source authority was supplied.

2c. Page Content and Component Coverage

Landing

• Information / state: Anonymous public entry. Shop identity and the fact that appointments can be booked online; the shop's services and the invitation to book a cut. No protected state is shown.
• Primary action: Begin booking (routes an unauthenticated visitor toward identity establishment, then booking).
• Supporting actions: Navigate to Sign Up; navigate to Login.
• Domain entities: Shop, Service (name, duration, price), next available slot indicator.
• Component responsibilities: Hero with the oversized headline and primary booking call to action; a running ticker of service names and shop slogans; a stacked, full-width service list with hairline ink rules where each row expands in place to reveal duration and price; a footer band.
• States: Loading — static content, no data-dependent blocking state. Empty — if no service list is available, the booking call to action remains and directs to identity establishment. Success — visitor reaches Sign Up or Login. Error / recovery — if navigation to identity establishment fails, the visitor can retry from the same call to action.

Sign Up

• Information / state: Anonymous first-use enrollment form for a customer independently beginning to book appointments online.
• Primary action: Submit enrollment to create the customer's identity.
• Supporting actions: Navigate to Login for an already-enrolled customer.
• Domain entities: Customer identity (name, contact email, credential).
• Component responsibilities: Enrollment form panel; field-level validation messaging; submit control; link to Login.
• States: Loading — submit control shows in-progress while the enrollment request is processed. Empty — pristine form. Success — identity established; the customer continues to Book Appointment. Error / recovery — invalid or incomplete input is reported per field and the form retains entered values; a failed enrollment request is reported and can be resubmitted.

Login

• Information / state: Anonymous returning-verification form for customers and the barber / shop owner.
• Primary action: Submit credentials to reach protected appointment state.
• Supporting actions: Navigate to Sign Up for a customer without an identity.
• Domain entities: Customer identity, barber / shop owner identity.
• Component responsibilities: Credential form panel; error messaging; submit control; link to Sign Up.
• States: Loading — submit control shows in-progress while verification is processed. Empty — pristine form. Success — the customer continues to Book Appointment or Booking Confirmation; the barber / shop owner continues to Appointments. Error / recovery — incorrect credentials are reported without revealing which field was wrong, and the form can be resubmitted.

Book Appointment

• Information / state: Protected, customer-only. The selected service, the selected time slot, and a running summary of service, time, and price.
• Primary action: Submit the booking for the selected service and time slot.
• Supporting actions: Select a service from the stacked service list; select an available time slot; adjust the selection before submitting.
• Domain entities: Service (name, duration, price), Time slot (start time, availability), Appointment (customer, service, time slot, status).
• Component responsibilities: Two-panel split — a pinned running summary panel (service, time, price) and the step content panel; stacked service rows that expand in place to reveal duration and price; time slots as pill chips; submit control.
• States: Loading — available services and slots are being retrieved; the summary panel shows placeholders until a selection exists. Empty — no service selected yet, or no time slots available for the chosen service; the customer is told no slots are currently available and can choose another service. Success — the booking is accepted and the customer is taken to Booking Confirmation. Error / recovery — a slot taken between selection and submission is reported, the slot list refreshes, and the customer can pick another slot and resubmit; a failed submission is reported and the selection is retained.

Booking Confirmation

• Information / state: Protected, customer-only. Confirmation that the submitted appointment booking was accepted, showing the confirmed service, time, and price.
• Primary action: Return to booking to book another appointment.
• Supporting actions: Review the confirmed appointment details.
• Domain entities: Appointment (customer, service, time slot, status, price).
• Component responsibilities: Confirmation card presenting the appointment time prominently, the service and price, and a confirmed status marker; control to start another booking.
• States: Loading — confirmation details are being retrieved. Empty — no accepted booking is available to show; the customer is directed back to Book Appointment. Success — the accepted appointment is displayed. Error / recovery — if the confirmation cannot be retrieved, the customer can retry, and the accepted booking remains recorded.

Appointments

• Information / state: Protected, barber / shop owner only. The list of appointments booked online, with customer, service, time, and status.
• Primary action: Review the booked appointments to keep the chair schedule accurate.
• Supporting actions: Scan the list by time and status.
• Domain entities: Appointment (customer, service, time slot, status), Customer (name, contact).
• Component responsibilities: Appointment table with rows colour-coded by status; columns for customer, service, time, and status.
• States: Loading — the appointment list is being retrieved. Empty — no appointments have been booked online yet; the owner is told there are none. Success — the booked appointments are listed. Error / recovery — if the list cannot be retrieved, the owner can retry.

3. Functional Requirements

FR-1 — Barbershop website (explicit). As a visitor, I should reach a website for the barbershop so that I can learn about the shop and its services. Trigger: the visitor opens the site. Observable result: the Landing page presents the shop and its services. Access: anonymous. Failure / recovery: if the page fails to load, the visitor can reload. Continuation: the visitor can begin booking or go to Sign Up or Login.

FR-2 — Online appointment booking (explicit). As a Customer, I should book an appointment online through the website so that I secure a slot without calling or visiting. Trigger: the customer chooses to book. Input: a selected service and an available time slot. Observable result: the booking is submitted and accepted, and the appointment is recorded. Access: protected; the customer must be verified. Failure / recovery: if the chosen slot is no longer available or submission fails, the customer is told, the slot list refreshes, and the customer can choose another slot and resubmit. Continuation: the customer proceeds to Booking Confirmation.

FR-3 — Customer self-service enrollment (required_inference). As a Customer, I should establish my own identity before booking so that my booking is bound to me and I can return to it. Trigger: an unauthenticated customer begins booking. Input: enrollment details. Observable result: the customer's identity is established and protected booking state becomes reachable. Access: anonymous entry on Sign Up. Failure / recovery: invalid or incomplete input is reported per field and the form retains entered values; a failed enrollment request can be resubmitted. Continuation: the customer continues to Book Appointment.

FR-4 — Returning verification (required_inference). As a Customer or the Barber / Shop Owner, I should verify my identity on return so that I can reach my protected appointment state. Trigger: a returning customer or the owner opens Login. Input: credentials. Observable result: the customer reaches Book Appointment or Booking Confirmation; the owner reaches Appointments. Access: anonymous entry on Login; protected destinations remain unavailable until verification succeeds. Failure / recovery: incorrect credentials are reported without revealing which field was wrong, and the form can be resubmitted. Continuation: the actor proceeds to their protected destination.

FR-5 — Service and time-slot selection (required_inference). As a Customer, I should select a service and an available time slot so that I can submit a booking for the slot I want. Trigger: the verified customer is on Book Appointment. Input: a service chosen from the stacked service list and a time slot chosen from the available slots. Observable result: the running summary shows the selected service, time, and price. Access: protected, customer-only. Failure / recovery: if no slots are available for the chosen service, the customer is told and can choose another service. Continuation: the customer submits the booking.

FR-6 — Booking submission and acceptance (required_inference). As a Customer, I should submit my selected service and time slot so that my appointment is accepted and confirmed. Trigger: the customer submits the booking. Observable result: the appointment is accepted and recorded, and the customer is taken to Booking Confirmation showing the confirmed service, time, and price. Access: protected, customer-only. Failure / recovery: a slot taken between selection and submission is reported, the slot list refreshes, and the customer can pick another slot and resubmit; a failed submission is reported and the selection is retained. Continuation: the customer reviews the confirmation or starts another booking.

FR-7 — Durable appointment records (required_inference). As the system, I should persist submitted bookings so that they remain available for later review by the customer and the shop owner. Trigger: an accepted booking. Observable result: the appointment record persists with its customer, service, time slot, status, and price. Access: protected; readable by the owning customer and by the barber / shop owner. Failure / recovery: if persistence fails, the booking is not reported as accepted and the customer can resubmit. Continuation: the record appears on Booking Confirmation and on Appointments.

FR-8 — Owner appointment review (required_inference). As the Barber / Shop Owner, I should review the appointments booked online so that the chair schedule stays accurate. Trigger: the verified owner opens Appointments. Observable result: the list of booked appointments with customer, service, time, and status is shown. Access: protected, owner-only. Failure / recovery: if the list cannot be retrieved, the owner can retry. Continuation: the owner uses the list to know who is coming and when.

4. User Personas

Customer

• Product context: A barbershop client who wants to book an appointment online without calling or visiting. They arrive on the shop's website, most often on a phone, and choose a barber and a cut the way they choose a record or a sneaker — by vibe and by the cut.
• Primary goal: Secure a confirmed appointment for a chosen service and time slot.
• Distinct accepted responsibilities: Establish their own identity through self-service enrollment; verify their identity on return; browse the shop's services; select a service and an available time slot; submit the booking; receive and review the confirmation; start another booking.
• Relevant inputs or decisions: Which service to book; which available time slot to take; whether to enroll (Sign Up) or verify (Login); whether to adjust the selection before submitting.
• Interactions with other accepted participants: The customer's submitted booking becomes the record the Barber / Shop Owner reviews on Appointments; the customer's own confirmation is the other side of that same accepted booking.
• Observable success: A confirmed appointment for the chosen slot, shown on Booking Confirmation with the service, time, and price.

Barber / Shop Owner

• Product context: The person running the barbershop, who needs to see and manage incoming online appointment bookings so the chair schedule stays accurate. Their recurring responsibility is reviewing booked appointments and knowing who is coming and when.
• Primary goal: Keep the shop's day running on the bookings customers made online.
• Distinct accepted responsibilities: Verify their identity on return through Login; review the appointments booked online on Appointments, scanning by time and status.
• Relevant inputs or decisions: Which appointments are booked, for which service and time, and in what status.
• Interactions with other accepted participants: The owner reviews the appointments that Customers submitted and had accepted; the owner's view is the shop-side counterpart of each customer's confirmation.
• Observable success: The owner can see the booked appointments with customer, service, time, and status, and the chair schedule matches what customers booked online.

5. Core User Flows

Flow A — Customer books an appointment online (first-time customer)

1. The Customer opens the site and lands on Landing (anonymous). They see the shop, its services, and the invitation to book a cut.
2. The Customer chooses to book. Because they have no identity yet, they are directed to Sign Up.
3. On Sign Up, the Customer enters their enrollment details and submits. The application establishes their identity, and protected booking state becomes reachable.
4. The Customer arrives on Book Appointment (protected, customer-only). The stacked service list is shown; the running summary panel is empty until a selection exists.
5. The Customer selects a service. The row expands in place to reveal duration and price, and the summary panel updates with the service and price.
6. The Customer selects an available time slot from the pill chips. The summary panel updates with the selected time and price.
7. The Customer submits the booking. The application accepts the booking and records the appointment.
8. The Customer is taken to Booking Confirmation, which shows the confirmed service, time, and price with a confirmed status marker.
9. Failure / recovery: if the chosen slot was taken between selection and submission, the Customer is told, the slot list refreshes, and they pick another slot and resubmit; if submission fails, the selection is retained and can be resubmitted.
10. Continuation: the Customer can start another booking from Booking Confirmation, returning to Book Appointment.

Flow B — Returning customer verifies and books again

1. The Customer opens Login (anonymous) and submits their credentials.
2. On success, the Customer reaches their protected appointment state — Book Appointment to book again, or Booking Confirmation to review their accepted booking.
3. Failure / recovery: if the credentials are incorrect, the error is reported without revealing which field was wrong, and the Customer resubmits.
4. Continuation: the Customer selects a service and an available time slot on Book Appointment and submits, following Flow A from step 5.

Flow C — Barber / Shop Owner reviews booked appointments

1. The Barber / Shop Owner opens Login (anonymous) and submits their credentials.
2. On success, the owner reaches Appointments (protected, owner-only).
3. The owner reviews the list of appointments booked online, with customer, service, time, and status, scanning by time and status to keep the chair schedule accurate.
4. Empty state: if no appointments have been booked online yet, the owner is told there are none.
5. Failure / recovery: if the list cannot be retrieved, the owner retries.
6. Continuation: the owner uses the reviewed list to know who is coming and when; the appointments shown are the same accepted bookings Customers received on Booking Confirmation.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. Muse: Jessica Walsh. Headline register: saturated swagger for the chair — a drop, not a form.

Color tokens (light mode):

No gradients on UI surfaces; gradients only inside staged prop imagery. Contrast: ink on apricot ≈ 14:1; ink on hot pink ≈ 5.4:1 (body copy on pink must be ink, never white at small sizes); ink on lime ≈ 15:1.

Typography:

• Headings: Archivo Black at 400 (its only weight), letter-spacing -0.03em, sentence case, not all-caps. Hero at clamp(56px, 11vw, 168px) with line-height 0.88; section headings clamp(32px, 5vw, 72px). One word per headline may be flipped to Space Grotesk 700 italic in lime as an emphasis gesture.
• Labels / eyebrow text: Space Grotesk 500, uppercase, 0.14em tracking, 12–13px.
• Body: Space Grotesk. Scale: 1.25 modular on body, 1.6 modular on display. Tokens: 12 / 14 / 17 / 21 / 26 / 32 / 44 / 60 / 84 / 120. Body 17px/1.6 desktop, 16px/1.65 mobile.
• Numbers (prices, times, slot counts): Space Grotesk 700 with tabular figures.

Shape language: Hard-edged colour fields with a small deliberate radius — panels and buttons 14px, slot chips 999px (pills), image frames 0px so photography reads as a printed poster crop. Thick 3px ink rules under section headers and around the booking summary. Sticker-like rotated badges (a lime "WALK-INS WELCOME" tag at -6°) sit on top of panels. No soft offset shadows — depth comes from flat colour overlap and a single hard 6px ink offset on primary buttons.

Layout: Poster grid, asymmetric and full-bleed. The landing page is three stacked colour fields: apricot hero, hot-pink service band, ink footer band. Content sits on a 12-column grid at 1280px with a 4-column gutter, collapsing to a single column at 375px with 20px side padding. The booking flow uses a two-panel split: left 5 columns is the running summary (service, time, price) pinned in ink on apricot; right 7 columns is the step content on hot pink. The service list is a stacked list of full-width rows with hairline ink rules — explicitly not a grid of cards. The owner appointment list is a table with colour-coded rows by status.

Imagery: Art-directed and staged, never stock: high-contrast flash-lit portraits of the shop's actual barbers and cuts shot against flat hot-pink or lime seamless; tight crops on clippers, straight razors, talc and tonic bottles arranged as surreal still lifes; one wide shot of the shop chairs in apricot light. Photography is cropped hard to the frame edge, printed-poster style, with occasional halftone treatment in ink. No generic "smiling man in barbershop" stock, no illustrated mascots, no 3D blobs.

Avoid: White or near-white page ground anywhere; blue, indigo or violet of any kind; gradient-blob heroes; Inter, Roboto, Poppins, Manrope, DM Sans or any neutral geometric sans for headings or body; a grid of identical rounded cards with soft shadows and hover-lift; white text on hot pink at body size; stock photography of smiling men in aprons; illustrated mascots or 3D blob characters; centred headline + subtext + single CTA hero composition; soft drop shadows for depth.

7. Signature Design Concept

The public entry is a full-bleed apricot poster. A single flash-lit barber portrait is cropped hard at the right edge, bleeding off the viewport, occupying the right 45% and overlapping the type. The headline is set in Archivo Black at clamp(56px, 11vw, 168px), flush left, three stacked lines — BOOK / THE / CHAIR — with "THE" flipped to lime on a rotated lime block behind it, overlapping the line above and below. Beneath the headline sits a lime pill CTA BOOK A CUT with a hard 6px ink offset, and next to it a small ink-on-apricot line: Next free slot today · 4:30pm. A running marquee ticker in ink on a hot-pink band sits along the very bottom of the hero: SKIN FADES · HOT TOWEL SHAVES · BEARD TRIM · WALK-INS ·. No centred stack, no gradient, no blue button.

The concept recomposes only accepted content and controls: the shop identity, the service names, the booking call to action, and the next-available-slot indicator. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: the flash-lit barber portrait cropped hard at the right edge, bleeding off the viewport and overlapping the headline type.
• Input → transformation → outcome thesis: as the visitor arrives, the hot-pink service band wipes up over the apricot ground (380ms, cubic-bezier(0.16,1,0.3,1)), the three headline lines reveal word-by-word with a 40ms stagger, and the marquee ticker begins running service names and "WALK-INS WELCOME" along the bottom edge — the visitor's outcome is a composed poster frame with the booking call to action fully readable and ready.
• Motion vocabulary: colour-block wipes on section entry; word-by-word headline reveal with 40ms stagger; a continuously running marquee ticker; hover on the primary button flips its hard ink offset from 6px to 2px (a press, not a lift); slot chips scale 0.94→1 with a lime flash on selection; a 200ms counter roll on the price in the pinned summary panel.
• Composed first frame: apricot ground, portrait bleeding off the right edge, "BOOK / THE / CHAIR" flush left with "THE" on a rotated lime block, lime pill CTA with hard ink offset, next-free-slot line, and the hot-pink ticker band along the bottom.
• Reduced-motion state: all wipes become instant, the ticker becomes a horizontally scrollable row of static items, and the stagger collapses to a single fade.

9. Non-Functional Requirements

• NFR-1 — Durable appointment persistence (required_inference). Submitted bookings must persist so that they remain available for later review by the customer and the shop owner. Rationale: the accepted booking is a commitment that must survive the session and be visible on both Booking Confirmation and Appointments.
• NFR-2 — Protected state (required_inference). Book Appointment, Booking Confirmation, and Appointments must be unreachable until identity is established; Landing, Sign Up, and Login are anonymously reachable. Rationale: a customer's booking state is private to that customer, and the owner's appointment list is private to the shop.
• NFR-3 — Readable text and controls at every viewport (explicit). Headlines, wordmarks, labels, numbers, cards' text and controls must stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element may cover any part of them. Imagery, decoration and motion may be cropped, bled off an edge, rotated, overlapped or cut as the direction asks, as long as they cover no readable text or control. Moving and scrollable content (marquees, tickers, horizontally scrollable rows) may cross the viewport or container edge by design and is judged by whether it actually moves or scrolls and whether every item becomes fully readable as it passes. Under prefers-reduced-motion, a usable static arrangement must be provided — items wrap into rows or scroll horizontally so each item can be brought fully into view.
• NFR-4 — Reduced-motion support (explicit). Under prefers-reduced-motion, all wipes become instant, the ticker becomes a horizontally scrollable row of static items, and the stagger collapses to a single fade.
• NFR-5 — Accessible contrast (explicit). Ink on apricot ≈ 14:1; ink on hot pink ≈ 5.4:1 (body copy on pink must be ink, never white at small sizes); ink on lime ≈ 15:1.

10. Tech Stack

• Frontend: React (custom web UI).
• Backend: Python / FastAPI, extending a single shared backend process for the booking API, identity, and appointment records.
• Storage: a persistent datastore for durable appointment records and identities.
• Deployment: Docker / docker-compose for the frontend and backend services.

No source-specified technology beyond the above was supplied; no additional services are introduced.

11. Assumptions and Constraints

• A-1 (assumption). The barbershop's services, durations, and prices are shop-owned content that the site presents; the source does not specify a service-management capability, so none is added.
• A-2 (assumption). Available time slots are derived from the shop's bookable hours; the source does not specify a scheduling engine, so only the slot selection and booking submission accepted by the source are in scope.
• A-3 (constraint). The site is a first-party website for the barbershop; no third-party booking marketplace or provider-owned surface is introduced.
• A-4 (constraint). The generic indigo/blue-on-white SaaS template is forbidden for this project; the palette, fonts, surfaces, tone, and layout in Section 6 are binding.
• A-5 (constraint). No payment processing, customer messaging or notifications, staff/barber roster management, inventory or product sales, loyalty programs, or multi-location support are in scope; the source does not authorize them.

12. Glossary

• Appointment: A booking of a service at a time slot by a customer, with a status and price, persisted as a durable record.
• Barber / Shop Owner: The accepted persona who runs the barbershop and reviews the appointments booked online.
• Customer: The accepted persona who books an appointment online through the website.
• Service: A barbershop offering (for example a skin fade, hot towel shave, or beard trim) with a duration and price.
• Time slot: A bookable start time for a service; shown as pill chips on the booking panel and selectable by the customer.
• Booking Confirmation: The protected page where a customer receives confirmation that their submitted appointment booking was accepted.
• Appointments: The protected page where the barber / shop owner reviews the appointments booked online.
• Landing: The anonymous public entry page presenting the barbershop and its online appointment booking.
• Sign Up: The anonymous self-service enrollment page where a customer establishes their identity.
• Login: The anonymous returning-verification page for customers and the barber / shop owner.