Architecture

Overview

Neverline utilizes a monorepo architecture comprising a React frontend suite, a Fastify REST API, and Supabase for underlying data structuring and resilient authentication.

neverline/
├── apps/client/        # React + Vite (customer PWA)
├── apps/dashboard/     # React + Vite (admin dashboard)
├── apps/mobile-access/ # Expo + React Native (staff mobile app)
├── services/api/       # Fastify REST API
├── packages/shared/    # Shared types, schemas, constants
├── supabase/           # Migrations, seed data
└── docs/manual/        # VitePress documentation

Frontend — Customer PWA (apps/client)

• React with TypeScript and Vite
• Mobile-first Progressive Web App
• Framer Motion for animations

Key Routes

Path	Component	Description
/join/:queueId	JoinPage	Queue joining form
/status	StatusPage	Waiting screen with position, chat, wayfinding
/action	ActionPage	Deep-link action handler
/feedback	FeedbackPage	Post-service feedback
/plan	PlanArrivalPage	Pre-arrival time window picker

Key Components

Component	Feature
ChatView	In-app two-way chat with staff
WayfindingView	Arrival guidance with map + overrides
AlternativesCard	Smart queue alternative suggestions
AnnouncementBanner	Real-time announcement display
AwayModeTimer	Away countdown timer
LatePickerSheet	ETA picker for running late
ReturnPickerSheet	Return from away picker
CancelConfirmDialog	Queue leave confirmation

Frontend — Admin Dashboard (apps/dashboard)

• React with TypeScript and Vite
• React Router for client-side routing
• Recharts for analytics charts
• Framer Motion for queue view animations

Dashboard Routes

Path	Component	Description
/login	LoginPage	Staff authentication
/admin	AdminLayout	Dashboard shell with sidebar
/admin/dashboard	DashboardPage	Overview KPIs
/admin/queues	QueuesPage	Queue management (4 view modes)
/admin/queues/:id	QueueDetailPage	Queue detail + policy settings
/admin/analytics	AnalyticsPage	History & statistics
/admin/customers	CustomersPage	Customer list
/admin/announcements	AnnouncementsPage	Announcement CRUD
/admin/forecast	ForecastPage	Planned arrival forecasting
/admin/locations	LocationsPage	Location & wayfinding management
/admin/chat	ChatInbox	Staff chat inbox
/admin/settings	SettingsPage	Organization settings

• AuthContext — Supabase session and user profile
• LanguageContext — FI/EN translations (admin)
• ThemeContext — Light/dark mode
• ServingContext — Active serving sessions for the current staff member

Frontend — Staff Mobile Scanner (apps/mobile-access)

• React Native + Expo
• Expo Router for file-based routing
• Engineered specifically for staff operators managing rapid venue ingress
• Native camera integration for QR/Barcode ticket verification

Key Features

• High-performance barcode scanning
• Direct connection to the Fastify API (via LAN IP in development)
• Native haptic feedback upon successful verification

Backend (services/api)

• Fastify with TypeScript
• Routes organized by domain
• Supabase client for database access (service role key)

Routes

File	Purpose
routes/queues.ts	Queue CRUD, status management, alternatives
routes/sessions.ts	Join, call, complete, requeue, away, late, return
routes/analytics.ts	Analytics summary endpoint
routes/announcements.ts	Announcement CRUD (scoped)
routes/chat.ts	Chat thread and message endpoints
routes/locations.ts	Location management, wayfinding overrides
routes/planned-arrivals.ts	Pre-arrival signals, forecast, conversion

Services

File	Purpose
services/queue-engine.ts	Core queue logic, policy enforcement, alternatives, jump detection
services/notification-trigger.ts	Event-driven notification dispatch
services/notification-templates.ts	SMS/push message templates
services/timer-processor.ts	Background expired-timer scanner
services/event-emitter.ts	Queue event emission
services/position-manager.ts	Queue position recalculation
services/wait-time-estimator.ts	Wait time algorithm

Libraries

File	Purpose
lib/deep-links.ts	HMAC-signed action URL generation/verification
lib/wait-estimate.ts	Wait time estimation algorithm
lib/crypto.ts	AES-256-GCM PII encryption
lib/errors.ts	Structured error handling

Database

PostgreSQL via Supabase with the following tables:

Core Tables

Table	Purpose
organizations	Tenant isolation
queues	Queue definitions, settings, and policies
queue_sessions	Individual customer visits
staff_profiles	Staff user metadata

Feature Tables

Table	Purpose
announcements	Scoped announcements (org/location/queue)
chat_threads	Chat conversation threads
chat_messages	Individual chat messages
planned_arrivals	Pre-arrival signals
service_locations	Physical venue details
wayfinding_overrides	Temporary navigation alerts
queue_alternatives	Cross-queue alternative mappings

System Tables

Table	Purpose
webhook_subscriptions	Webhook configuration
api_keys	API key management
feedback	Customer feedback
staff_queue_assignments	Staff-to-queue access control

Row-Level Security (RLS) policies ensure organization-level data isolation.

Wait Time Estimation

The wait time algorithm (in lib/wait-estimate.ts) computes:

1. Weighted average service time from completed sessions:
   • 70% from sessions in the same 2-hour time window
   • 30% from all sessions in the period
   • Looks at 7 days, falls back to 30 days, then to queue.avg_service_time_s
2. Active server count from sessions with status = 'serving'
3. Per-person estimate: (peopleAhead × avgServiceTime) / activeServers