# TeeCup — Arkitektur-beslutningslogg (ADR) > Dette dokumentet er den autoritative kilden til *hva* som er bestemt og *hvorfor*. > Det leses av mennesker og av AI-modeller (Claude, Gemini) i starten av hver økt. > Endre aldri en beslutning uten å legge til en ny ADR som erstatter den — historikken skal bevares. **Status:** Levende dokument **Sist oppdatert:** 2026-07-15 --- ## Kontekst TeeCup er en kommersiell (SaaS) webapplikasjon for å opprette, administrere og gjennomføre golfturneringer i «Ryder Cup»-format. Den driftes på samme VPS som `teeoff.no`, men skal fungere som et isolert økosystem med eget subdomene (`teecup.teeoff.no`) og egen database (`teecup_db`). Målgruppe: klubber, bedrifter og vennegjenger som arrangerer turneringer over tid. --- ## ADR-001 — Tenant = Organisasjon **Beslutning:** Isolasjonsenheten («tenant») er en **organisasjon**, ikke en turnering. En organisasjon er et bevisst nøytralt begrep som dekker klubb, bedrift *og* vennegjeng. Ved å ikke kalle den «klubb» i datamodellen unngår vi refaktorering den dagen første bedriftskunde kommer. **Hierarki:** ``` Organisasjon (tenant — det som isoleres og faktureres) ├── Medlemmer/spillere (gjenbrukbare på tvers av turneringer) ├── Egendefinerte baner └── Turneringer ├── Lag └── Matcher └── Scores ``` **Begrunnelse:** En turnering er en hendelse med start og slutt, ikke en kunde. Gjenbrukbare ting (spillere, baner, historikk) må leve over turneringens levetid. Turnering er derfor en entitet *inne i* en organisasjon. **Konsekvens:** `tenant_id` i alle skjemaer heter `organization_id`. --- ## ADR-002 — Bruker og organisasjonsmedlemskap er adskilt **Beslutning:** Identitet (innlogging) og medlemskap i en organisasjon er to forskjellige ting. Én `user` kan ha flere `organization_memberships`. **Begrunnelse:** Samme person spiller ofte både klubbturneringen og jobbturneringen. En bruker må kunne krysse organisasjoner med samme innlogging. Dette er lett å bygge inn fra start og smertefullt å legge til senere. **Konsekvens:** Utelukker «database-per-tenant» (se ADR-003), fordi en bruker som krysser organisasjoner da måtte eksistere i flere databaser samtidig. --- ## ADR-003 — Isolasjonsstrategi: Shared schema + Row-Level Security **Beslutning:** Én database (`teecup_db`), delte tabeller, isolert på `organization_id`-kolonne, håndhevet av PostgreSQL **Row-Level Security (RLS)**. **Vurderte alternativer:** | Strategi | For | Mot | Valgt | |---|---|---|---| | Shared schema + `organization_id` + RLS | Enkel drift, billig, skalerer til mange org. | Krever disiplin; RLS må settes riktig | **Ja** | | Database/schema per tenant | Sterk isolasjon | Tung migrering; bryter med ADR-002 | Nei | **Begrunnelse:** RLS flytter isolasjonen fra applikasjonskoden (der én glemt `WHERE organization_id = ...` lekker data mellom kunder) ned til databasen, som håndhever den uansett hva koden gjør. Kombinert med ADR-002 er dette det eneste praktiske valget. **Konsekvens / oppgave:** Hver økt/tilkobling må sette `SET app.current_org` (eller tilsvarende) slik at RLS-policyen kan filtrere. Dette må inn i tilkoblingslaget tidlig, ikke ettermonteres. --- ## ADR-004 — Banedata fra `teeoff_db` via enveis, lesende API-kontrakt **Beslutning:** TeeCup henter offisielle banedata fra hovedplattformen gjennom et veldefinert, lesende API — **ikke** via direkte databasekobling på tvers. **Begrunnelse:** En direkte kobling ville låst TeeCup til hovedplattformens skjemaendringer, og et brudd ett sted ville tatt ned begge produktene. `teeoff_db` er «master» for offisielle banedata; alt brukergenerert innhold (egendefinerte baner, turneringer, brukere) forblir strengt i `teecup_db`. **Konsekvens:** API-kontrakten mot TeeOff må versjoneres og behandles som en ekstern avhengighet, selv om den kjører på samme server. --- ## ADR-005 — Handicap-motoren er et frittstående, testet bibliotek **Beslutning:** All handicap- og score-logikk bygges som en ren Python-modul uten avhengigheter til database, API eller web-rammeverk. Den testes grundig i isolasjon. **Begrunnelse:** Dette er produktets hjerte og den mest risikofylte biten. Feil her koster mest troverdighet. Ved å isolere den kan reglene enhetstestes mot kjente fasitverdier uavhengig av resten av systemet. **Konsekvens / viktig presisering:** Prosentbaserte «allowances» (f.eks. 75 %, 90 %, 3/4) er **konfigurasjon, ikke hardkodet logikk**. Motoren vet ikke at «fourball = 90 %»; den mottar tildelingen som parameter. De konkrete standardprosentene per format må verifiseres mot gjeldende WHS/lokale regler før produksjon — de skal ikke antas fra hukommelse. --- ## ADR-006 — Teknologistack **Beslutning:** - **Backend:** Python + FastAPI (gjenbruker stacken fra TeeOff → enklere vedlikehold). - **Database:** PostgreSQL (+ PostGIS der banegeometri trengs). - **Frontend:** React (Vite) som PWA, offline-first (Service Workers + IndexedDB). **Begrunnelse:** Offline-first er *kjernefunksjonalitet*, ikke luksus — golfbaner har ofte dårlig mobildekning, og score må kunne registreres uten nett og synkes senere. --- ## ADR-007 — Miksede formater via økter, og spiller-pool **Beslutning:** En turnering er en **ordnet sekvens av økter** (sessions), ikke ett enkelt format. Hver økt bærer format, hullomfang og allowance. Ryder Cup = foursome/18 → fourball/18 → singles/18 er tre økter. Hvert lag har en **pool** (`team_roster`) som kan være større enn antall matchplasser. Deltakelse avgjøres per match via `match_participant`. En reserve er en spiller i poolen uten deltaker-rad i en gitt økt; en spiller kan spille kun enkelte økter (f.eks. bare singelen). **Begrunnelse:** Dette er selve Ryder Cup-strukturen. Å modellere format på turneringsnivå ville gjort miksede formater umulig; å modellere deltakelse på turneringsnivå ville gjort reserver og delvis deltakelse umulig. **Konsekvens:** Handicap-snapshot fryses per turnering i `team_roster` (`handicap_index_snapshot`) for reproduserbare resultater. --- ## ADR-008 — 9-hulls-slag: "slagene som faller på 18-hulls-kortet" **Beslutning:** For 9-hulls-økter (front/back) brukes spillerens fulle 18-hulls-tildeling, og slagene fordeles over **hele** 18-hulls stroke index — deretter tas kun de spilte hullene ut. Spilleren mottar slag på de spilte hullene der SI ≤ mottatte slag. **Vurdert alternativ:** WHS' formelle 9-hulls course handicap (eget 9-hulls rating, grovt sagt halvparten). Kan gi et litt annet totaltall. Ikke valgt som standard fordi ikke alle baner publiserer 9-hulls-ratinger, og den valgte metoden er den vanlige i vennegjeng-/klubbmatch-spill. **Kritisk implementasjonsdetalj:** Man må IKKE sende bare de ni spilte hullene inn i slagfordelingen med et 18-hulls slagtall — det gir feil ved høye slagtall (12 slag på back-9 blir da 10 i stedet for riktige 6). Motoren har derfor `allocate_over_played_holes(...)` som fordeler over alle 18 og så tar ut de spilte. Dekket av test `test_nine_hole_twelve_strokes_is_six_not_ten`. **Konsekvens:** `tee_rating` beholder likevel front/back-omfang, slik at WHS' alternativ kan tilbys senere som konfig per turnering uten skjemaendring. --- ## ADR-009 — Egen innlogging, uavhengig av teeoff **Beslutning:** TeeCup har egne brukerkontoer (`app_user`), uavhengig av teeoffs innlogging. **Begrunnelse:** TeeCup selges kommersielt til klubber/bedrifter som kanskje aldri har hørt om teeoff.no. Delt innlogging ville vært forvirrende for dem og koblet de to systemenes auth tettere sammen enn ellers ønskelig. Styrker isolasjonen fra ADR-004. **Konsekvens:** Egen auth (registrering, Google/magic-link e.l.), egne secrets (jf. åpent spørsmål 1), egen sesjonshåndtering. Kaptein- og tilskuer-roller defineres innenfor TeeCups eget auth-lag. --- ## ADR-010 — Feed krever innlogging (ingen anonym lesesti i v1) **Beslutning:** Den «offentlige» runde-feeden er felles for begge lag i turneringen, men bak innlogging. Ingen verdenssynlig lenke i v1. **Begrunnelse:** «Offentlig» betyr her «alle innloggede deltakere i turneringen», ikke «hvem som helst med en lenke». Dette fjerner den uautentiserte lesestien og den tunge modereringen (som ellers kreves når innhold er synlig for verden) fra v1. **Konsekvens:** Synlighet modelleres som kanal-scope (lag / turnering). En ekte verdenssynlig delingslenke kan legges til senere som egen bryter, med moderering, uten å bygge om. --- ## ADR-011 — Turneringsstruktur: lagformat i v1, bracket som egen fremtidig type **Beslutning:** v1 bygges for Ryder Cup-lagformatet (økter → uavhengige matcher → summerte poeng), og låses til **nøyaktig to lag**. **Begrunnelse:** En match/flight er alltid to-sidig. Tre lag ville krevd kryss-oppgjør (A–B, A–C, B–C), nok spillere til å møte to motstandere samtidig, balansert oppsett, og tre-veis blind draw — mye kompleksitet for lite gevinst. To lag er både enklere og riktigere for formatet. Et knockout-bracket (f.eks. 128 spillere, utslagsmatcher, finale + bronsefinale) er en helt egen turneringstype: rundene er *avhengige* (vinner av match A møter vinner av match B), og krever progresjon mellom matcher, seeding, fripass og bronsegren — noe dagens modell ikke har. **Konsekvens:** To-lags-grensen håndheves i app-laget (validering ved turneringsoppsett), ikke med DB-trigger. Match-modellen holdes generell (to sider, vilkårlige lag-referanser), så flere lag eller en knockout-type kan komme senere uten dataomskriving — kjernen (spillere, motor, hull-score, RLS) er typeuavhengig. Knockout er fanget som egen type i FEATURE_BACKLOG.md. --- ## ADR-012 — To scoring-moduser per økt **Beslutning:** Hver økt har en `scoring_mode`: `stroke` (spillere taster slag per hull) eller `hole_result` (registrer bare hvem som vant hullet / delt). **Begrunnelse:** Ønsket fra start: kunne føre score enten detaljert (slag) eller raskt (tapp «lag rød vant hullet»). De to modusene har ulik datainngang. **Konsekvens:** `stroke` skriver til `hole_score` (brutto, motor utleder netto og hull-resultat). `hole_result` skriver til ny tabell `match_hole_result` (vinnende side per hull, NULL = delt). Begge mater samme `compute_match_state` i motoren, så matchstatus beregnes likt uansett modus. --- ## ADR-013 — Blind draw via lås per lag per økt **Beslutning:** Lagoppstilling settes skjult; matchene avsløres når BEGGE lag har låst. Modellert med tabell `lineup_lock` (én rad per lag per økt). **Begrunnelse:** Kjerneønske i Ryder Cup-formatet — kapteinene låser i blinde, og oppgjørene avsløres samtidig. **Konsekvens:** `match_participant`-radene (oppstillingen) opprettes per lag, men motstanderens side skjules i app-laget til det finnes en `lineup_lock` for begge lag. Etter lås kan egen oppstilling ikke endres. Dette er finkornet synlighet (lag-nivå) og håndheves i app-/spørrelaget, ikke RLS — begge lag ligger i samme organisasjon (jf. ADR-010). --- ## Åpne spørsmål (ikke besluttet ennå) Disse må avklares før eller under de relevante fasene: 1. **Sesjons-secret:** TeeOff lar `PUBLIC_SESSION_SECRET` falle tilbake på `JWT_SECRET`. TeeCup bør bruke separate, uavhengige secrets. *(Sikkerhet)* 2. **Cache over flere prosesser:** In-memory `dict`-cache på `app.state` deles ikke mellom flere workers/containere. Ved skalering trengs Redis. *(Skalering)* 3. **Prising:** Per organisasjon (abonnement) eller per turnering? Påvirker ikke isolasjonsmodellen, men påvirker fakturerings-/kvotemodell. 4. **Scramble-grensesnitt:** Arkitekturen skal ta høyde for formatet; eksakt UI-løsning spesifiseres senere. 5. **Individuell-vs-delt-ball i `hole_score`:** Håndheves i app-laget, ikke av databasen (CHECK når ikke opp til `session.format`). Motoren/API-et må passe på at f.eks. et foursome ikke får per-spiller-scorer. --- ## Utviklingsplan (rekkefølge) 1. ✅ Land tenant-modell → **Organisasjon** (ADR-001/002/003) 2. ✅ Denne beslutningsloggen (dette dokumentet) 3. ✅ Handicap-motor som frittstående, testet bibliotek (ADR-005) — 24 tester, R&A-verifisert 4. ✅ Databaseskjema (`001_initial_schema.sql`) — RLS, miksede formater, pool 5. ⏩ Backend-API + regelmotor-integrasjon (neste) 6. ⬜ Frontend (admin + score-registrering) 7. ⬜ PWA & offline-synk