Page 01 · v2
Glossary & data model
The source of truth for what track captures. Two entities, one capture grammar, one extensible tag system, and connections that let us learn from history.
One golden idea: "New session" and "log an event" are the same card — they differ only in which fields are primary and what they write to. Second idea: everything we capture should be groupable (tags + connections) so details auto-populate from what's already known.
1 · Entities
2 · Field states
3 · Tag system
4 · Connections & memory
5 · Session fields
6 · Money model
7 · Event fields
8 · Event catalog
9 · Mirrors
10 · Gates
11 · Media library
12 · Mental-game pulse
13 · Derived metrics
14 · Still open
15 · Term glossary
1 The two entities
| Entity | Captures | One-liner |
|---|---|---|
| Session | What the tournament is & how it ended | The container: title, venue/operator, format, money/chip config, structure, payouts, result — plus connections & tags. |
| Event | What happened at one instant | A timestamped row: money, a chip/field snapshot, a hand, a pulse, a note, media, visibility, tags. |
A session has many events. Live metrics ($/hr, stack-in-BB, ICM equity) are derived (§13) — never stored. Two satellite concepts hang off both: Media (§11) and Connections (§4).
2 Field kinds & the three states
Kinds: text select tags datetime money chips count number level hand media rating toggle ref meta.
| State | Meaning | Examples |
|---|---|---|
| Captured | Typed / picked by the player. | title, buy-in, your chips, players left, a hand. |
| Auto-generated | System fills it, stays editable & pins on edit (GR5), or a mirror applies it (GR6), or it's recalled from history/connections (§4). | fee = 20%·buy-in, entry = now, currency = your default, finish place from a payout, venue defaults recalled. |
| Derived | Computed on the fly, never stored. | net, ROI, $/hr, stack-in-BB, ICM equity, counts. |
4 Connections & entity memory new
Every session can connect to canonical pkr2go entities. All nullable — but even when null, we still remember and group so details auto-populate next time.
| Field | Kind | Links to | Notes |
|---|---|---|---|
| venue | text | — | what the player types ("The Tote, Collingwood") |
| venueId | ref | pkr2go venue directory | nullable; matched/confirmed when we recognise the venue |
| operator | text | — | the league/series operator running it |
| operatorId | ref | pkr2go operator directory | nullable; matched when known |
| pkr2goEventId | ref | pkr2go tournament/event | nullable; the actual scorekept event, if this session is a pkr2go game |
Why it matters — mass data & auto-populate
- Group similar events. Same venue / operator / recurring event → cluster sessions so we can summarise, compare, and spot patterns across many.
- Auto-populate from what's known. A recurring "Tuesday $80 at The Tote" already has currency, typical structure, buy-in, payouts — recall them so a new session is near-zero input.
- Don't reinvent the wheel. Reuse the existing pkr2go venue/operator/event directory rather than a parallel one.
New venue = silently remembered. When a player types a venue/operator we don't recognise, we auto-save it to their history behind the scenes (a soft entity). Next time it autocompletes and carries its learned defaults; if it later matches a canonical pkr2go entity, we link the
id — no re-entry, no duplicate.
5 Session fields
✱ = auto-generated (editable + pins). "Shows" = main card, behind More, or gated by a format: tag (§10). Money fields use the §6 convention.
| Field | Kind | Auto? | Default / source | Shows |
|---|---|---|---|---|
| id · createdAt | — | ✱ | generated | system |
| title | text | — | always | |
| venue · operator + ids | text · ref | ✱ | typed; ids matched from directory (§4) | always |
| pkr2goEventId | ref | ✱ | linked if it's a pkr2go game (§4) | More |
| format | select | MTT (Cash later) — see callout | always | |
| tags | tags | the §3 type:value set (incl. format:* capabilities) | always | |
| currency | select | ✱ | = your profile default | More |
| tourneyStart · entryTime | datetime | ✱ | paired; entry = now, tourneyStart = entry | entry always |
| endedAt · netHours | datetime · number | ✱ | set on end; netHours = entry→end − overnight | result |
| buyin | money | headline in-play amount (what folks see) | always | |
| buyinFee | money | ✱ | = 20%·buyin | inline, faint |
| buyinBounty | money | ✱ | = 50%·buyin (the KO split, see §6); else 0 | tag format:pko/mystery |
| buyinCost | money | derived | = buyin + buyinFee | inline, faint |
| reentry · reentryFee · reentryBounty · reentryCost | money | ✱ | default to the buyin set; cost derived | tag format:reentry |
| rebuy · rebuyFee · rebuyCost | money | ✱ | rebuy = buyin; cost derived | tag format:rebuy |
| addon · addonFee · addonCost | money | ✱ | addon = buyin; cost derived | tag format:addon |
| lastLongerBuyin | money | flat side-pool entry (no prizepool/fee split) | tag format:last-longer | |
| startingChips | chips | — | always | |
| rebuyChips · reentryChips · addonChips | chips | ✱ | rebuy/reentry chips = starting | by tag |
| reentriesCount · rebuysCount · addonsCount | count | ✱ | your own counts — from your events, editable (§13) | result |
| gtd · structure · payouts | number · meta | guarantee; blind ladder; prize ladder | More | |
| finishPlace · entrants | count | ✱ | mirrors from payout/bust & field snapshot (§9) | result |
| status | select | ✱ | planned · setup · live · busted · cashed · ended | always |
| pulse (start/end) | rating | A-game · energy · focus snapshot (§12) | More |
format vs tags:
format = the structural class (MTT now; Cash later changes the schema — blinds/sessions instead of buy-ins/places). Everything that used to be a "format tag" (re-entry, rebuy, PKO…) is now a format:* tag from §3. Cleaner and extensible.
6 Money model — one naming convention reworked
No more guessing "cost vs fee". For every entry action X ∈ {buyin, reentry, rebuy, addon}, the same four parts:
| Part | Always means |
|---|---|
| X | the headline in-play amount — what folks see / quote |
| Xfee | the fee / rake (auto = 20%·X, editable) |
| Xbounty | the bounty split inside X for KO formats (auto = 50%·X → 50/50; 0 otherwise). Prize-pool part = X − Xbounty. Informational — it's already inside X, not added on top. |
| Xcost (derived) | = X + Xfee — total cash out of pocket per bullet |
Worked examples
- Standard $100+$20: buyin 100 · buyinFee 20 · buyinBounty 0 · buyinCost 120.
- PKO "$150 + $15" 50/50: buyin 150 · buyinFee 15 · buyinBounty 75 (so 75 prize-pool + 75 bounty) · buyinCost 165.
Same rule for re-entry/rebuy/add-on. So: buyin + buyinFee = buyinCost, and bounty is a clearly-labelled split, never a mystery extra. Open to your naming — if you prefer buyinRake over buyinFee, say so and it's a one-line change here.
7 Event fields
| Field | Kind | Notes |
|---|---|---|
| id · sessionId | — | system |
| ts | datetime | absolute instant. Default now. Tail field. |
| type · category | — | one of §8; ✱ category derived from type |
| visibility | toggle | public · friends · private. Default per type. (friends needs the friend graph — see §14) |
| money | money | cost/income amount, session currency |
| breakKind | toggle | ✱ auto from the break→resume gap: overnight if it crosses local midnight or > 4h, else short. Editable. (threshold tunable — §14) |
| payload.chips | chips | your stack after this event |
| payload.playersLeft · totalEntries | count | paired; totalEntries → entrants |
| payload.chipsInPlay | count | ✱ two-way with entries: chipsInPlay ⇄ totalEntries·startingChips + rebuys·rebuyChips + addons·addonChips. Give one, get the other. |
| payload.level | level | { num, sb, bb, ante } |
| payload.rebuys · addons · reentries | counts | field-wide counters (everyone) — feed chips-in-play |
| payload.lastLongerLeft | count | players alive in the last-longer pool |
| payload.place | count | finishing place → finishPlace + status (§9) |
| hand | hand | { position, hole, board, action, result, potChips } |
| pulse | rating | { aGame, energy, focus } 1–5 (§12) |
| note | text | shareable per visibility. Tail field. |
| privateNote new | text | always player-only, regardless of visibility — your candid read / mental-hand-history. |
| media | media[] | attached photos — also live in the library (§11) |
| tags | tags | event:key, mind:tilt… (§3) |
Universal tail (every event card ends with): Media · Time (now) · Note · Private note · Visibility · Tags.
8 Event catalog — what each one shows
19 types. Key fields = the primary zone; the universal tail is implicit. Trigger: + the log sheet · footer a session action button · auto system. Lifecycle events can carry a place — there's no special "menu only" rule any more.
| Type | Cat. | Key fields shown | Default vis. | Auto-fill · gate · trigger | |
|---|---|---|---|---|---|
| stackSnapshot | stack | Your chips | public | chips = latest stack · + | |
| fieldSnapshot | field | Players left · Total entries · Level · Chips-in-play · Rebuys/Re-entries/Add-ons · LL left | public | chips-in-play two-way (§7) · + | |
| hand | hand | Position · Hole · Board · Action · Result · Pot chips (±) | public | + | |
| pulse new | mind | A-game · Energy · Focus (1–5) | private | optional tilt:* tag · + / footer | |
| rebuy | cost | Amount · Chips after | public | amount = rebuyCost; chips = latest + rebuyChips · gate format:rebuy · + | |
| reentry | cost | Amount · Chips after | public | amount = reentryCost; chips = starting · gate format:reentry · + | |
| addon | cost | Amount · Chips after | public | amount = addonCost · gate format:addon · + | |
| toke | cost | Amount | private | + | |
| food | cost | Amount | private | + | |
| lastLongerEntry | cost | Amount | private | amount = lastLongerBuyin · gate format:last-longer · + | |
| otherCost | cost | Amount | private | + | |
| payout | income | Amount · Finishing place | public | place → finishPlace + cashed · + / footer | |
| bounty | income | Amount | public | gate format:pko/mystery · + | |
| lastLongerPayout | income | Amount | public | gate format:last-longer · + | |
| break | break | Chips | public | breakKind auto (§7) · footer | |
| resume | break | — | public | ends a break · footer | |
| busted | lifecycle | Place | public | place → finishPlace + busted · footer | |
| cashed | lifecycle | Place · Amount | public | place → finishPlace + cashed · footer | |
| ended | lifecycle | (note) | public | stamps endedAt, netHours · footer | |
| note | note | Note text | public | + |
Default visibility rule: money housekeeping (
toke, food, otherCost, lastLongerEntry) and pulse default private; the rest of the journey defaults public. Always editable, now incl. friends.9 Mirrors — events that write back to the session
Results auto-apply; config is only offered (never silent). [GR6]
| Trigger | Writes to session | Mode |
|---|---|---|
| payout/cashed.place | finishPlace + status = cashed | auto |
| busted.place | finishPlace + status = busted | auto |
| fieldSnapshot.totalEntries | entrants | auto |
| your rebuy / reentry / addon events | rebuysCount · reentriesCount · addonsCount | auto |
| any entry-cost money | the matching session cost (rebuy, …) | offered when blank |
10 Gates — format: tags unlock fields & event types
A format: tag (§3) is what makes the relevant fields/events appear. [GR7]
| Tag | Unlocks |
|---|---|
| format:freezeout (default) | baseline — nothing extra |
| format:reentry | reentry money set + reentry event |
| format:rebuy | rebuy money set + rebuyChips + rebuy event |
| format:addon | addon money set + addonChips + addon event |
| format:pko / :mystery | buyinBounty split + bounty event |
| format:last-longer | lastLongerBuyin + LL events + lastLongerLeft |
| level has ante | the ante input on the level field |
11 Media library new
Photos go two ways: attached to an event and into a tagged, classified library we can batch-analyse later (OCR chips/levels, read receipts, auto-populate fields).
| Field | Kind | Notes | |
|---|---|---|---|
| id · playerId · key | — | storage object key (uploaded — not an ephemeral blob URL) | |
| mediaType | select | classification: chips · field-screenshot · hand-screenshot · invoice · receipt · ticket · other | |
| tags | tags | media:* + any §3 tag | |
| capturedAt | datetime | when taken | |
| sessionId · eventId | ref | nullable — media can be standalone in the library or linked | |
| classification | meta | auto (later) | ML-suggested type + confidence |
| ocrText / extracted | meta | auto (later) | read values → prefill an event (chips, level, amount) |
Why first-class: a chip photo isn't just a memory — it's data. Classifying & OCR-ing media is how we auto-populate the boring fields and run mass analysis across a player's whole history.
12 Mental-game pulse new
What mental-game coaches actually track, distilled to three one-tap ratings + a tilt tag. Deliberately not overdone.
| Metric | Scale | Why it's the one to keep |
|---|---|---|
| A-game | 1–5 (C→A) | "Which game did you play?" — the core of Tendler's framework. One number captures decision quality vs your ceiling. |
| Energy | 1–5 (spent→fresh) | Yerkes–Dodson: performance tanks when energy is too low or too high. Decision fatigue is the silent leak. |
| Focus | 1–5 (scattered→locked-in) | Mental fatigue shows up as distraction & second-guessing before you feel "tired". |
- Tilt is a tag, not a 4th slider — mind:tilt with a trigger: tilt:bad-beat · tilt:cooler · tilt:ego · tilt:fatigue. Tag a hand or the session; review patterns later (this mirrors Tendler's "mental hand history").
- Captured as a pulse event any time (one tap), and recalled at session start/end. Defaults private; deeper reflection goes in privateNote.
- Derived: avg A-game/energy/focus per session, and trend across sessions (§13) — the actual coaching signal.
Sources: Tendler — The Mental Game of Poker · 888poker mental-game guide · vip-grinders session management.
13 Derived metrics — never stored, always computed
| Metric | Meaning |
|---|---|
| invested · returned · net · roi · perHour | total in (cost + entry events); total out (income events); profit; ROI %; net ÷ netHours |
| reentriesCount · rebuysCount · addonsCount | your bullets — counted from your events (also stored on session, editable) |
| bountiesWon new | $ & count from bounty events |
| bountyTargetsLeft new | ≈ playersLeft − 1 in a KO — how many bounties are still on the table |
| latestStack · stackInBB · avgStack · vsAvg | chips; chips ÷ BB; total ÷ players left; you ÷ average |
| totalChips | chips-in-play, explicit or from entries × starting (+ rebuys/add-ons) — two-way (§7) |
| currentLevel · playedHours | manual level wins, else structure predictor; entry→end − overnight |
| prizepool · paidSpots · moneyStatus | from payouts; ITM / bubble / from-the-money |
| liveEquity | $ value of your seat — ICM ≤9 left, chip-chop for big fields |
| stackSeries · avgSeries · stackExtremes · strategyHints | trajectory; peak/low; tactical nudges |
| pulseAvg · pulseTrend new | avg A-game/energy/focus this session & across sessions (§12) |
14 What's still open — candidate fields decide
Surfaced by the review. Each is real for a serious bankroll tracker; none are in v1 unless you say so — flagged so we don't quietly balloon scope.
| Candidate | What it adds | Lean call |
|---|---|---|
| Staking / backing | markup, % sold → personal vs investor ROI. Big for serious players (most are staked). | likely v2 — touches every money metric |
| Satellite / ticket entry | entry paid by a won ticket → cost basis differs from cash. | v2 — a flag on the entry |
| Currency conversion | roll USD/AUD/… sessions into one home-currency bankroll. | needed once multi-currency is real |
| Multi-day bags | explicit Day-N bagged chip count (now implicit via overnight break). | nice-to-have; overnight break covers most |
| Table & seat | table #, seat, draw — table-change events. | low priority |
| Friend graph | required to make friends visibility real (§7). | blocks friends-visibility |
| Profile defaults | home currency, default visibility, home venue → feed the auto-fills. | small, do early |
| breakKind threshold | confirm the overnight rule (midnight-cross / >4h) (§7). | one constant to set |
15 Plain-English term glossary
| Term | Meaning |
|---|---|
| MTT | Multi-Table Tournament — played across many tables, players merging as they bust. |
| Cash game | Chips = cash, sit/leave any time. Structurally different from an MTT — hence format is a real field (v2). |
| Buy-in / fee / cost | Buy-in = headline in-play amount; fee = the house rake; cost = buy-in + fee (total out of pocket). |
| Freezeout | One entry, one stack — bust and you're out. The default. |
| Re-entry / Rebuy / Add-on | Re-entry = a brand-new entry after busting; rebuy = top up while seated; add-on = one-time top-up at a break. |
| Bounty / PKO / Mystery | A prize for a knockout. PKO = Progressive (part of the bounty grows your own head); Mystery = bounty drawn from a random pool. Typically a 50/50 split of the buy-in. |
| Last-longer | A side bet: whoever survives longest wins the side pool (independent of the prizepool). |
| GTD / Structure / Level / SB·BB·ante | Guaranteed prizepool; the blind ladder; one rung; the forced bets (small/big blind + ante). |
| Stack / BB / Average stack | Your chips; your stack in big blinds (the real measure of room); total chips ÷ players left. |
| ITM / Bubble | In The Money; the last spot before the money. |
| ICM / Chip-chop | Independent Chip Model — chips→$ equity near the money; chip-chop = simpler proportional estimate for big fields. |
| A-game / B-game / C-game | Tendler's framing for the level you played at — your best, average, and worst decision-making selves. |
| Tilt | Emotion-driven bad play (bad beat, ego, fatigue…). Tracked here as a tag with its trigger. |
| Staking / markup | Selling a % of your action to investors, often at a markup. Splits results into personal vs investor ROI (§14). |
| Toke | A tip to the dealer. |
| Overnight (break) | A multi-day gap (Day 1 → bag → Day 2). Excluded from played hours. |
| Public / Friends / Private | Who sees an event when you share. The flag is the decision — no cherry-picking. |