Internal engineering brief · confidential

AI × Nightclub Platform — Engineering Brief

Pre-read for the offshore engineering team · Phases 0–2 · Prepared by EXPLACE Inc. (Japan)

01What we are building

The Client operates nightclubs. Today nobody has data on what happens on the floor while guests are inside the venue — what they want to hear, what makes them stay longer, what makes them buy another drink. Ticketing and entry are digitised; the hours in between are not.

Phase 1 builds exactly one thing: a system that captures what guests actually want, as numbers. Audio and video production — the visually impressive part — comes later, and only after the Phase 1 data exists.

Deployment starts with one flagship venue, but the system is designed as a multi-tenant group platform from day one. Adding venues later must not require re-architecting. This is a hard requirement, not an aspiration.

02Phase structure

Target start: late August 2026. Phases 0 and 1 are being proposed as a single decision, because Phase 0 alone produces no guest data and therefore no basis for the next decision.

03Phase 1 scope: in and out

In scope

Out of scope for Phase 1

• Automatic track playback or audio streaming of any kind
• Audio output to DJ mixers or audio interfaces
• BPM sync, crossfade, automatic mixing
• Avatar-DJ video generation or switching
• Video output to LED walls (HDMI / NDI / OBS / Novastar etc.)
• Lighting control and show-control system integration
• Procurement or installation of on-site PCs, audio interfaces or GPU machines

04Use cases

05Music data: the three-layer model

This is the part most likely to be challenged by technical reviewers, and the part you need to understand best.

Layer 1 — runtime data from DJ hardware

Current CDJ hardware publishes now-playing, BPM and beat information on the LAN. The Client’s AV affiliate already owns this equipment and the bridge software, so no new hardware purchase is required; we receive and record only.

Fallback chain (must be designed in from the start)

(a) gives the richest show; (c) still delivers usable video sync. No single path may be a hard dependency.

Layer 2 — track features from rekordbox XML

rekordbox can export the entire collection as XML. This is an officially documented format, and it already contains everything we need for candidate selection.

What the XML does not contain: there is no field equivalent to energy, mood or danceability. We fill that gap using rekordbox MyTag / colour / comment conventions, or manual tagging. At Phase 1 scale manual tagging is both fastest and most accurate. Custom audio analysis can be added later; we do not build it in Phase 1.

Layer 3 — guest input

• Purpose is autocomplete and name resolution only (treating alternate spellings of the same artist as one entity).
• Search and metadata lookup remain available from public catalog APIs. If one becomes unavailable it is replaceable, and in the worst case free-text input alone still works.
• This layer must never become critical path. Design it as replaceable from the start.

06The irreversible logging layer

Phase 1 does not run any trained model. But several preconditions for Phase 1.5 cannot be recovered retroactively if we fail to build them into Phase 1. If we miss these, Phase 1.5-a ends up with “we have data, but it is unusable” — the worst possible outcome.

Mandatory in Phase 1 (no separate line item — absorbed into the data platform)

Valuable to pull forward — see §11

07Data model

Phase 1 tables. Names are indicative; final naming is fixed in Phase 0.

users_ref        : anon_id, partner_user_id (reference only), membership_status, created_at
sessions         : id, venue_id, event_id, started_at, ended_at, operator_id
survey_questions : id, session_id/venue_id, type, body, options, is_active, order
survey_answers   : id, session_id, anon_id, question_id, value, answered_at
votes            : id, session_id, anon_id, candidate_track_id, voted_at
track_candidates : id, session_id, track_ref, source, score, rank, proposed_at
proposal_results : id, candidate_id, adopted(bool), adopted_at    <- key input for 1.5-a
activity_logs    : id, session_id, anon_id, event_type, payload(jsonb), occurred_at
venues           : id, name, partner_venue_id, timezone, config(jsonb)

-- learning-preparation layer (see section 06) --
track_catalog    : id, title, artist, isrc, source, added_at
track_features   : track_id, bpm, key, energy, genre_tags, era, source, confidence
impressions      : id, session_id, anon_id, candidate_id, shown_at, position   <- L2
session_context  : session_id, weekday, time_slot, event_type, headcount_band, weather
shadow_runs      : id, session_id, algo_name, algo_version, output(jsonb), ran_at <- never displayed

