# intellectdaksh/bnb26_terminal_maharashtra_round architecture

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

- Interactive diagram: https://gitdiagram.com/intellectdaksh/bnb26_terminal_maharashtra_round
- Repository: https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round

## Overview

Fair Drop is a ticket-drop frontend with participant registration, queueing, time-limited reservation and confirmation, alongside an admin console for operating and monitoring drops. The participant journey is driven by server-reported entry status, with realtime updates and refreshes informing screen routing; API mode selects live or mock behavior. The README also documents bot-defense and FIFO-versus-protected allocation simulation. Those capabilities are represented, but details of unsampled implementations are necessarily limited to documented scope.

Main entry points: [`lib/api/index.ts`](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/index.ts) (API mode selector), [`lib/state/JourneyProvider.tsx`](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/state/JourneyProvider.tsx) (Journey state), [`app/(site)/events/[id]/register/page.tsx`](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/register/page.tsx) (Registration), [`lib/api/mock.ts`](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/mock.ts) (Mock API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_participant["Participant journey"]
  node_landing["Drop discovery<br/>[page.tsx]"]
  node_events["Event catalog<br/>[page.tsx]"]
  node_event["Event details<br/>[page.tsx]"]
  node_registration["Registration<br/>[page.tsx]"]
  node_queue["Queue status<br/>[page.tsx]"]
  node_reservation["Seat reservation<br/>[page.tsx]"]
  node_confirmation["Confirmation<br/>[page.tsx]"]
  node_tickets["Ticket access<br/>[page.tsx]"]
end

subgraph group_operations["Admin operations"]
  node_admin["Drop dashboard<br/>[page.tsx]"]
  node_admin_queue["Queue operations<br/>[page.tsx]"]
  node_admin_reservations["Reservation oversight<br/>[page.tsx]"]
  node_admin_security["Security controls<br/>[page.tsx]"]
  node_admin_traffic["Traffic analytics<br/>[page.tsx]"]
  node_admin_settings["Drop settings<br/>[page.tsx]"]
end

subgraph group_runtime["API and journey runtime"]
  node_journey["Journey routing<br/>[journey.ts]"]
  node_journey_provider["Journey state"]
  node_contracts["API contracts<br/>[index.ts]"]
  node_api_select["API mode selector<br/>[index.ts]"]
  node_live_api["Live API<br/>[live.ts]"]
  node_mock_api["Mock API<br/>[mock.ts]"]
  node_catalog["Mock event catalog<br/>[catalog.ts]"]
  node_realtime["Realtime updates<br/>[index.ts]"]
  node_allocation["Allocation simulation<br/>[index.ts]"]
  node_time["Time utilities<br/>[index.ts]"]
end

subgraph group_identity["Identity and protection"]
  node_auth["Sign-in and roles<br/>[auth.ts]"]
  node_supabase["Supabase browser client<br/>[client.ts]"]
  node_turnstile["Bot challenge endpoint<br/>[route.ts]"]
end

node_participant(("Participant"))

node_participant -->|"browses"| node_landing
node_landing -->|"opens catalog"| node_events
node_events -->|"opens drop"| node_event
node_event -->|"starts entry"| node_registration
node_registration -->|"signs in"| node_auth
node_registration -->|"submits entry"| node_api_select
node_registration -->|"sets entry status"| node_journey_provider
node_journey_provider -->|"reconciles status"| node_journey
node_journey_provider -->|"fetches entry and event"| node_api_select
node_journey_provider -->|"subscribes to updates"| node_realtime
node_queue -->|"reads journey"| node_journey_provider
node_reservation -->|"confirms reservation"| node_api_select
node_reservation -->|"updates entry status"| node_journey_provider
node_confirmation -->|"reads journey"| node_journey_provider
node_tickets -->|"loads ticket entries"| node_api_select
node_api_select -->|"selects live mode"| node_live_api
node_api_select -->|"selects mock mode"| node_mock_api
node_live_api -->|"validates payloads"| node_contracts
node_mock_api -->|"uses schemas"| node_contracts
node_mock_api -->|"loads demo events"| node_catalog
node_mock_api -->|"simulates allocation"| node_allocation
node_realtime -->|"uses API mode"| node_api_select
node_realtime -->|"uses live transport"| node_live_api
node_admin -->|"loads operations data"| node_api_select
node_admin_queue -->|"operates queue"| node_api_select
node_admin_queue -->|"shows allocation model"| node_allocation
node_admin_reservations -->|"loads reservations"| node_api_select
node_admin_security -->|"loads security data"| node_api_select
node_admin_traffic -->|"loads traffic data"| node_api_select
node_admin_settings -->|"updates settings"| node_api_select
node_auth -->|"uses browser auth"| node_supabase
node_live_api -->|"gets access token"| node_supabase
node_turnstile -.->|"supports bot checks"| node_participant
node_reservation -.->|"uses expiry timing"| node_time

click node_landing "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/page.tsx"
click node_events "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/page.tsx"
click node_event "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/page.tsx"
click node_registration "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/register/page.tsx"
click node_queue "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/queue/page.tsx"
click node_reservation "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/reservation/page.tsx"
click node_confirmation "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/confirmed/page.tsx"
click node_tickets "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/my-tickets/page.tsx"
click node_journey "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/state/journey.ts"
click node_journey_provider "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/state/JourneyProvider.tsx"
click node_contracts "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/contracts/index.ts"
click node_api_select "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/index.ts"
click node_live_api "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/live.ts"
click node_mock_api "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/mock.ts"
click node_catalog "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/catalog.ts"
click node_realtime "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/realtime/index.ts"
click node_allocation "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/sim/index.ts"
click node_admin "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/page.tsx"
click node_admin_queue "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/queue/page.tsx"
click node_admin_reservations "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/reservations/page.tsx"
click node_admin_security "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/security/page.tsx"
click node_admin_traffic "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/traffic/page.tsx"
click node_admin_settings "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/settings/page.tsx"
click node_auth "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/auth.ts"
click node_supabase "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/supabase/client.ts"
click node_turnstile "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/api/turnstile/route.ts"
click node_time "https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/time/index.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_landing,node_events,node_event,node_registration,node_queue,node_reservation,node_confirmation,node_tickets toneBlue
class node_admin,node_admin_queue,node_admin_reservations,node_admin_security,node_admin_traffic,node_admin_settings toneAmber
class node_journey,node_journey_provider,node_contracts,node_api_select,node_live_api,node_mock_api,node_catalog,node_realtime,node_allocation,node_time toneMint
class node_auth,node_supabase,node_turnstile toneRose
class node_participant toneIndigo
```

## Components

### Participant journey

- [Drop discovery](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/page.tsx): `app/(site)/page.tsx`
- [Event catalog](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/page.tsx): `app/(site)/events/page.tsx`
- [Event details](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/page.tsx): `app/(site)/events/[id]/page.tsx`
- [Registration](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/register/page.tsx): `app/(site)/events/[id]/register/page.tsx`
- [Queue status](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/queue/page.tsx): `app/(site)/events/[id]/queue/page.tsx`
- [Seat reservation](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/reservation/page.tsx): `app/(site)/events/[id]/reservation/page.tsx`
- [Confirmation](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/events/%5Bid%5D/confirmed/page.tsx): `app/(site)/events/[id]/confirmed/page.tsx`
- [Ticket access](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/(site)/my-tickets/page.tsx): `app/(site)/my-tickets/page.tsx`

### Admin operations

- [Drop dashboard](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/page.tsx): `app/admin/page.tsx`
- [Queue operations](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/queue/page.tsx): `app/admin/queue/page.tsx`
- [Reservation oversight](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/reservations/page.tsx): `app/admin/reservations/page.tsx`
- [Security controls](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/security/page.tsx): `app/admin/security/page.tsx`
- [Traffic analytics](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/traffic/page.tsx): `app/admin/traffic/page.tsx`
- [Drop settings](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/admin/settings/page.tsx): `app/admin/settings/page.tsx`

### API and journey runtime

- [Journey routing](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/state/journey.ts): `lib/state/journey.ts`
- [Journey state](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/state/JourneyProvider.tsx): `lib/state/JourneyProvider.tsx`
- [API contracts](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/contracts/index.ts): `lib/contracts/index.ts`
- [API mode selector](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/index.ts): `lib/api/index.ts`
- [Live API](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/live.ts): `lib/api/live.ts`
- [Mock API](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/mock.ts): `lib/api/mock.ts`
- [Mock event catalog](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/api/catalog.ts): `lib/api/catalog.ts`
- [Realtime updates](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/realtime/index.ts): `lib/realtime/index.ts`
- [Allocation simulation](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/sim/index.ts): `lib/sim/index.ts`
- [Time utilities](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/time/index.ts): `lib/time/index.ts`

### Identity and protection

- [Sign-in and roles](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/auth.ts): `lib/auth.ts`
- [Supabase browser client](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/lib/supabase/client.ts): `lib/supabase/client.ts`
- [Bot challenge endpoint](https://github.com/intellectdaksh/bnb26_terminal_maharashtra_round/blob/Frontend/app/api/turnstile/route.ts): `app/api/turnstile/route.ts`

### Other components

- **Participant**

## Connections

- Participant → Drop discovery: browses (evidence: `README.md`)
- Drop discovery → Event catalog: opens catalog (evidence: `app/(site)/page.tsx`)
- Event catalog → Event details: opens drop (evidence: `app/(site)/events/page.tsx`)
- Event details → Registration: starts entry
- Registration → Sign-in and roles: signs in (evidence: `app/(site)/events/[id]/register/page.tsx`)
- Registration → API mode selector: submits entry (evidence: `app/(site)/events/[id]/register/page.tsx`)
- Registration → Journey state: sets entry status (evidence: `app/(site)/events/[id]/register/page.tsx`)
- Journey state → Journey routing: reconciles status (evidence: `lib/state/JourneyProvider.tsx`)
- Journey state → API mode selector: fetches entry and event (evidence: `lib/state/JourneyProvider.tsx`)
- Journey state → Realtime updates: subscribes to updates (evidence: `lib/state/JourneyProvider.tsx`)
- Queue status → Journey state: reads journey (evidence: `app/(site)/events/[id]/queue/page.tsx`)
- Seat reservation → API mode selector: confirms reservation (evidence: `app/(site)/events/[id]/reservation/page.tsx`)
- Seat reservation → Journey state: updates entry status (evidence: `app/(site)/events/[id]/reservation/page.tsx`)
- Confirmation → Journey state: reads journey (evidence: `app/(site)/events/[id]/confirmed/page.tsx`)
- Ticket access → API mode selector: loads ticket entries (evidence: `app/(site)/my-tickets/page.tsx`)
- API mode selector → Live API: selects live mode (evidence: `lib/api/index.ts`)
- API mode selector → Mock API: selects mock mode (evidence: `lib/api/index.ts`)
- Live API → API contracts: validates payloads (evidence: `lib/api/live.ts`)
- Mock API → API contracts: uses schemas (evidence: `lib/api/mock.ts`)
- Mock API → Mock event catalog: loads demo events (evidence: `lib/api/mock.ts`)
- Mock API → Allocation simulation: simulates allocation (evidence: `lib/api/mock.ts`)
- Realtime updates → API mode selector: uses API mode (evidence: `lib/realtime/index.ts`)
- Realtime updates → Live API: uses live transport (evidence: `lib/realtime/index.ts`)
- Drop dashboard → API mode selector: loads operations data (evidence: `app/admin/page.tsx`)
- Queue operations → API mode selector: operates queue (evidence: `app/admin/queue/page.tsx`)
- Queue operations → Allocation simulation: shows allocation model (evidence: `app/admin/queue/page.tsx`)
- Reservation oversight → API mode selector: loads reservations (evidence: `app/admin/reservations/page.tsx`)
- Security controls → API mode selector: loads security data (evidence: `app/admin/security/page.tsx`)
- Traffic analytics → API mode selector: loads traffic data (evidence: `app/admin/traffic/page.tsx`)
- Drop settings → API mode selector: updates settings (evidence: `app/admin/settings/page.tsx`)
- Sign-in and roles → Supabase browser client: uses browser auth (evidence: `lib/auth.ts`)
- Live API → Supabase browser client: gets access token (evidence: `lib/api/live.ts`)
- Bot challenge endpoint → Participant: supports bot checks
- Seat reservation → Time utilities: uses expiry timing
