# nguyenchidung2007real-hue/cinecode architecture

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

- Interactive diagram: https://gitdiagram.com/nguyenchidung2007real-hue/cinecode
- Repository: https://github.com/nguyenchidung2007real-hue/cinecode

## Overview

CineMax AI combines movie discovery, semantic search and AI recommendations with a cinema booking flow that reserves seats, confirms bookings and issues QR tickets for check-in. Admin tools manage showtimes and synchronize external schedule data. The graph includes documented capabilities even where their UI or implementation was not sampled; those parts have no speculative wiring. Edges reflect the provided excerpts, SOURCE INDEX references or README, so some UI-to-API relationships are intentionally omitted.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/lib/bookingService.ts`](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingService.ts) (Booking service), [`src/lib/movieService.ts`](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/movieService.ts) (Movie service), [`src/lib/bookingClient.ts`](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingClient.ts) (Booking API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Movie discovery"]
  node_movie_ui["Movie browsing UI<br/>[page.tsx]"]
  node_movie_catalog_api["Movie catalog API<br/>[route.ts]"]
  node_movie_service["Movie service<br/>[movieService.ts]"]
  node_movie_fallback["Mock movie data<br/>[mockData.ts]"]
  node_semantic_search_ui["Semantic search UI"]
  node_search_api["Search API<br/>[route.ts]"]
end

subgraph group_assistant["AI and search"]
  node_rag_search["Semantic RAG service<br/>[hfRagService.ts]"]
  node_chat_ui["AI chat widget<br/>[AiChatWidget.tsx]"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_mood["Mood detection<br/>[moodDetector.ts]"]
  node_seat_recommender["Seat recommendations<br/>[seatRecommender.ts]"]
  node_groq{{"Groq AI service"}}
end

subgraph group_booking["Booking and tickets"]
  node_booking_ui["Booking modal<br/>[BookingModal.tsx]"]
  node_seat_hold_hook["Seat-hold hook<br/>[useSeatHold.ts]"]
  node_booking_client["Booking API client<br/>[bookingClient.ts]"]
  node_seats_api["Seat holds API<br/>[route.ts]"]
  node_booking_api["Booking API<br/>[route.ts]"]
  node_booking_service["Booking service<br/>[bookingService.ts]"]
  node_ticket_ui["My tickets UI<br/>[MyTicketsModal.tsx]"]
  node_ticket_api["Ticket lookup API<br/>[route.ts]"]
  node_showtimes_api["Showtimes API<br/>[route.ts]"]
end

subgraph group_operations["Cinema operations"]
  node_scanner_ui["Ticket scanner<br/>[page.tsx]"]
  node_checkin_api["Check-in API<br/>[route.ts]"]
  node_admin_ui["Admin dashboard<br/>[page.tsx]"]
  node_admin_showtimes_api["Admin showtimes API<br/>[route.ts]"]
  node_beta_sync_api["Beta schedule sync<br/>[route.ts]"]
  node_beta_crawler["Beta schedule crawler<br/>[betaCrawler.ts]"]
end

subgraph group_shared["Shared services"]
  node_seat_store[("Seat store<br/>[seatStore.ts]")]
  node_showtime_store[("Showtime store<br/>[showtimeStore.ts]")]
  node_ticket_store[("Ticket store<br/>[ticketStore.ts]")]
  node_admin_auth["Admin authentication<br/>[adminAuth.ts]"]
  node_kv_store["KV REST adapter<br/>[kvRest.ts]"]
  node_rate_limit["Rate limiting<br/>[rateLimit.ts]"]
end

node_visitor(("Moviegoer"))

node_visitor -.->|"browses movies"| node_movie_ui
node_visitor -.->|"books tickets"| node_booking_ui
node_movie_catalog_api -->|"loads movies"| node_movie_service
node_movie_service -->|"falls back to"| node_movie_fallback
node_movie_service -.-> node_groq
node_semantic_search_ui -.->|"searches movies"| node_search_api
node_search_api -->|"loads catalog"| node_movie_service
node_search_api -->|"ranks results"| node_rag_search
node_chat_ui -.->|"sends messages"| node_chat_api
node_chat_api -->|"loads catalog"| node_movie_service
node_chat_api -->|"builds context"| node_rag_search
node_chat_api -->|"detects mood"| node_mood
node_chat_api -->|"extracts party size"| node_seat_recommender
node_chat_api -.->|"streams completion"| node_groq
node_booking_ui -->|"manages seat holds"| node_seat_hold_hook
node_booking_ui -->|"calls booking API"| node_booking_client
node_seat_hold_hook -->|"requests seat holds"| node_booking_client
node_booking_client -->|"calls seat endpoint"| node_seats_api
node_booking_client -->|"submits booking"| node_booking_api
node_seats_api -->|"holds or releases"| node_booking_service
node_seats_api -->|"reads seat status"| node_seat_store
node_booking_api -->|"processes booking"| node_booking_service
node_booking_service -->|"holds seats"| node_seat_store
node_booking_service -->|"loads showtime"| node_showtime_store
node_booking_service -->|"creates ticket"| node_ticket_store
node_showtimes_api -->|"loads showtimes"| node_showtime_store
node_ticket_ui -.->|"looks up tickets"| node_ticket_api
node_ticket_api -->|"reads ticket"| node_ticket_store
node_scanner_ui -.->|"checks in ticket"| node_checkin_api
node_checkin_api -->|"validates ticket"| node_ticket_store
node_admin_ui -.->|"manages showtimes"| node_admin_showtimes_api
node_admin_showtimes_api -->|"checks authorization"| node_admin_auth
node_admin_showtimes_api -->|"updates showtimes"| node_showtime_store
node_beta_sync_api -->|"fetches schedules"| node_beta_crawler
node_rate_limit -->|"uses KV adapter"| node_kv_store
node_seat_store -->|"uses KV adapter"| node_kv_store
node_showtime_store -->|"uses KV adapter"| node_kv_store
node_ticket_store -->|"uses KV adapter"| node_kv_store

click node_movie_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/page.tsx"
click node_movie_catalog_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/movies/route.ts"
click node_movie_service "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/movieService.ts"
click node_movie_fallback "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/mockData.ts"
click node_semantic_search_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/SemanticSearchModal.tsx"
click node_search_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/search/route.ts"
click node_rag_search "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/hfRagService.ts"
click node_chat_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/AiChatWidget.tsx"
click node_chat_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/chat/route.ts"
click node_mood "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/moodDetector.ts"
click node_seat_recommender "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/seatRecommender.ts"
click node_booking_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/BookingModal.tsx"
click node_seat_hold_hook "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/hooks/useSeatHold.ts"
click node_booking_client "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingClient.ts"
click node_seats_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/seats/route.ts"
click node_booking_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/booking/route.ts"
click node_booking_service "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingService.ts"
click node_seat_store "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/seatStore.ts"
click node_showtime_store "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/showtimeStore.ts"
click node_ticket_store "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/ticketStore.ts"
click node_ticket_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/MyTicketsModal.tsx"
click node_ticket_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/tickets/%5Bid%5D/route.ts"
click node_scanner_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/scanner/page.tsx"
click node_checkin_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/tickets/check-in/route.ts"
click node_admin_ui "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/admin/page.tsx"
click node_admin_showtimes_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/admin/showtimes/route.ts"
click node_admin_auth "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/adminAuth.ts"
click node_showtimes_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/showtimes/route.ts"
click node_kv_store "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/kvRest.ts"
click node_rate_limit "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/rateLimit.ts"
click node_beta_sync_api "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/admin/sync-beta/route.ts"
click node_beta_crawler "https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/betaCrawler.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_movie_ui,node_movie_catalog_api,node_movie_service,node_movie_fallback,node_semantic_search_ui,node_search_api toneBlue
class node_rag_search,node_chat_ui,node_chat_api,node_mood,node_seat_recommender,node_groq toneAmber
class node_booking_ui,node_seat_hold_hook,node_booking_client,node_seats_api,node_booking_api,node_booking_service,node_ticket_ui,node_ticket_api,node_showtimes_api toneMint
class node_scanner_ui,node_checkin_api,node_admin_ui,node_admin_showtimes_api,node_beta_sync_api,node_beta_crawler toneRose
class node_seat_store,node_showtime_store,node_ticket_store,node_admin_auth,node_kv_store,node_rate_limit,node_visitor toneIndigo
```

