That's My Dash

Teknisk dokumentation

For udviklere

Arkitektur, sikkerhed og retningslinjer for videreudvikling af promoveringssiden og CMS’et.

Projektstatus: That's My Dash

Senest opdateret: 2. august 2026 Aktuel version: 0.8.1 Projektansvarlig og rettighedshaver: Weiglin 2026 Licens: MIT

Formål

Dette er projektets korte overdragelsesdokument. Det skal læses sammen med README.md, CHANGELOG.md, docs/DEVELOPMENT.md, docs/ACCESSIBILITY.md og den seneste frigivelsesaudit, før kode ændres.

Ved modstrid gælder den aktuelle kildekode og databaseskemaet som teknisk virkelighed. Bindende produktbeslutninger nedenfor må ikke ændres uden en udtrykkelig ny beslutning fra projektansvarlig.

Produktet

That's My Dash er en personlig, internetbaseret startside til flere brugere. Hver bruger har sin egen profil og egne data. Applikationen er skrevet i PHP, bruger SQLite og skal kunne installeres på et almindeligt webhotel uden MySQL, kommandolinje eller manuel databaseimport.

Beslutninger, der skal bevares

  • Produktnavnet er That's My Dash. Browserfanens HTML-titel er præcis dette

    • navn på alle sider.

  • SQLite er den eneste lokale database. Der må ikke indføres et MySQL-krav.
  • Eksisterende databaser opgraderes additivt. Brugeren udfører aldrig SQL

    • manuelt. Ved opgradering bevares config.php og hele storage-mappen.

  • Flere brugere har hver sin profil. Private data må ikke kunne ses eller

    • ændres af andre brugere. Administratorfunktioner kræver administratorrolle.

  • Alle skrivende handlinger bruger POST, CSRF-kontrol, validering og

    • ejerskabskontrol.

  • Lyst og mørkt tema skal understøttes på alle sider.
  • WCAG 2.2 niveau AA er det tekniske mål. Musetræk må aldrig være den eneste

    • måde at flytte indhold på.

  • Brugergrænsefladen leveres på dansk, engelsk, tysk, fransk, spansk, polsk,

    • russisk og forenklet kinesisk. Engelsk er sikkerhedssprog.

  • Sprogfiler kan tilpasses og udvides uden programændringer. Lokale

    • tilpasninger i storage/languages skal overleve opgraderinger.

  • Brugervejledningen findes på alle medfølgende sprog og åbnes fra sidefoden.
  • Sidefoden viser version, © Weiglin 2026 og kort MIT-licensinformation.
  • Eksterne RSS-, iCal- og vejradresser hentes serverside med HTTPS,

    • størrelses- og tidsgrænser samt beskyttelse mod interne netværksadresser.

  • Google Kalender er valgfri. Den lokale kalender fungerer uden Googlekonto.
  • PWA og notifikationer er valgfrie og må ikke være nødvendige for normal brug.

Funktioner i 0.8.1

  • Indbyggede søgemaskiner samt op til to personlige søgemaskiner.
  • Favoritkasser med egne overskrifter, links, ikoner, prioritering, rækkefølge,

    • visning og kompakt tilstand.

  • Aktuelle opgaver med deadline, noter, afslutning, hurtig oprettelse og

    • valgfrie adviseringer.

  • Flere noter, søgning, fastgørelse og frigørelse uden sletning.
  • Lokal kalender, skrivebeskyttet iCal og valgfri Google Kalender. Aftalens

    • kilde markeres med både tekst og farve.

  • Vejr fra valgt by eller enhedens position med metriske eller amerikanske

    • enheder.

  • Flere RSS-kilder, test før lagring, ligelig kildefordeling, nyhedsside og

    • valgfri ticker med hastighed og pause. På mobil bruges RSS-listen.

  • Modulstyring med vis, skjul, flyt op, flyt ned og kompakt visning.
  • Separat systemtjek med status, forståelige fejl, seneste vellykkede

    • opdatering og mulighed for at prøve igen.

  • Personlig backup og import, profil, adgangskodeskift, brugeradministration og

    • installerbar PWA med offline-side.