-- defined now, activated in Phase 1.5 --
output_devices     : id, venue_id, type(audio/video), status, connected_at
session_output_map : session_id, audio_device_id, video_device_id
visual_assets      : id, name, path, genre_tags, bpm_range, rights_note

The output-layer tables are defined but not implemented in Phase 1. Keep the connection points in the schema; do not build the functionality behind them yet.

08Privacy and retention

• Our side holds an anonymous ID (anon_id) and a reference token only. Names, contact details and similar personal data stay inside the Partner App.
• Retention is two-tier — this distinction is essential:

Data location: personal data handling and storage region are governed by the agreed policy for this project. Confirm with the Japan-side PM before selecting any region, managed service or third-party processor. Do not assume the default region of your cloud account is acceptable.

09System architecture (Phase 1)

Guest smartphone ──(QR / deep link)──▶  Web (Next.js)
                                          │
                                          ▼
                                Backend API (Node.js / Python)
                                  ├── auth: Partner App token verification (RS256)
                                  ├── preference / vote / behaviour logging
                                  └── rule-based track proposal
                                          │
                        ┌─────────────────┼─────────────────┐
                        ▼                 ▼                 ▼
                 Admin console      Data platform      Partner App API
                (shows proposals)   (DB / aggregation)  (member & log sync)
                                    (BI / CSV export)

  * Audio output, LED output and DJ-hardware integration are Phase 1.5.
    Connection points are designed now; nothing is wired in this phase.

10Partner App integration

Required from Phase 1. This is a known schedule risk: it depends on the Client’s own app team.

• Auth: OAuth2 / JWT (1-hour expiry), verified with RS256 public-key signature
• Transport: HTTPS (TLS 1.3)
• Sync: user info on demand; subscription status every 5 minutes
• Versioning: /v1/… prefixed endpoints; breaking changes require advance notice
• Failure behaviour: if token refresh fails, the guest continues as an anonymous guest. The venue must never stop because an API is down

11Optional parallel workstreams

Two workstreams are offered as optional and run in parallel with Phase 1. They are optional commercially, but if they are ordered, they must start with Phase 1 — not after it.

Engineering notes

• Both are independent of guest data, so they can start on day one and are not blocked by Phase 1 progress.
• Option B’s logs feed Option A’s evaluation harness — “what was actually played” becomes ground truth for comparing approaches. Design the schemas so this join is trivial.
• Option B doubles as risk reduction: it verifies whether the (unofficial) hardware protocol actually works at this venue, before the expensive Phase 1.5-b implementation is ordered. If it turns out not to be readable, that is a valid and valuable result — it changes the 1.5-b design at the cheapest possible moment.
• Option A reduces later effort: with a feature store already in place, the AI portion of Phase 1.5-b shrinks substantially.

12KPI targets

Phase 1 — does data capture and operation work?

Phase 1.5-b / Phase 2 — show quality

13Risks and fallbacks

Phase 1

Phase 1.5 and later

14Deliverables

Source code and design assets are delivered to the Client. Write code and documentation on the assumption that another team may take it over.

15Hardware

Phase 1: no additional hardware. It runs on guests’ own smartphones and the venue’s existing network and PC.

16Open questions (to be fixed in Phase 0)

• Which venue is the flagship deployment, and what audio/video/lighting systems are already installed (show-control system present? LED resolution and input paths?)
• Whether the Partner App can be modified, and who owns that work (in-house or external)
• The exact responsibility line with the Client’s AV affiliate
• Existing equipment details: DJ hardware models, LAN topology, bridge software version
• Consent wording that explicitly includes future analysis and algorithm improvement (cannot be obtained retroactively)
• Method for building track features (manual tagging / own extraction / commercial API)
• Number of languages supported in the guest UI at launch (drives effort — do not assume)
• Personal data handling policy, storage region and legal review process
• Start month, avoiding the Client’s peak season and major festival periods

17Glossary

18How to work with this brief