Sports DB

Zimbabwe sports data platform for athlete registry, teams, organizations, competitions, public results, and digital athlete passports.

Project lives at: /Users/bhekanik/code/bhekanik/sports-db/

In one paragraph

Sports DB is the data-platform side of the Sports Performance Lab idea: a shared system for verified athletes, competition results, team/federation records, and performance data. The product is moving beyond an internal dashboard into public surfaces: a national athlete directory, public results, and shareable digital passports. That makes the privacy boundary the important product question, not a detail to clean up later.

Why it exists

Zimbabwe sports data still lives in scattered spreadsheets, WhatsApp threads, federation paperwork, and one-off media records. Sports DB tries to make the registry legible enough for athletes, federations, clubs, media, sponsors, and scouts to trust the same record. The useful version of the product is not "more data." It is controlled access to verified data, with the public story separated from the internal operating record.

What is true in code as of 2026-06-23

Validated against the repo:

• The app is a Next.js 16 App Router project using Drizzle/Postgres, Better Auth, TanStack Query, Resend, and R2-compatible image storage.
• The dashboard requires a session, but it does not enforce user.isApproved.
• New users default to viewer.
• The old account-approval endpoint returns 410 Gone; approval columns and some approval UI/copy still exist.
• The public directory and public results pages exist.
• The digital passport API deliberately filters sensitive fields and gates optional sections through passport settings.
• /api/athletes and /api/athletes/[id] are still public through middleware and return broader athlete data than the passport API.
• Passport settings API exists, but there is no visible settings UI. Missing settings default to published.
• Vitest and Playwright tests exist.
• There is no generated docs website in the repo. Markdown under docs/ is the docs surface.

What the audit changed

The June 2026 audit turned the repo's risk from a vague feeling into a usable backlog. The most important finding is still valid: the app has a privacy-filtered passport surface, but the public directory is wired to the broad internal athlete API. That is not just a security issue. It is a product definition issue. The app has to decide what a public athlete record is before the public directory can be treated as shipped.

The audit also showed a documentation failure mode I keep seeing: docs had preserved an older approval model, while the runtime had moved to immediate viewer access. That kind of drift is especially dangerous in auth docs because operators trust them when assigning roles, approving users, and explaining access to stakeholders.

Reusable lessons

• Audit Evidence Is Part of the Fix - the audit became useful because it landed as committed reports with evidence, not only as a temporary browser tab.
• Generated Docs as Drift Defense - this repo has no generated docs site, so Markdown docs need manual code truth sweeps for auth, public routes, migrations, tests, and role behavior.
• Document Every Shipped Surface - public routes are product surfaces. A public API, a directory page, a passport page, and an admin settings page all need their own documented contract.
• Read Existing Before Creating - the right move was to update AGENTS.md, README.md, architecture, schema, and roadmap docs instead of creating a parallel "new truth" file that would drift too.

Open product decisions

• Should account approval come back, or is immediate viewer access the intended model?
• What exact fields belong in a public athlete directory row and public athlete profile?
• Should passports default to unpublished until an athlete/admin explicitly publishes them?
• Is configurable authorization meant to be the source of truth, or only a draft policy UI until routes are migrated?
• What is the actual team-manager scope: all athletes, managed teams, organizations, or assigned athletes only?

Current repo docs

• docs/README.md
• docs/ARCHITECTURE.md
• docs/SCHEMA.md
• docs/FEATURE_ROADMAP.md
• docs/audit/2026-06-19-consolidated-plan.md