Bevidste afgrænsninger

  • iCal-aftaler er skrivebeskyttede.
  • Google kræver administratorens OAuth-opsætning og brugerens Googlekonto.
  • Eksterne datakilder kan fejle uden at applikationen er defekt.
  • Noter er almindelig tekst og må ikke bruges til adgangskoder.
  • Automatisk test kan ikke alene dokumentere fuld WCAG-overholdelse.
  • Oversættelserne er kontekstreviderede, men ikke godkendt af professionelle

    • modersmålskorrekturlæsere.

Sikkerheds- og datakrav

  • PHP 8.2 eller nyere og HTTPS.
  • public bør være dokumentrod. config.php, storage og databasen må ikke

    • kunne downloades.

  • Adgangskoder hashes med PHP's passwordfunktioner.
  • Kalenderhemmeligheder, Google Client Secret og tokens krypteres med

    • installationens app_key.

  • Private data må ikke skrives til browser- eller service-worker-cache.
  • Import valideres og må ikke importere adgangskoder eller kalenderhemmeligheder.
  • Brugerfejl er forståelige; tekniske detaljer logges uden hemmeligheder.

Kontrol før hver frigivelse

  1. Kør php tools/quality-check.php med pdo_sqlite.
  2. Kontrollér PHP-, JavaScript- og JSON-syntaks.
  3. Kør node tools/i18n-check.js. Alle sprog skal have fuld dækning og

    4. uændrede tekniske pladsholdere.

  4. Test ren installation og opgradering af en kopi af en eksisterende database.
  5. Test brugeradskillelse, roller og alle funktioner nævnt ovenfor.
  6. Test lyst og mørkt tema, mobil, desktop samt lange og tomme tekster.
  7. Gennemfør tastatur-, skærmlæser-, zoom-, reflow- og kontrastkontrollerne i

    8. docs/ACCESSIBILITY.md.

  8. Kontrollér HTML-titlen That's My Dash på alle sider.
  9. Opdatér VERSION, ændringslog, README, denne fil og relevant audit.
  10. Pak uden config.php, database, cache og installationsdata, og offentliggør

    11. pakkens SHA-256-fingeraftryk.

Kendte opfølgningspunkter

  • Den manuelle WCAG-test skal dokumenteres på den installerede version med

    • mindst NVDA eller VoiceOver.

  • Oversættelser bør senere korrekturlæses af frivillige modersmålstalende uden

    • at ændre tekniske pladsholdere.

  • Nye funktioner skal prioriteres mod enkelhed. Startsiden skal ikke udvikle

    • sig til et komplet projektstyrings- eller notesystem.

Tekst til en ny udviklingssamtale

Vedhæft den seneste ZIP-pakke og skriv:

Vi fortsætter udviklingen af That's My Dash. Den vedhæftede ZIP er det eneste

tekniske udgangspunkt. Pak den ud, og læs docs/PROJECT_STATUS.md,

README.md, CHANGELOG.md, docs/DEVELOPMENT.md og

docs/ACCESSIBILITY.md, før du ændrer noget. Bevar eksisterende funktioner,

SQLite-data, sprogsystem, tilgængelighed og opgraderingsmulighed. Kontrollér

ændringerne og dokumentér kendte begrænsninger.

Beskriv derefter den ønskede ændring og vedhæft eventuelle skærmbilleder. En ny udvikler må ikke antage, at tidligere mundtlige beslutninger er kendt, hvis de ikke står i pakken.

Udvikling

Teknisk grundlag

  • PHP 8.2 eller nyere
  • SQLite
  • Moderne HTML, CSS og JavaScript uden frontend-framework
  • Progressiv forbedring: centrale redigeringsfunktioner virker uden JavaScript