## Components

### Movie discovery

- [Movie browsing UI](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Movie catalog API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/movies/route.ts): `src/app/api/movies/route.ts`
- [Movie service](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/movieService.ts): `src/lib/movieService.ts`
- [Mock movie data](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/mockData.ts): `src/lib/mockData.ts`
- [Semantic search UI](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/SemanticSearchModal.tsx): `src/components/SemanticSearchModal.tsx`
- [Search API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/search/route.ts): `src/app/api/search/route.ts`

### AI and search

- [Semantic RAG service](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/hfRagService.ts): `src/lib/hfRagService.ts`
- [AI chat widget](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/AiChatWidget.tsx): `src/components/AiChatWidget.tsx`
- [Chat API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Mood detection](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/moodDetector.ts): `src/lib/moodDetector.ts`
- [Seat recommendations](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/seatRecommender.ts): `src/lib/seatRecommender.ts`
- **Groq AI service**

### Booking and tickets

- [Booking modal](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/BookingModal.tsx): `src/components/BookingModal.tsx`
- [Seat-hold hook](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/hooks/useSeatHold.ts): `src/hooks/useSeatHold.ts`
- [Booking API client](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingClient.ts): `src/lib/bookingClient.ts`
- [Seat holds API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/seats/route.ts): `src/app/api/seats/route.ts`
- [Booking API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/booking/route.ts): `src/app/api/booking/route.ts`
- [Booking service](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/bookingService.ts): `src/lib/bookingService.ts`
- [My tickets UI](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/components/MyTicketsModal.tsx): `src/components/MyTicketsModal.tsx`
- [Ticket lookup API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/tickets/%5Bid%5D/route.ts): `src/app/api/tickets/[id]/route.ts`
- [Showtimes API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/showtimes/route.ts): `src/app/api/showtimes/route.ts`

