// uuid_generator

GYST UUID v8

Generate and decode GYST UUID v8 identifiers. Every entity in PopSoc is addressed by a 128-bit UUID with embedded type, domain, and timestamp.

View Full Specification (Gist)GYST Manager

UUID Generator

UUID Decoder

Bit Structure (128 bits)

0-11
12-23
24-47
48-51
52-55
56-127
Entity
12 bits
Event
12 bits
Timestamp
24 bits
V
4b
Var
4b
Random
72 bits
Example UUID:
020abc123456-78-89ab-cdef-0123456789ab

Key Features

Entity Typing
First 12 bits encode entity type (user, event, vendor, etc.)
Event Scoping
Bits 12-23 contain event hash for hierarchical grouping
Temporal Ordering
24-bit timestamp enables chronological sorting
RFC Compliant
Version 8 (custom) per RFC 4122, variant bits preserved
Collision Resistant
72 random bits provide sufficient uniqueness
Parseable
Extract metadata without database lookup

Entity Type Codes

user0x01016

User accounts and profiles

AttendeesOrganizersVendors
event0x02032

Root GYST event containers

Wine FestivalGolf TournamentConference
canvas0x03048

Visual canvas/page layouts

Event MapSchedule ViewVendor Grid
view0x04064

Saved view configurations

Map ViewList ViewTimeline
vendor0x05080

Vendor/sublicant entities

WineriesFood TrucksSponsors
product0x06096

Products and offerings

TicketsMerchandisePackages
session0x070112

Scheduled sessions/talks

KeynotesWorkshopsPanels
channel0x080128

Communication channels

AnnouncementsChat RoomsAlerts
collection0x090144

Grouped entity collections

FavoritesSaved EventsWatchlist
message0x100256

Individual messages

NotificationsAlertsUpdates

Usage Example

import { generateUUID, parseUUID } from '@/lib/uuid'

// Generate UUIDs for different entity types
const eventUuid = generateUUID('event', 'wine-fest-2026')
const vendorUuid = generateUUID('vendor', 'wine-fest-2026', eventUuid)
const userUuid = generateUUID('user')

// Parse a UUID to extract metadata
const parsed = parseUUID(vendorUuid)
console.log(parsed)
// {
//   entityType: 'vendor',
//   entityCode: 80,
//   eventHash: 1234,
//   timestamp: 12345678,
//   isValid: true
// }

// Check if entities belong to same event
const sameEvent = parseUUID(vendorUuid).eventHash === parseUUID(eventUuid).eventHash

Implementation Notes

Event Hash Generation

The 12-bit event hash is derived from the event slug using a consistent hashing function. This allows all entities within an event to share the same event hash, enabling efficient filtering without joins.

Timestamp Precision

The 24-bit timestamp represents seconds since January 1, 2024. This provides a range of ~194 days at second precision, or can be scaled for longer ranges at reduced precision.

Parent-Child Relationships

Child entities (vendors, sessions) inherit the event hash from their parent, establishing a queryable hierarchy. The parent_uuid column provides explicit relationships for complex queries.

Database Indexing

Index on SUBSTR(uuid, 1, 3) for entity type queries, and SUBSTR(uuid, 4, 3) for event scoping. SQLite/Turso handles these efficiently.

Full Specification

The complete GYST UUID v8 protocol specification, including edge cases, migration guides, and language-specific implementations, is maintained as a GitHub Gist.

gist.github.com/SoMaCoSF/aabf2966a198b03de2434fab5e717d3a