Struktur

public/
  index.php          Kort frontcontroller, logout og login
  api.php            Same-origin endpoints til kalender, RSS, vejr og ikoner
  install.php        Browserbaseret installationsguide
  assets/            CSS og JavaScript
src/
  actions.php        OAuth-ruter og autoriserede ændringer
  page_context.php   Læseforespørgsler og data til visningen
  bootstrap.php      Session, database, sikkerhedsheaders og fælles funktioner
  http.php           Sikre, cachede HTTPS-kald
  view.php           Præsentations- og formateringshjælpere
views/
  app.php            Fælles HTML, navigation og valg af sideskabelon
  license.php        Offentlig, selvstændig licensside
  pages/             Én skabelon pr. side
storage/
  startside.sqlite   Brugerdata, oprettes ved installation
  cache/             Genskabelige cachefiler

Requestforløb

Efter login udfører public/index.php tre trin i fast rækkefølge:

  1. src/actions.php håndterer OAuth og eventuelle POST-handlinger.
  2. src/page_context.php indlæser de data, som den aktuelle side kan bruge.
  3. views/app.php vælger en sideskabelon fra en fast, intern liste.

Filer under views må ikke udføre ændringer i databasen. Nye POST-handlinger skal placeres i src/actions.php, beskyttes af den fælles CSRF-kontrol og begrænse brugerdata med den aktuelle brugers id.

Skabeloner arver kun de variabler, som frontcontrollerens inkluderede filer har forberedt. Al brugerleveret tekst skal fortsat escapes med e().

Koderegler

  • Brug declare(strict_types=1) i alle PHP-filer
  • Følg PSR-12 for ny PHP-kode, hvor PHP/HTML-skabeloner tillader det
  • Brug parameteriserede PDO-forespørgsler
  • Medtag altid brugerens id i forespørgsler, der ændrer brugerdata
  • Escape al brugerdata med e() ved HTML-output
  • Tillad ikke brugerleveret HTML
  • Alle ændringer skal kunne betjenes med tastatur
  • Brug native HTML før ARIA
  • Kommentér årsagen til usædvanlig kode, ikke det indlysende
  • Bevar bagudkompatibilitet med eksisterende SQLite-databaser
  • Databaseændringer skal være additive og idempotente

JavaScript

JavaScript bruges som progressiv forbedring til:

  • søgning
  • dynamisk kalender, RSS og vejr
  • favicon-reserve
  • deadlineadvis
  • fokus på formularbeskeder

Indstillinger, favoritter, RSS-administration og opgaver må ikke kræve JavaScript for at kunne gemmes.

Undgå at indsætte brugerdata med innerHTML. Brug textContent og DOM-metoder. Statiske HTML-fragmenter må bruges, når de udelukkende består af kode, som projektet selv kontrollerer.

Eksterne kald

Alle eksterne kald går gennem src/http.php.

  • Kun HTTPS
  • Private og reserverede IP-adresser afvises
  • Redirects valideres enkeltvis
  • Maksimal svartid og svarstørrelse er begrænset
  • Svar caches lokalt

Browseren kontakter derfor ikke RSS-kilder, kalenderudbydere eller favicon-tjenesten direkte.

Personlige søgemaskiner er den bevidste undtagelse: Efter et direkte brugerklik åbner browseren den valgte HTTPS-søgeadresse med et URL-kodet søgeord. Skabelonen valideres af valid_search_template() før lagring og må indeholde {query} præcis én gang.

Før en ændring afleveres

  1. Kør php tools/quality-check.php
  2. Kontrollér PHP-syntaks
  3. Kontrollér JavaScript-syntaks
  4. Test både ny installation og opdatering af en eksisterende database
  5. Test lyst og mørkt tema
  6. Test mobilvisning
  7. Gennemfør den relevante del af ACCESSIBILITY.md
  8. Opdatér CHANGELOG.md, README.md og VERSION

