# Technical Design

## Current prototype shape

The current deliverable is a dependency-free front-end prototype so the concept can be reviewed quickly. It includes the core translation logic in client-side JavaScript and a mock venue dataset.

## Recommended production architecture

### Clients

- iOS app
- Android app
- Responsive web app
- Venue business console

### Backend services

- API gateway
- Identity and consent service
- Location ingestion service
- Aggregation and privacy rules engine
- Venue catalog service
- Venue specials service
- Notification service
- Analytics pipeline

### Storage

- Relational database for users, venues, permissions, and specials
- Time-series or event store for anonymous location pings
- Cache for hot venue summaries
- Data warehouse for longer-term analysis

## Core domain model

### User

- `id`
- `birth_date`
- `sex`
- `relationship_status`
- `email`
- `pace_preference`
- `consent_foreground_location`
- `consent_background_location`
- `created_at`

### Venue

- `id`
- `name`
- `category`
- `lat`
- `lng`
- `timezone`
- `hours_json`
- `status`

### Anonymous presence event

- `venue_id`
- `hashed_user_id`
- `event_time`
- `confidence_score`
- `foreground_or_background`

### Crowd pulse

- `venue_id`
- `window_start`
- `window_end`
- `active_user_count`
- `age_band_distribution`
- `relationship_distribution`
- `energy_score`
- `crowd_score`
- `signal_strength`
- `translation_version`

### Crowd vote

- `venue_id`
- `hashed_user_id`
- `vote_label`
- `created_at`

### Venue special

- `venue_id`
- `title`
- `description`
- `start_time`
- `end_time`
- `approval_status`

## Rules engine requirements

The aggregation service should:

- Group users into age bands before presentation logic.
- Enforce a minimum sample threshold before any segment output is eligible.
- Require a dominant share of at least 55% before age or relationship summaries appear.
- Suppress outputs that could reveal too much about a thin sample.
- Distinguish between live, prompt-verified, and historical output sources.
- Write an explanation payload for the client, not just a label.

## API outline

### `GET /venues/nearby`

Returns a list of nearby venues and translated venue summaries.

Suggested response fields:

- `venue`
- `distance_miles`
- `signal`
- `updated_at`
- `social_vibe`
- `crowd_size`
- `age_summary`
- `hours`
- `deals`

### `POST /crowd-votes`

Accepts a lightweight crowd label vote when a venue has thin live signal.

### `GET /venues/{id}/details`

Returns deeper venue context, explanations, and historical patterns.

### `POST /business/specials`

Allows approved venue operators to update specials and featured items.

## Delivery phases

### Phase 1

- Finalize signal rules
- Build venue catalog
- Build web/mobile card experience
- Launch anonymous data collection with consent

### Phase 2

- Add map experience
- Add business dashboard
- Improve notifications and retention campaigns

### Phase 3

- Expand to non-nightlife verticals
- Add recommendation engine
- Add partner integrations