تخطي إلى المحتوى الرئيسي

Platform master — schaal, evolutie en wijzigingen

Dit bestand is de ene centrale referentie voor capaciteitsdoelen, ontwerpkeuzes rond schaalbaarheid en een append-only wijzigingslog. Iedere substantiële wijziging aan architectuur, data-pad, security of capaciteit moet hier eerst gelezen en daarna bijgewerkt worden (zie workflow onderaan).

Detaildocumenten blijven bestaan (docs/platform/*, docs/telematics/*, ADR’s). Dit master-document vat de noordelijke richting samen en houdt besluiten + log bij één plek.

1. Noordelijke capaciteit (ontwerpdoelen)​

DomeinDoelOpmerking
Gebruikers≥ 40 miljoen accounts / identiteiten die het platform aankan (registraties, rollen, auth)Vereist o.a. horizontale schaal van app-laag, caching, DB-strategie (replica’s, sharding/partitionering waar nodig), geen single-node aannames.
Trackers≥ 600.000 gelijktijdige veldapparaten (ingest + status)Referentieklasse: Teltonika FMC920 (Codec 8 / AVL — zelfde familie als FMB920). Gateway horizontaal, sticky TCP, event backbone, tijdreeksen in geschikte store.
GroeiToekomstige producten (extra device types, integraties, rapporten)Nieuwe features documenteren hier en in ADR indien architectuur wijzigt; capaciteit expliciet meenemen.

Concrete technische uitwerking: o.a. docs/telematics/scaling.md, docs/platform/data-plane.md, ADR’s onder docs/platform/adr/ en docs/telematics/adr/.

2. Referentie-hardware (voorbeeld)​

  • Teltonika FMC920 — representatief voor een grote fleet: periodieke AVL-records, TCP-sessies, command queue. Ontwerp gateway + workers + opslag alsof honderdduizenden van dergelijke sessies gelijktijdig kunnen bestaan.

3. Ontwerpprincipes (kort)​

  1. Stateless applicatie waar mogelijk; sessies/cache extern (bijv. Redis).
  2. Horizontale schaal voor gateway, API en workers; geen “één grote machine”-mentaliteit.
  3. Data: partitionering / tijdreeksen-archief; leespaden voor rapportage gescheiden van hot write-path waar passend.
  4. Backpressure & limieten — buffers, rate limits, duidelijke foutpaden (zie telematics scaling).
  5. Observability — metrics, logging, runbooks; SLO’s expliciet houdbaar maken.
  6. Documentatie — significante beslissingen in ADR; dit master-document bijwerken + logregel toevoegen.

4. Verplichte workflow (mens + agent)​

Vóór substantiële code- of infra-wijzigingen:

  1. Lees dit bestand (relevante secties + laatste logregels).
  2. Lees docs/platform/README.md voor index; open betrokken ADR’s en telematics/platform docs.
  3. Raadpleeg de lokale agent-audittrail: .cursor/logs/agent-audit.jsonl (laatste regels) om overlap of recente edits te zien.

Na wijzigingen die architectuur, security, data-model of capaciteit raken:

  1. Werk de relevante secties in dit document bij (doelen, status, links).
  2. Voeg een regel toe aan §5 Wijzigingslog (append-only).
  3. Voeg of werk een ADR bij indien het een blijvende architectuurkeuze is.

5. Wijzigingslog (append-only)​

Datum (UTC)GebiedSamenvattingDetails / PR / commit
2026-05-15Docs + Cursor rulesMaster-document aangemaakt; schaaldoelen 40M gebruikers / 600k FMC920-klasse devices; workflow gekoppeld aan rules; platform/telematics index en scaling.md op doelen afgestemd.docs/PLATFORM-MASTER.md, .cursor/rules/platform-scale-evolution.mdc, .cursor/rules/agent-audit-workflow.mdc, docs/platform/README.md, docs/telematics/scaling.md, docs/telematics/README.md
2026-05-15GitHub / DXRepo-naam package.json aligned; GitHub workflows (docs CI, PR labeler, dependency review), Dependabot, issue/PR templates, CODEOWNERS, SECURITY, CONTRIBUTING, scripts voor labels + starter issues, docs/github/SETUP.md..github/*, scripts/github/*, CONTRIBUTING.md, SECURITY.md, docs/github/SETUP.md, package.json
2026-05-15Docs-site + deployDocusaurus (documentation/) bouwt repo-root docs/; nginx-template + render uit .env; secrets PRODUCTION_DOCS_HOST / PRODUCTION_DOCS_URL; Docker build naar /var/www/omnihub-docs; certbot --expand voor extra hostnamen; workflow: patch → docs → ensure → compose.documentation/, deploy/nginx/omnihub.conf.template, deploy/render-nginx-from-env.sh, deploy/build-documentation-static.sh, deploy/patch-env-github-secrets.sh, deploy/ensure-server-deps.sh, .github/workflows/deploy.yml, .github/DEPLOY-SECRETS.md, .cursor/rules/docusaurus-public-and-domains.mdc
2026-05-15GitHub / DXScript create-roadmap-project.mjs: na gh auth refresh -s project,read:project project aanmaken of hergebruiken, repo koppelen, open issues op board; SETUP §2 uitgebreid.scripts/github/create-roadmap-project.mjs, scripts/github/create-roadmap-project.ps1, scripts/github/create-roadmap-project.sh, docs/github/SETUP.md
2026-05-15GitHub / DXProject #4 OmniTrack roadmap: aangemaakt, Jjustmee23/omnihub-schoolV2 gekoppeld, 5 open issues op het board gezet.gh project + scripts/github/create-roadmap-project.mjs
2026-05-15Cursor rulesNieuwe rule github-issues-resolve-and-done.mdc: agents bij “los issue(s)” gh gebruiken, Fixes/Closes, sluiten na merge voor Done op project; kruisverwijzing in platform-scale-evolution.mdc..cursor/rules/github-issues-resolve-and-done.mdc, .cursor/rules/platform-scale-evolution.mdc
2026-05-15GitHub / DXDependabot groups + open-pull-requests-limit: 1 per ecosystem (minder branches/PR’s); PR labeler alleen naar main; lichte CI voor pure dependabot/github_actions/* PR’s in deploy.yml; SETUP-doc met cleanup-hint..github/dependabot.yml, .github/workflows/deploy.yml, .github/workflows/pr-labeler.yml, docs/github/SETUP.md
2026-05-15GitHub / DXRoadmap-batch: manifest ~33 issues; populate-omnitrack-roadmap.mjs + labels roadmap / omnitrack-roadmap-batch; SETUP §4b.scripts/github/roadmap/manifest.json, scripts/github/populate-omnitrack-roadmap.mjs, scripts/github/labels.json, docs/github/SETUP.md
2026-05-15GitHub / DXProject #4: repo gh project link; velden Target date + Delivery phase (gh project field-create); SETUP §2c — 12 gefilterde views + optionele Roadmap-timeline, Status vs Delivery phase, workflows, default view.gh project link, gh project field-create, docs/github/SETUP.md
2026-05-15Product / feedbackIn-app supporttickets (categorie/subcategorie), feature-ideeën met stemmen + suggesties + merge; optionele GitHub-export (overheid); dashboardtabs + chauffeur-help; tabellen support_tickets, feature_requests, feature_votes; env GITHUB_FEEDBACK_*; rule feedback-product-github.mdc.server.ts, src/App.tsx, src/feedback/FeedbackPages.tsx, src/locales/*.json, deploy/env.production.template, .cursor/rules/feedback-product-github.mdc
2026-05-15Product / feedbackSemantische dubbele ideeën (Jaccard-tokens + titelgewicht), live preview-duplicates; chauffeur-header Ideas naast Help; GitHub-token uit GITHUB_FEEDBACK_TOKEN_FILE (mtime-cache); feedback rate limits (preview/write/vote/sync).server.ts, src/App.tsx, src/feedback/FeedbackPages.tsx, src/locales/*.json, deploy/env.production.template, .cursor/rules/feedback-product-github.mdc
2026-05-15Security / RBACCanonieke Engelse rollen + tabellen user_permissions / user_scopes; routes en Socket op permissies/scopes; legacy NL-rollen migratie; UI + seed op /api/me permissies; feedback-viewer uitzondering voor POST zonder domein-write.ADR 0005-rbac-roles-scopes-permissions.md, lib/authz.ts, server.ts, seedIraqDemo.ts, src/authzClient.ts, src/App.tsx, src/feedback/FeedbackPages.tsx, src/locales/*.json, .cursor/rules/overheid-operator-ux.mdc, .cursor/rules/feedback-product-github.mdc
2026-05-15Deploy / docsCanonieke productie-domeinen in repo: omnitransitiq.com (app), docs.omnitransitiq.com, track.omnitransitiq.com — templates + DEPLOY-SECRETS.md + Docusaurus/build-defaults aligned met GitHub secrets..github/DEPLOY-SECRETS.md, deploy/env.production.template, deploy/build-documentation-static.sh, documentation/docusaurus.config.ts, .cursor/rules/docusaurus-public-and-domains.mdc, docs/PLATFORM-MASTER.md §7
2026-05-15Product / authHeropenen eerste setup: optioneel BOOTSTRAP_REOPEN_TOKEN (min. 24 tekens) + POST /api/bootstrap/reopen + login-UI; transactie zet bootstrap_completed=false en heractiveert admin@admin.be; optioneel GitHub secret PRODUCTION_BOOTSTRAP_REOPEN_TOKEN → patch-env.server.ts, src/App.tsx, src/locales/*.json, deploy/patch-env-github-secrets.sh, deploy/env.production.template, .github/workflows/deploy.yml, .github/DEPLOY-SECRETS.md, README.md, docs/PLATFORM-MASTER.md
2026-05-15Product / authDemo quick-login: vaste *.@demo.local seed-accounts worden bij elke start gesynchroniseerd (ensureDemoQuickLoginUsers); super-demo gov.super@demo.local verwijderd; inlog vóór bootstrap_completed toegestaan alleen voor e-mailadressen op @demo.local (bootstrap blijft verplicht voor overige accounts).seedIraqDemo.ts, server.ts, src/App.tsx, src/locales/*.json
2026-05-15Product / studentsParent enrollment: map-based pickup (Nominatim reverse via GET /api/geocode/reverse), school type-ahead, optional child login (users.role=student, students.child_login_user_id); buses list for student role; Iraq-oriented address fallback when road is missing.server.ts, lib/authz.ts, src/authzClient.ts, src/App.tsx, src/locales/*.json, ADR 0005-rbac-roles-scopes-permissions.md
2026-05-15Docs-site (publiek)Gebruikersgids in docs/user-guide/ (ouders, school, chauffeurs, account, help/ideeën); Docusaurus i18n en / ar-IQ / ckb (RTL), vertaalde MD onder documentation/i18n/*/…/user-guide/, thema-strings via documentation/scripts/seed-locale-code-json.mjs; homepage + footer/navbar; sidebar-categorieën; unieke _category_.json keys voor dubbele adr-mappen.docs/user-guide/*, documentation/docusaurus.config.ts, documentation/sidebars.ts, documentation/src/pages/index.tsx, documentation/scripts/seed-locale-code-json.mjs, documentation/i18n/**, docs/platform/adr/_category_.json, docs/telematics/adr/_category_.json, documentation/README.md, .cursor/rules/docusaurus-public-and-domains.mdc
2026-05-15Product / supportdeskIn-app enterprise ticketing: threads (support_ticket_messages), audit (support_ticket_events), queues/filters, SLA policies + deadlines, outbound e-mail jobs (SUPPORT_SMTP_URL), inbound webhook HMAC (SUPPORT_EMAIL_INBOUND_SECRET), macro’s, knowledge base (/api/kb/*); permissies feedback_support_agent, feedback_support_macros_manage, feedback_kb_admin; UI tabs Tickets/Help center.ADR 0006-in-app-support-desk.md, server.ts, lib/supportDesk.ts, lib/authz.ts, src/authzClient.ts, src/feedback/*, src/locales/*.json, deploy/env.production.template
2026-05-15Product / supportdeskTicket bijlagen (max 3 × 4 MB, PDF/JPEG/PNG/WebP in Postgres) + authenticated download; UI-split: Support-tab voor iedereen met feedback_support_create, aparte sidebar Ticket desk voor agents (feedback_support_agent + feedback_support_read_all).server.ts, src/App.tsx, src/feedback/FeedbackPages.tsx, src/feedback/SupportTicketDetailModal.tsx, src/locales/*.json, ADR 0006-in-app-support-desk.md

(Nieuwe rijen altijd onderaan toevoegen; oude rijen niet wijzigen.)

6. Status & open punten​

7. Publieke documentatie (Docusaurus) en domeinen​

  • De map docs/ (Markdown, ADR’s, runbooks) is de bron; documentation/ bevat Docusaurus en publiceert die inhoud als statische site (geen secrets in die content). Klant‑handleiding (docs/user-guide/) staat naast technische indexen; vertalingen ar-IQ en ckb voor die gids zitten onder documentation/i18n/<locale>/docusaurus-plugin-content-docs/current/user-guide/ (korte UI‑teksten blijven in src/locales/*.json).
  • Productie: configureer PRODUCTION_APP_URL, PRODUCTION_TRACKER_HOST, optioneel PRODUCTION_DOCS_HOST (= bv. docs.omnitransitiq.com) en PRODUCTION_DOCS_URL in GitHub Actions secrets; DNS naar de juiste server(s). Details: ../.github/DEPLOY-SECRETS.md.
  • Meerdere servers (schaal): wijs per rol hostnamen toe (app vs. ingest vs. docs-edge); werk dit document + platform-docs bij wanneer je traffic splitst.

Laatste inhoudelijke update van dit document: zie laatste regel in §5.