Open source og licens

Projektet er udgivet under MIT-licensen. Alle kopier og væsentlige dele af programmet skal derfor indeholde copyrightmeddelelsen og licensteksten fra LICENSE.

Bidragydere bør dokumentere større ændringer i CHANGELOG.md og undgå at tilføje kode, skrifter, ikoner eller andre aktiver med en uforenelig licens.

Tilgængelighed

Målsætning

That's My Dash udvikles med WCAG 2.2 niveau AA som teknisk mål.

For danske offentlige websteder er den harmoniserede europæiske standard EN 301 549 v3.2.1 central. Standardens webkrav henviser til WCAG 2.1. Ved at arbejde efter WCAG 2.2 AA dækkes WCAG 2.1-kravene samtidig, og de nyere succeskriterier indarbejdes i produktet.

Officielle referencer:

Tilgængelighed er ikke en engangstest. Nye funktioner og designændringer skal vurderes efter de fire WCAG-principper:

  1. Opfattelig
  2. Anvendelig
  3. Forståelig
  4. Robust

Hvad koden understøtter

  • Semantiske HTML-elementer og en logisk overskriftsstruktur
  • Korrekt sidesprog og et stabilt produktnavn i browserfanen; hver sides

    • emne fremgår af dens synlige <h1>

  • Spring til hovedindhold
  • Fuld betjening med tastatur
  • Synlig tastaturfokus i lyst og mørkt tema
  • Tilstrækkeligt store betjeningsmål
  • Formularnavne, hjælpetekster og tekstbaserede fejlbeskeder
  • Aktuel side markeret med aria-current
  • Valgt søgemaskine markeret med aria-pressed
  • Dynamiske moduler med aria-live og aria-busy
  • Vigtige deadlinebeskeder med live-region
  • Dekorative SVG-ikoner skjult for hjælpemidler
  • Understøttelse af prefers-reduced-motion
  • Grundlæggende understøttelse af Windows High Contrast/forced colors
  • Funktionel serverbaseret redigering uden JavaScript

Ingen automatisk overensstemmelseserklæring

Projektet må ikke markedsføres som fuldt WCAG-konformt alene på baggrund af koden eller et automatisk testværktøj. En overensstemmelsesvurdering gælder den konkrete installation, det konkrete indhold og de anvendte tredjepartskilder.

Før en offentlig lancering skal installationen som minimum gennemgå nedenstående manuelle test.

Manuel test før udgivelse

Tastatur

  • Gennemgå alle sider med Tab og Shift+Tab
  • Kontrollér, at fokus altid er synligt
  • Kontrollér alle knapper, links, formularer og details med Enter og Space
  • Kontrollér at springlinket flytter fokus til hovedindholdet
  • Kontrollér at fokus ikke bliver fanget

Skærmlæser

Test mindst:

  • NVDA med seneste Firefox eller Chrome på Windows
  • VoiceOver med Safari på iPhone eller macOS

Kontrollér overskrifter, landmærker, formularnavne, fejlbeskeder, deadlineadvis, vejr, kalender, RSS, personlige søgemaskiner og licenssiden.

Forstørrelse og reflow

  • 200 procent browserzoom
  • 400 procent browserzoom ved 1280 CSS-pixels
  • 320 CSS-pixels bred visning
  • Større tekst og brugerdefineret tekstafstand
  • Ingen tabt information eller vandret rulning i hovedindholdet

Farver

  • Lyst tema
  • Mørkt tema
  • Windows High Contrast
  • Information må ikke være afhængig af farve alene
  • Tekst og betjeningskomponenter skal kontrastmåles

Indhold og fejl

  • Tomme moduler
  • Lange navne, links, opgaver og RSS-overskrifter
  • Ugyldige formularfelter
  • Ugyldig søgeskabelon og testsøgning i nyt vindue
  • Udløbet session
  • Manglende vejr-, kalender- og RSS-forbindelse
  • Afvist tilladelse til geografisk placering

