# zeus-pr/cutly architecture

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

- Interactive diagram: https://gitdiagram.com/zeus-pr/cutly
- Repository: https://github.com/zeus-pr/cutly

## Overview

CUTLY is a customer-facing salon/barber discovery and booking product, with separate partner operations and admin surfaces. The main customer journey is sign-in, find a nearby shop or service, select a booking time, place a hold, review and confirm, then manage visits. The README describes backend availability, booking-state, payment-provider, and relational-model capabilities; only some backend routes were excerpted, so uncertain internal calls are omitted. The repository tree does not include the documented Prisma schema, so no schema or database node is asserted.

Main entry points: [`backend/src/server.ts`](https://github.com/zeus-pr/cutly/blob/main/backend/src/server.ts) (REST API routes), [`services/api.ts`](https://github.com/zeus-pr/cutly/blob/main/services/api.ts) (Mobile API boundary), [`app/booking/review.tsx`](https://github.com/zeus-pr/cutly/blob/main/app/booking/review.tsx) (Booking review), [`app/search/index.tsx`](https://github.com/zeus-pr/cutly/blob/main/app/search/index.tsx) (Shop discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer app"]
  node_auth["Customer sign-in<br/>[auth.tsx]"]
  node_discovery["Shop discovery<br/>[index.tsx]"]
  node_service_results["Service results<br/>[&#91;service&#93;.tsx]"]
  node_shop_detail["Shop selection<br/>[index.tsx]"]
  node_booking_flow["Booking selection<br/>[booking.tsx]"]
  node_booking_review["Booking review<br/>[review.tsx]"]
  node_booking_status["Booking management<br/>[&#91;id&#93;.tsx]"]
  node_visits["Visit history<br/>[visits.tsx]"]
end

subgraph group_booking["Booking backend"]
  node_backend["REST API routes<br/>[server.ts]"]
  node_availability["Availability engine<br/>[availability.ts]"]
  node_booking_state["Booking transitions<br/>[bookingState.ts]"]
  node_customer_domain["Customer services<br/>[customer.ts]"]
  node_payment["Payment provider<br/>[payment.ts]"]
end

subgraph group_partner["Partner operations"]
  node_partner_app["Partner workspace<br/>[index.tsx]"]
  node_partner_service["Partner operations<br/>[partner.ts]"]
  node_partner_history["Partner history<br/>[partnerHistory.ts]"]
end

subgraph group_admin["Admin and web"]
  node_marketing["Partner lead site<br/>[App.tsx]"]
  node_lead_api["Lead submission API<br/>[api.ts]"]
  node_admin_console["Admin console<br/>[App.tsx]"]
  node_catalogue_admin["Catalogue management<br/>[catalogueAdmin.ts]"]
end

subgraph group_shared["Shared app services"]
  node_client_api["Mobile API boundary<br/>[api.ts]"]
  node_place_state["Place and location<br/>[usePlaceStore.ts]"]
  node_session_state["Secure session<br/>[useSessionStore.ts]"]
end

node_customer(("Customer"))

node_customer -->|"signs in"| node_auth
node_auth -->|"stores session"| node_session_state
node_customer -->|"finds shops"| node_discovery
node_discovery -->|"queries shops"| node_client_api
node_discovery -->|"uses active place"| node_place_state
node_customer -->|"chooses service"| node_service_results
node_service_results -->|"loads shop results"| node_client_api
node_customer -->|"selects shop"| node_shop_detail
node_customer -->|"selects time"| node_booking_flow
node_booking_flow -.->|"requests availability"| node_client_api
node_customer -->|"reviews booking"| node_booking_review
node_booking_review -->|"creates booking"| node_client_api
node_booking_review -->|"notifies shop"| node_booking_review
node_customer -->|"checks booking"| node_booking_status
node_customer -->|"views visits"| node_visits
node_client_api -.->|"calls REST API"| node_backend
node_backend -->|"routes customer actions"| node_customer_domain
node_backend -->|"routes booking actions"| node_booking_state
node_backend -.->|"uses availability"| node_availability
node_backend -.->|"uses provider contract"| node_payment
node_customer -->|"partner signs in"| node_partner_app
node_partner_app -.->|"manages operations"| node_partner_service
node_partner_app -.->|"views history"| node_partner_history
node_marketing -->|"submits partner lead"| node_lead_api
node_lead_api -.->|"submits lead"| node_backend
node_admin_console -.->|"administers product"| node_backend
node_backend -->|"routes catalogue edits"| node_catalogue_admin

click node_auth "https://github.com/zeus-pr/cutly/blob/main/app/auth.tsx"
click node_discovery "https://github.com/zeus-pr/cutly/blob/main/app/search/index.tsx"
click node_service_results "https://github.com/zeus-pr/cutly/blob/main/app/search/%5Bservice%5D.tsx"
click node_shop_detail "https://github.com/zeus-pr/cutly/blob/main/app/shop/%5Bid%5D/index.tsx"
click node_booking_flow "https://github.com/zeus-pr/cutly/blob/main/app/booking.tsx"
click node_booking_review "https://github.com/zeus-pr/cutly/blob/main/app/booking/review.tsx"
click node_booking_status "https://github.com/zeus-pr/cutly/blob/main/app/booking/%5Bid%5D.tsx"
click node_visits "https://github.com/zeus-pr/cutly/blob/main/app/visits.tsx"
click node_client_api "https://github.com/zeus-pr/cutly/blob/main/services/api.ts"
click node_place_state "https://github.com/zeus-pr/cutly/blob/main/store/usePlaceStore.ts"
click node_session_state "https://github.com/zeus-pr/cutly/blob/main/store/useSessionStore.ts"
click node_backend "https://github.com/zeus-pr/cutly/blob/main/backend/src/server.ts"
click node_availability "https://github.com/zeus-pr/cutly/blob/main/backend/src/availability.ts"
click node_booking_state "https://github.com/zeus-pr/cutly/blob/main/backend/src/bookingState.ts"
click node_customer_domain "https://github.com/zeus-pr/cutly/blob/main/backend/src/customer.ts"
click node_payment "https://github.com/zeus-pr/cutly/blob/main/backend/src/payment.ts"
click node_partner_app "https://github.com/zeus-pr/cutly/blob/main/app/partner/(tabs)/index.tsx"
click node_partner_service "https://github.com/zeus-pr/cutly/blob/main/backend/src/partner.ts"
click node_partner_history "https://github.com/zeus-pr/cutly/blob/main/backend/src/partnerHistory.ts"
click node_marketing "https://github.com/zeus-pr/cutly/blob/main/site/src/App.tsx"
click node_lead_api "https://github.com/zeus-pr/cutly/blob/main/site/src/api.ts"
click node_admin_console "https://github.com/zeus-pr/cutly/blob/main/admin/src/App.tsx"
click node_catalogue_admin "https://github.com/zeus-pr/cutly/blob/main/backend/src/catalogueAdmin.ts"

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_auth,node_discovery,node_service_results,node_shop_detail,node_booking_flow,node_booking_review,node_booking_status,node_visits toneBlue
class node_backend,node_availability,node_booking_state,node_customer_domain,node_payment toneAmber
class node_partner_app,node_partner_service,node_partner_history toneMint
class node_marketing,node_lead_api,node_admin_console,node_catalogue_admin toneRose
class node_client_api,node_place_state,node_session_state,node_customer toneIndigo
```

## Components

### Customer app

- [Customer sign-in](https://github.com/zeus-pr/cutly/blob/main/app/auth.tsx): `app/auth.tsx`
- [Shop discovery](https://github.com/zeus-pr/cutly/blob/main/app/search/index.tsx): `app/search/index.tsx`
- [Service results](https://github.com/zeus-pr/cutly/blob/main/app/search/%5Bservice%5D.tsx): `app/search/[service].tsx`
- [Shop selection](https://github.com/zeus-pr/cutly/blob/main/app/shop/%5Bid%5D/index.tsx): `app/shop/[id]/index.tsx`
- [Booking selection](https://github.com/zeus-pr/cutly/blob/main/app/booking.tsx): `app/booking.tsx`
- [Booking review](https://github.com/zeus-pr/cutly/blob/main/app/booking/review.tsx): `app/booking/review.tsx`
- [Booking management](https://github.com/zeus-pr/cutly/blob/main/app/booking/%5Bid%5D.tsx): `app/booking/[id].tsx`
- [Visit history](https://github.com/zeus-pr/cutly/blob/main/app/visits.tsx): `app/visits.tsx`

### Booking backend

- [REST API routes](https://github.com/zeus-pr/cutly/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Availability engine](https://github.com/zeus-pr/cutly/blob/main/backend/src/availability.ts): `backend/src/availability.ts`
- [Booking transitions](https://github.com/zeus-pr/cutly/blob/main/backend/src/bookingState.ts): `backend/src/bookingState.ts`
- [Customer services](https://github.com/zeus-pr/cutly/blob/main/backend/src/customer.ts): `backend/src/customer.ts`
- [Payment provider](https://github.com/zeus-pr/cutly/blob/main/backend/src/payment.ts): `backend/src/payment.ts`

### Partner operations

- [Partner workspace](https://github.com/zeus-pr/cutly/blob/main/app/partner/(tabs)/index.tsx): `app/partner/(tabs)/index.tsx`
- [Partner operations](https://github.com/zeus-pr/cutly/blob/main/backend/src/partner.ts): `backend/src/partner.ts`
- [Partner history](https://github.com/zeus-pr/cutly/blob/main/backend/src/partnerHistory.ts): `backend/src/partnerHistory.ts`

### Admin and web

- [Partner lead site](https://github.com/zeus-pr/cutly/blob/main/site/src/App.tsx): `site/src/App.tsx`
- [Lead submission API](https://github.com/zeus-pr/cutly/blob/main/site/src/api.ts): `site/src/api.ts`
- [Admin console](https://github.com/zeus-pr/cutly/blob/main/admin/src/App.tsx): `admin/src/App.tsx`
- [Catalogue management](https://github.com/zeus-pr/cutly/blob/main/backend/src/catalogueAdmin.ts): `backend/src/catalogueAdmin.ts`

### Shared app services

- [Mobile API boundary](https://github.com/zeus-pr/cutly/blob/main/services/api.ts): `services/api.ts`
- [Place and location](https://github.com/zeus-pr/cutly/blob/main/store/usePlaceStore.ts): `store/usePlaceStore.ts`
- [Secure session](https://github.com/zeus-pr/cutly/blob/main/store/useSessionStore.ts): `store/useSessionStore.ts`

### Other components

- **Customer**

## Connections

- Customer → Customer sign-in: signs in (evidence: `README.md`)
- Customer sign-in → Secure session: stores session (evidence: `app/auth.tsx`)
- Customer → Shop discovery: finds shops (evidence: `README.md`)
- Shop discovery → Mobile API boundary: queries shops (evidence: `app/search/index.tsx`)
- Shop discovery → Place and location: uses active place (evidence: `app/search/index.tsx`)
- Customer → Service results: chooses service (evidence: `README.md`)
- Service results → Mobile API boundary: loads shop results (evidence: `app/search/[service].tsx`)
- Customer → Shop selection: selects shop (evidence: `README.md`)
- Customer → Booking selection: selects time (evidence: `README.md`)
- Booking selection → Mobile API boundary: requests availability
- Customer → Booking review: reviews booking (evidence: `README.md`)
- Booking review → Mobile API boundary: creates booking (evidence: `app/booking/review.tsx`)
- Booking review → Booking review: notifies shop (evidence: `app/booking/review.tsx`)
- Customer → Booking management: checks booking (evidence: `README.md`)
- Customer → Visit history: views visits (evidence: `README.md`)
- Mobile API boundary → REST API routes: calls REST API
- REST API routes → Customer services: routes customer actions (evidence: `backend/src/server.ts`)
- REST API routes → Booking transitions: routes booking actions (evidence: `backend/src/server.ts`)
- REST API routes → Availability engine: uses availability
- REST API routes → Payment provider: uses provider contract
- Customer → Partner workspace: partner signs in (evidence: `README.md`)
- Partner workspace → Partner operations: manages operations
- Partner workspace → Partner history: views history
- Partner lead site → Lead submission API: submits partner lead (evidence: `site/src/App.tsx`)
- Lead submission API → REST API routes: submits lead
- Admin console → REST API routes: administers product
- REST API routes → Catalogue management: routes catalogue edits (evidence: `backend/src/server.ts`)