### Cinema operations

- [Ticket scanner](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/scanner/page.tsx): `src/app/scanner/page.tsx`
- [Check-in API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/tickets/check-in/route.ts): `src/app/api/tickets/check-in/route.ts`
- [Admin dashboard](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [Admin showtimes API](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/admin/showtimes/route.ts): `src/app/api/admin/showtimes/route.ts`
- [Beta schedule sync](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/app/api/admin/sync-beta/route.ts): `src/app/api/admin/sync-beta/route.ts`
- [Beta schedule crawler](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/betaCrawler.ts): `src/lib/betaCrawler.ts`

### Shared services

- [Seat store](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/seatStore.ts): `src/lib/seatStore.ts`
- [Showtime store](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/showtimeStore.ts): `src/lib/showtimeStore.ts`
- [Ticket store](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/ticketStore.ts): `src/lib/ticketStore.ts`
- [Admin authentication](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/adminAuth.ts): `src/lib/adminAuth.ts`
- [KV REST adapter](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/kvRest.ts): `src/lib/kvRest.ts`
- [Rate limiting](https://github.com/nguyenchidung2007real-hue/cinecode/blob/main/src/lib/rateLimit.ts): `src/lib/rateLimit.ts`

### Other components

- **Moviegoer**

## Connections

- Moviegoer → Movie browsing UI: browses movies
- Moviegoer → Booking modal: books tickets
- Movie catalog API → Movie service: loads movies (evidence: `src/app/api/movies/route.ts`)
- Movie service → Mock movie data: falls back to (evidence: `src/lib/movieService.ts`)
- Movie service → Groq AI service
- Semantic search UI → Search API: searches movies
- Search API → Movie service: loads catalog (evidence: `src/app/api/search/route.ts`)
- Search API → Semantic RAG service: ranks results (evidence: `src/app/api/search/route.ts`)
- AI chat widget → Chat API: sends messages
- Chat API → Movie service: loads catalog (evidence: `src/app/api/chat/route.ts`)
- Chat API → Semantic RAG service: builds context (evidence: `src/app/api/chat/route.ts`)
- Chat API → Mood detection: detects mood (evidence: `src/app/api/chat/route.ts`)
- Chat API → Seat recommendations: extracts party size (evidence: `src/app/api/chat/route.ts`)
- Chat API → Groq AI service: streams completion
- Booking modal → Seat-hold hook: manages seat holds (evidence: `src/components/BookingModal.tsx`)
- Booking modal → Booking API client: calls booking API (evidence: `src/components/BookingModal.tsx`)
- Seat-hold hook → Booking API client: requests seat holds (evidence: `src/hooks/useSeatHold.ts`)
- Booking API client → Seat holds API: calls seat endpoint (evidence: `src/lib/bookingClient.ts`)
- Booking API client → Booking API: submits booking (evidence: `src/lib/bookingClient.ts`)
- Seat holds API → Booking service: holds or releases (evidence: `src/app/api/seats/route.ts`)
- Seat holds API → Seat store: reads seat status (evidence: `src/app/api/seats/route.ts`)
- Booking API → Booking service: processes booking (evidence: `src/app/api/booking/route.ts`)
- Booking service → Seat store: holds seats (evidence: `src/lib/bookingService.ts`)
- Booking service → Showtime store: loads showtime (evidence: `src/lib/bookingService.ts`)
- Booking service → Ticket store: creates ticket (evidence: `src/lib/bookingService.ts`)
- Showtimes API → Showtime store: loads showtimes (evidence: `src/app/api/showtimes/route.ts`)
- My tickets UI → Ticket lookup API: looks up tickets
- Ticket lookup API → Ticket store: reads ticket (evidence: `src/app/api/tickets/[id]/route.ts`)
- Ticket scanner → Check-in API: checks in ticket
- Check-in API → Ticket store: validates ticket (evidence: `src/app/api/tickets/check-in/route.ts`)
- Admin dashboard → Admin showtimes API: manages showtimes
- Admin showtimes API → Admin authentication: checks authorization (evidence: `src/app/api/admin/showtimes/route.ts`)
- Admin showtimes API → Showtime store: updates showtimes (evidence: `src/app/api/admin/showtimes/route.ts`)
- Beta schedule sync → Beta schedule crawler: fetches schedules (evidence: `src/app/api/admin/sync-beta/route.ts`)
- Rate limiting → KV REST adapter: uses KV adapter (evidence: `src/lib/rateLimit.ts`)
- Seat store → KV REST adapter: uses KV adapter (evidence: `src/lib/seatStore.ts`)
- Showtime store → KV REST adapter: uses KV adapter (evidence: `src/lib/showtimeStore.ts`)
- Ticket store → KV REST adapter: uses KV adapter (evidence: `src/lib/ticketStore.ts`)