Automatiske værktøjer

Automatiske værktøjer kan bruges som supplement:

  • axe DevTools
  • Accessibility Insights for Web
  • Lighthouse Accessibility
  • W3C HTML Validator

Et automatisk værktøj kan ikke teste blandt andet forståelighed, meningsfuld læserækkefølge, gode linktekster eller hele tastaturoplevelsen.

Vedligeholdelse

Alle fejl, som forhindrer brug med tastatur eller hjælpemidler, behandles som funktionelle fejl og ikke som kosmetiske forbedringer.

Ved open source-udgivelse bør projektet have:

  • en offentlig metode til indberetning af tilgængelighedsproblemer
  • dokumenteret browser- og hjælpemiddelunderstøttelse
  • en tilgængelighedserklæring for den konkrete demonstrationsinstallation
  • et fast regressionstjek ved hver udgivelse

Filen ACCESSIBILITY_STATEMENT_TEMPLATE.md kan bruges som udgangspunkt, men skal tilpasses den konkrete installation og de regler, som gælder for ejeren.

Sprog og oversættelser

That's My Dash bruger en lille filbaseret sprogmotor uden Composer-afhængigheder. De medfølgende kataloger ligger i languages/ og er almindelige JSON-filer.

Sprog i version 0.8.1

Kode Sprog
da Dansk
en Engelsk
de Tysk
fr Fransk
es Spansk
pl Polsk
ru Russisk
zh-CN Forenklet kinesisk

Engelsk er altid sikkerhedssprog. Mangler en nøgle i det valgte katalog, forsøger sprogmotoren først en.json. Den danske kildetekst bruges kun som sidste nødudvej, hvis også den engelske post mangler.

Katalogformat

{
  "_meta": {
    "code": "en",
    "name": "English",
    "native_name": "English",
    "direction": "ltr"
  },
  "messages": {
    "Gem": "Save"
  }
}

Danske kildetekster fungerer som stabile meddelelses-id'er. Brugerindhold må aldrig sendes gennem tr(). Dynamiske værdier indsættes med navngivne pladsholdere:

tr("Vejret i :place", ["place" => $place]);

Pladsholderens navn må ikke oversættes. :place, {query} og tilsvarende tekniske markører skal være identiske i kilde og oversættelse.

Lokale tilpasninger

En installation kan overskrive enkelte tekster i storage/languages/<kode>.json. Sprogmotoren fletter filen oven på den medfølgende sprogpakke. Eksempel:

{
  "messages": {
    "Startside": "Min portal"
  }
}

Filer i storage/languages hører til installationens data og må ikke overskrives ved en opgradering.

Tilføj et nyt sprog

  1. Kopiér languages/en.json til en ny JSON-fil.
  2. Ret metadata, herunder sprogkode og sprogets eget navn.
  3. Oversæt værdierne i messages. Nøglerne må ikke ændres.
  4. Bevar alle navngivne pladsholdere uændret.
  5. Kør node tools/i18n-check.js.
  6. Test login, dashboard, formularer, fejlbeskeder, kalender, vejr og mobilvisning.

Sprogfiler med højre mod venstre-skrift kan bruge "direction": "rtl". Layoutet angiver automatisk dokumentets dir, men en ny RTL-pakke kræver stadig en visuel gennemgang.

Udviklerkontrol

node tools/i18n-sync.js føjer nye danske, bogstavelige nøgler til languages/da.json. Værktøjet oversætter ikke noget.

node tools/i18n-check.js kontrollerer, at alle registrerede nøgler findes i alle kataloger. Kontrollen dækker også serverbeskeder, installerens tekster og den lille ordbog, der sendes til JavaScript.

En automatisk dækningskontrol kan ikke vurdere sproglig kvalitet. Nye eller ændrede oversættelser skal derfor læses i sammenhæng og testes i grænsefladen.