# dance-engine/the-engine architecture

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

- Interactive diagram: https://gitdiagram.com/dance-engine/the-engine
- Repository: https://github.com/dance-engine/the-engine

## Overview

Dance Engine is an event and membership platform with branded public client sites, an authenticated administration app, and operational tools. The principal workflow is: an attendee discovers an event, views its details or media, joins or purchases a bundle, and reaches a success state; administrators configure events, customers, tickets, media, and organisations. Scanner and survey tools provide operational follow-up. The tree supports these route-level capabilities, while many backend persistence and Lambda implementations are not sampled.

Main entry points: [`apps/core/app/ProtectedLayout.tsx`](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/ProtectedLayout.tsx) (Admin Shell), [`apps/clients/solo/app/events/[ksuid]/page.tsx`](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/%5Bksuid%5D/page.tsx) (Event Detail), [`apps/clients/solo/app/api/stripe/checkout_session/route.ts`](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/api/stripe/checkout_session/route.ts) (Checkout API), [`apps/tools/scanner/app/page.tsx`](https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/page.tsx) (Scanner UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public Experiences"]
  node_client_site["Client Site<br/>[page.tsx]"]
  node_event_catalog["Event Catalog<br/>[page.tsx]"]
  node_event_detail["Event Detail<br/>[page.tsx]"]
  node_cart["Cart State<br/>[CartContext.tsx]"]
  node_checkout_api["Checkout API<br/>[route.ts]"]
  node_checkout_success["Checkout Success<br/>[page.tsx]"]
  node_media_gallery["Media Gallery<br/>[page.tsx]"]
  node_membership_join["Membership Join<br/>[page.tsx]"]
end

subgraph group_admin["Admin Platform"]
  node_admin_shell["Admin Shell"]
  node_event_management["Event Management<br/>[page.tsx]"]
  node_customer_management["Customer Management<br/>[page.tsx]"]
  node_ticket_management["Ticket Management<br/>[page.tsx]"]
  node_media_management["Media Management<br/>[page.tsx]"]
  node_organisation_setup["Organisation Setup<br/>[page.tsx]"]
end

subgraph group_tools["Field Tools"]
  node_scanner_ui["Scanner UI<br/>[page.tsx]"]
  node_scanner_check["Scanner Check<br/>[route.ts]"]
  node_scanner_mark["Ticket Marking<br/>[route.ts]"]
  node_survey_form["Survey Form<br/>[page.tsx]"]
  node_survey_api["Survey API<br/>[route.ts]"]
  node_survey_results["Survey Results<br/>[route.ts]"]
  node_results_dashboard["Results Dashboard"]
end

subgraph group_content["Content Integrations"]
  node_sanity_rendering["Sanity Rendering<br/>[SanityPage.tsx]"]
  node_sanity_content["Sanity Content<br/>[content.ts]"]
  node_sanity_studio["Sanity Studio<br/>[Studio.tsx]"]
end

node_attendee(("Attendee"))
node_administrator(("Administrator"))
node_scanner_operator(("Scanner Operator"))
node_survey_respondent(("Survey Respondent"))
node_stripe["Stripe"]
node_sanity["Sanity CMS"]
node_clerk["Clerk Auth"]

node_attendee -->|"visits"| node_client_site
node_client_site -->|"shows events"| node_event_catalog
node_event_catalog -->|"opens event"| node_event_detail
node_event_detail -->|"adds items"| node_cart
node_cart -->|"submits cart"| node_checkout_api
node_checkout_api -->|"creates checkout"| node_stripe
node_checkout_api -->|"redirects result"| node_checkout_success
node_event_detail -->|"opens media"| node_media_gallery
node_attendee -->|"joins"| node_membership_join
node_membership_join -.->|"loads content"| node_sanity_content
node_administrator -->|"opens console"| node_admin_shell
node_admin_shell -.->|"authenticates"| node_clerk
node_admin_shell -->|"dispatches events"| node_event_management
node_admin_shell -->|"dispatches customers"| node_customer_management
node_admin_shell -->|"dispatches tickets"| node_ticket_management
node_admin_shell -->|"dispatches media"| node_media_management
node_administrator -->|"starts onboarding"| node_organisation_setup
node_scanner_operator -->|"scans tickets"| node_scanner_ui
node_scanner_ui -->|"checks ticket"| node_scanner_check
node_scanner_ui -->|"marks used"| node_scanner_mark
node_survey_respondent -->|"answers survey"| node_survey_form
node_survey_form -->|"submits answers"| node_survey_api
node_survey_results -->|"provides results"| node_results_dashboard
node_sanity_rendering -->|"loads pages"| node_sanity_content
node_sanity_content -->|"reads content"| node_sanity
node_administrator -->|"edits content"| node_sanity_studio
node_sanity_studio -->|"publishes content"| node_sanity

click node_client_site "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/page.tsx"
click node_event_catalog "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/page.tsx"
click node_event_detail "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/%5Bksuid%5D/page.tsx"
click node_cart "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/contexts/CartContext.tsx"
click node_checkout_api "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/api/stripe/checkout_session/route.ts"
click node_checkout_success "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/checkout/success/page.tsx"
click node_media_gallery "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/%5Bksuid%5D/media/page.tsx"
click node_membership_join "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/join/page.tsx"
click node_admin_shell "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/ProtectedLayout.tsx"
click node_event_management "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/events/page.tsx"
click node_customer_management "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/customers/page.tsx"
click node_ticket_management "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/events/%5Bksuid%5D/tickets/page.tsx"
click node_media_management "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/media/page.tsx"
click node_organisation_setup "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/admin/onboarding/start/page.tsx"
click node_scanner_ui "https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/page.tsx"
click node_scanner_check "https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/api/mock/scanner/check/route.ts"
click node_scanner_mark "https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/api/mock/scanner/mark-used/route.ts"
click node_survey_form "https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/page.tsx"
click node_survey_api "https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/api/survey/route.ts"
click node_survey_results "https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/api/survey/results/route.ts"
click node_results_dashboard "https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/results/ResultsDashboard.tsx"
click node_sanity_rendering "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/components/content/SanityPage.tsx"
click node_sanity_content "https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/lib/sanity/content.ts"
click node_sanity_studio "https://github.com/dance-engine/the-engine/blob/main/apps/core/app/content/%5B%5B...index%5D%5D/Studio.tsx"

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_client_site,node_event_catalog,node_event_detail,node_cart,node_checkout_api,node_checkout_success,node_media_gallery,node_membership_join toneBlue
class node_admin_shell,node_event_management,node_customer_management,node_ticket_management,node_media_management,node_organisation_setup toneAmber
class node_scanner_ui,node_scanner_check,node_scanner_mark,node_survey_form,node_survey_api,node_survey_results,node_results_dashboard toneMint
class node_sanity_rendering,node_sanity_content,node_sanity_studio toneRose
class node_attendee,node_administrator,node_scanner_operator,node_survey_respondent,node_stripe,node_sanity,node_clerk toneIndigo
```

## Components

### Public Experiences

- [Client Site](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/page.tsx): `apps/clients/solo/app/page.tsx`
- [Event Catalog](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/page.tsx): `apps/clients/solo/app/events/page.tsx`
- [Event Detail](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/%5Bksuid%5D/page.tsx): `apps/clients/solo/app/events/[ksuid]/page.tsx`
- [Cart State](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/contexts/CartContext.tsx): `apps/clients/solo/contexts/CartContext.tsx`
- [Checkout API](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/api/stripe/checkout_session/route.ts): `apps/clients/solo/app/api/stripe/checkout_session/route.ts`
- [Checkout Success](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/checkout/success/page.tsx): `apps/clients/solo/app/checkout/success/page.tsx`
- [Media Gallery](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/events/%5Bksuid%5D/media/page.tsx): `apps/clients/solo/app/events/[ksuid]/media/page.tsx`
- [Membership Join](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/app/join/page.tsx): `apps/clients/solo/app/join/page.tsx`

### Admin Platform

- [Admin Shell](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/ProtectedLayout.tsx): `apps/core/app/ProtectedLayout.tsx`
- [Event Management](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/events/page.tsx): `apps/core/app/events/page.tsx`
- [Customer Management](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/customers/page.tsx): `apps/core/app/customers/page.tsx`
- [Ticket Management](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/events/%5Bksuid%5D/tickets/page.tsx): `apps/core/app/events/[ksuid]/tickets/page.tsx`
- [Media Management](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/media/page.tsx): `apps/core/app/media/page.tsx`
- [Organisation Setup](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/admin/onboarding/start/page.tsx): `apps/core/app/admin/onboarding/start/page.tsx`

### Field Tools

- [Scanner UI](https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/page.tsx): `apps/tools/scanner/app/page.tsx`
- [Scanner Check](https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/api/mock/scanner/check/route.ts): `apps/tools/scanner/app/api/mock/scanner/check/route.ts`
- [Ticket Marking](https://github.com/dance-engine/the-engine/blob/main/apps/tools/scanner/app/api/mock/scanner/mark-used/route.ts): `apps/tools/scanner/app/api/mock/scanner/mark-used/route.ts`
- [Survey Form](https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/page.tsx): `apps/tools/survey/app/page.tsx`
- [Survey API](https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/api/survey/route.ts): `apps/tools/survey/app/api/survey/route.ts`
- [Survey Results](https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/api/survey/results/route.ts): `apps/tools/survey/app/api/survey/results/route.ts`
- [Results Dashboard](https://github.com/dance-engine/the-engine/blob/main/apps/tools/survey/app/results/ResultsDashboard.tsx): `apps/tools/survey/app/results/ResultsDashboard.tsx`

### Content Integrations

- [Sanity Rendering](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/components/content/SanityPage.tsx): `apps/clients/solo/components/content/SanityPage.tsx`
- [Sanity Content](https://github.com/dance-engine/the-engine/blob/main/apps/clients/solo/lib/sanity/content.ts): `apps/clients/solo/lib/sanity/content.ts`
- [Sanity Studio](https://github.com/dance-engine/the-engine/blob/main/apps/core/app/content/%5B%5B...index%5D%5D/Studio.tsx): `apps/core/app/content/[[...index]]/Studio.tsx`

### Other components

- **Attendee**
- **Administrator**
- **Scanner Operator**
- **Survey Respondent**
- **Stripe**
- **Sanity CMS**
- **Clerk Auth**

## Connections

- Attendee → Client Site: visits
- Client Site → Event Catalog: shows events
- Event Catalog → Event Detail: opens event
- Event Detail → Cart State: adds items
- Cart State → Checkout API: submits cart
- Checkout API → Stripe: creates checkout
- Checkout API → Checkout Success: redirects result
- Event Detail → Media Gallery: opens media
- Attendee → Membership Join: joins
- Membership Join → Sanity Content: loads content
- Administrator → Admin Shell: opens console
- Admin Shell → Clerk Auth: authenticates
- Admin Shell → Event Management: dispatches events
- Admin Shell → Customer Management: dispatches customers
- Admin Shell → Ticket Management: dispatches tickets
- Admin Shell → Media Management: dispatches media
- Administrator → Organisation Setup: starts onboarding
- Scanner Operator → Scanner UI: scans tickets
- Scanner UI → Scanner Check: checks ticket
- Scanner UI → Ticket Marking: marks used
- Survey Respondent → Survey Form: answers survey
- Survey Form → Survey API: submits answers
- Survey Results → Results Dashboard: provides results
- Sanity Rendering → Sanity Content: loads pages
- Sanity Content → Sanity CMS: reads content
- Administrator → Sanity Studio: edits content
- Sanity Studio → Sanity CMS: publishes content
