# rlswenso/hackprinceton26 architecture

> Architecture diagram of the GitHub repository rlswenso/hackprinceton26, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rlswenso/hackprinceton26
- Repository: https://github.com/rlswenso/hackprinceton26

## Overview

Lollicut is a kids’ hair-salon app: customers can book appointments, while staff manage the salon’s daily work. The repository also includes text and phone agents that support booking conversations. The graph covers those product areas and the backend services visible in the source index. Several frontend pages, routers, and agent subsystems are unsampled, so their internal connections are omitted rather than inferred.

Main entry points: [`backend/app/features/bookings/service.py`](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/bookings/service.py) (Booking confirmation), [`backend/app/features/appointments/service.py`](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/appointments/service.py) (Appointment actions), [`backend/app/features/availability/engine.py`](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/availability/engine.py) (Slot availability), [`agents/photon/voice/engine.py`](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/engine.py) (Phone call engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_booking_ui["Online booking"]
  node_staff_calendar["Staff calendar"]
  node_staff_overview["Daily overview"]
  node_staff_payments["Payment management"]
  node_staff_settings["Salon settings"]
  node_assistant_ui["Staff assistant"]
  node_auth_ui["Staff sign-in"]
end

subgraph group_backend["Salon backend"]
  node_api_routes["Backend API"]
  node_agent_api["Agent API"]
  node_availability["Slot availability<br/>[engine.py]"]
  node_booking_service["Booking confirmation<br/>[service.py]"]
  node_appointment_service["Appointment actions<br/>[service.py]"]
  node_catalog["Service catalog<br/>[service.py]"]
  node_payments_service["Payments<br/>[service.py]"]
  node_settings_service["Salon configuration<br/>[service.py]"]
  node_reminders["Reminders<br/>[service.py]"]
end

subgraph group_agents["Conversational agents"]
  node_photon_text["Text agent<br/>[server.py]"]
  node_photon_agent["Text conversation engine<br/>[agent.py]"]
  node_voice_server["Phone webhooks<br/>[server.py]"]
  node_voice_engine["Phone call engine<br/>[engine.py]"]
  node_llm["Language model client<br/>[llm.py]"]
  node_speech["Speech handling<br/>[speech.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_database[("PostgreSQL access<br/>[database.py]")]
  node_repository["Transaction repository<br/>[repository.py]"]
  node_auth["Token authorization<br/>[auth.py]"]
end

node_customer(("Customer"))
node_staff(("Salon staff"))

node_repository -->|"connects through"| node_database
node_auth -->|"checks grants"| node_repository
node_auth -->|"uses connection"| node_database
node_availability -->|"reads capacity"| node_repository
node_booking_service -->|"checks capacity"| node_availability
node_booking_service -->|"loads service"| node_catalog
node_booking_service -->|"records intent"| node_reminders
node_appointment_service -->|"checks capacity"| node_availability
node_appointment_service -->|"uses booking"| node_booking_service
node_appointment_service -->|"updates reminders"| node_reminders
node_payments_service -->|"uses appointments"| node_appointment_service
node_payments_service -->|"uses bookings"| node_booking_service
node_payments_service -->|"checks availability"| node_availability
node_settings_service -->|"uses appointments"| node_appointment_service
node_settings_service -->|"uses bookings"| node_booking_service
node_settings_service -->|"checks availability"| node_availability
node_agent_api -->|"uses appointments"| node_appointment_service
node_agent_api -->|"checks slots"| node_availability
node_agent_api -->|"confirms bookings"| node_booking_service
node_customer -.->|"books online"| node_booking_ui
node_staff -.->|"manages visits"| node_staff_calendar
node_staff -.->|"views day"| node_staff_overview
node_staff -.->|"records payments"| node_staff_payments
node_staff -.->|"configures salon"| node_staff_settings
node_staff -.->|"uses assistant"| node_assistant_ui
node_photon_text -->|"dispatches turns"| node_photon_agent
node_photon_agent -->|"requests responses"| node_llm
node_voice_server -->|"routes calls"| node_voice_engine
node_voice_engine -->|"requests responses"| node_llm
node_voice_engine -->|"formats speech"| node_speech
node_voice_engine -.->|"uses shared agent logic"| node_photon_agent

click node_booking_ui "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/booking"
click node_staff_calendar "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/calendar"
click node_staff_overview "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/overview"
click node_staff_payments "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/payments"
click node_staff_settings "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/settings"
click node_assistant_ui "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/assistant"
click node_auth_ui "https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/auth"
click node_api_routes "https://github.com/rlswenso/hackprinceton26/tree/main/backend/app/features"
click node_agent_api "https://github.com/rlswenso/hackprinceton26/tree/main/backend/app/features/agent"
click node_availability "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/availability/engine.py"
click node_booking_service "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/bookings/service.py"
click node_appointment_service "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/appointments/service.py"
click node_catalog "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/catalog/service.py"
click node_payments_service "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/payments/service.py"
click node_settings_service "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/settings/service.py"
click node_reminders "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/reminders/service.py"
click node_database "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/core/database.py"
click node_repository "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/db/repository.py"
click node_auth "https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/core/auth.py"
click node_photon_text "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/server.py"
click node_photon_agent "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/agent.py"
click node_voice_server "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/server.py"
click node_voice_engine "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/engine.py"
click node_llm "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/llm.py"
click node_speech "https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/speech.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_booking_ui,node_staff_calendar,node_staff_overview,node_staff_payments,node_staff_settings,node_assistant_ui,node_auth_ui toneBlue
class node_api_routes,node_agent_api,node_availability,node_booking_service,node_appointment_service,node_catalog,node_payments_service,node_settings_service,node_reminders toneAmber
class node_photon_text,node_photon_agent,node_voice_server,node_voice_engine,node_llm,node_speech toneMint
class node_database,node_repository,node_auth toneRose
class node_customer,node_staff toneIndigo
```

## Components

### Web application

- [Online booking](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/booking): `frontend/src/features/booking`
- [Staff calendar](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/calendar): `frontend/src/features/calendar`
- [Daily overview](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/overview): `frontend/src/features/overview`
- [Payment management](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/payments): `frontend/src/features/payments`
- [Salon settings](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/settings): `frontend/src/features/settings`
- [Staff assistant](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/assistant): `frontend/src/features/assistant`
- [Staff sign-in](https://github.com/rlswenso/hackprinceton26/tree/main/frontend/src/features/auth): `frontend/src/features/auth`

### Salon backend

- [Backend API](https://github.com/rlswenso/hackprinceton26/tree/main/backend/app/features): `backend/app/features`
- [Agent API](https://github.com/rlswenso/hackprinceton26/tree/main/backend/app/features/agent): `backend/app/features/agent`
- [Slot availability](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/availability/engine.py): `backend/app/features/availability/engine.py`
- [Booking confirmation](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/bookings/service.py): `backend/app/features/bookings/service.py`
- [Appointment actions](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/appointments/service.py): `backend/app/features/appointments/service.py`
- [Service catalog](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/catalog/service.py): `backend/app/features/catalog/service.py`
- [Payments](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/payments/service.py): `backend/app/features/payments/service.py`
- [Salon configuration](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/settings/service.py): `backend/app/features/settings/service.py`
- [Reminders](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/features/reminders/service.py): `backend/app/features/reminders/service.py`

### Conversational agents

- [Text agent](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/server.py): `agents/photon/lollicut_photon/server.py`
- [Text conversation engine](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/agent.py): `agents/photon/lollicut_photon/agent.py`
- [Phone webhooks](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/server.py): `agents/photon/voice/server.py`
- [Phone call engine](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/engine.py): `agents/photon/voice/engine.py`
- [Language model client](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/lollicut_photon/llm.py): `agents/photon/lollicut_photon/llm.py`
- [Speech handling](https://github.com/rlswenso/hackprinceton26/blob/main/agents/photon/voice/speech.py): `agents/photon/voice/speech.py`

### Shared foundations

- [PostgreSQL access](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Transaction repository](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/db/repository.py): `backend/app/db/repository.py`
- [Token authorization](https://github.com/rlswenso/hackprinceton26/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`

### Other components

- **Customer**
- **Salon staff**

## Connections

- Transaction repository → PostgreSQL access: connects through (evidence: `backend/app/db/repository.py`)
- Token authorization → Transaction repository: checks grants (evidence: `backend/app/core/auth.py`)
- Token authorization → PostgreSQL access: uses connection (evidence: `backend/app/core/auth.py`)
- Slot availability → Transaction repository: reads capacity (evidence: `backend/app/features/availability/engine.py`)
- Booking confirmation → Slot availability: checks capacity (evidence: `backend/app/features/bookings/service.py`)
- Booking confirmation → Service catalog: loads service (evidence: `backend/app/features/bookings/service.py`)
- Booking confirmation → Reminders: records intent (evidence: `backend/app/features/bookings/service.py`)
- Appointment actions → Slot availability: checks capacity (evidence: `backend/app/features/appointments/service.py`)
- Appointment actions → Booking confirmation: uses booking (evidence: `backend/app/features/appointments/service.py`)
- Appointment actions → Reminders: updates reminders (evidence: `backend/app/features/appointments/service.py`)
- Payments → Appointment actions: uses appointments (evidence: `backend/app/features/payments/service.py`)
- Payments → Booking confirmation: uses bookings (evidence: `backend/app/features/payments/service.py`)
- Payments → Slot availability: checks availability (evidence: `backend/app/features/payments/service.py`)
- Salon configuration → Appointment actions: uses appointments (evidence: `backend/app/features/settings/service.py`)
- Salon configuration → Booking confirmation: uses bookings (evidence: `backend/app/features/settings/service.py`)
- Salon configuration → Slot availability: checks availability (evidence: `backend/app/features/settings/service.py`)
- Agent API → Appointment actions: uses appointments (evidence: `backend/app/features/agent/service.py`)
- Agent API → Slot availability: checks slots (evidence: `backend/app/features/agent/service.py`)
- Agent API → Booking confirmation: confirms bookings (evidence: `backend/app/features/agent/service.py`)
- Customer → Online booking: books online
- Salon staff → Staff calendar: manages visits
- Salon staff → Daily overview: views day
- Salon staff → Payment management: records payments
- Salon staff → Salon settings: configures salon
- Salon staff → Staff assistant: uses assistant
- Text agent → Text conversation engine: dispatches turns (evidence: `agents/photon/lollicut_photon/server.py`)
- Text conversation engine → Language model client: requests responses (evidence: `agents/photon/lollicut_photon/agent.py`)
- Phone webhooks → Phone call engine: routes calls (evidence: `agents/photon/voice/server.py`)
- Phone call engine → Language model client: requests responses (evidence: `agents/photon/voice/engine.py`)
- Phone call engine → Speech handling: formats speech (evidence: `agents/photon/voice/engine.py`)
- Phone call engine → Text conversation engine: uses shared agent logic