From ce795d68cd4b8bcd4caa7fd375227afc6fbd64d2 Mon Sep 17 00:00:00 2001
From: SowinskiBraeden <braeden@sowinski.dev>
Date: Sat, 21 Mar 2026 13:23:15 -0700
Subject: [PATCH] update README

---
 README.md | 89 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 66 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 28bb573..88868e0 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,108 @@
 # Poker Portal
 
-A small server-rendered poker ledger app for low-stakes no-limit hold'em nights.
+A small Flask app I put together for tracking our low-stakes hold'em nights without having to keep a spreadsheet open all the time.
+
+The idea is pretty simple: public pages for stats and session history, plus a small admin area for recording buy-ins, cash-outs, paid amounts, and notes. The data sits in a CSV audit log, so everything is append-only and easy to follow later.
+
+## What it does
+
+- all-time leaderboard
+- per-session pages
+- per-player stat pages
+- admin login for recording events
+- open / closed session tracking
+- payout tracking with `paid` events
+- session and player charts
+- CSV import / export from the admin page
+- append-only `entries.csv` ledger instead of overwriting old rows
 
 ## Stack
 
+Built with a pretty lightweight setup:
+
 - Python
 - Flask
 - Jinja templates
 - Chart.js
-- Append-only CSV event ledger
-
-## Stuff is does
-
-- All-time leaderboard
-- Session archive
-- Per player stat pages
-- Admin only login for adding ledger events
-- Append only `entries.csv` audit trail
-- Buy-ins, cash-outs, note-only events, and correction events using negative amounts
-- Cumulative profit chart and player charts
+- plain CSS
+- CSV event log for storage
 
 ## Ledger model
 
-The app treats the CSV as an append-only audit trail.
+The app treats `data/entries.csv` as the source of truth.
 
-Each row is one event:
+Each row is an event, not a final snapshot. Instead of editing an old row, I append another one. That keeps rebuys, corrections, payouts, and session state changes visible in the log instead of hiding them behind edits.
+
+Current event types:
 
 - `buyin`
 - `cashout`
+- `paid`
 - `note`
+- `session_open`
+- `session_close`
 
-This means you do not edit old rows when something changes. Instead, you append:
+A few examples:
 
-- another buy-in row for a rebuy
-- another cash-out row if they cash more later
-- a negative amount to correct a mistaken buy-in or cash-out
-- a `note` row for bookkeeping context
+- another `buyin` for a rebuy
+- another `cashout` if chip counts are corrected later
+- a `paid` event when someone is actually settled up
+- a `note` event for bookkeeping context
+- `session_open` / `session_close` to mark whether a game night is still live
+
+It is still just a small side project, but I wanted the event model to stay clean enough that the numbers are easy to trust and the history is easy to read back through.
 
 ## CSV format
 
+Main file:
+
 `data/entries.csv`
 
+Header:
+
 ```csv
 id,created_at,session_date,player_name,event_type,amount_cents,note,actor
 ```
 
-## Run locally
+Amounts are stored in cents to avoid floating-point issues.
+
+## Running it locally
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 cp .env.example .env
-export $(grep -v '^#' .env | xargs)
 python app.py
 ```
 
-## Default environment values
+Then open:
 
-The app reads these environment variables:
+`http://127.0.0.1:8000`
+
+## Environment values
+
+The app reads these from `.env`:
 
 - `SECRET_KEY`
 - `ADMIN_USERNAME`
 - `ADMIN_PASSWORD`
+
+Example:
+
+```env
+SECRET_KEY=change-this
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+```
+
+## Notes
+
+A few choices here were deliberate:
+
+- no database for now
+- no user accounts, just one admin login
+- public-facing stats pages, admin-only controls
+- CSV backup before importing a replacement ledger
+
+If I ever decide to take it further, the first real upgrade would probably be moving the storage layer to SQLite while keeping the rest of the app roughly the same.