basisbeeld-usage-dashboard

Local-only dashboard that surfaces how the Basisbeeld test and prod environments are being used. Reads directly from the DynamoDB basisbeeld-providers-* tables via your AWS SSO credentials.

What it shows

• Totals per concept — gesprekken, meldingen, onderzoeken, vragenlijsten over the picked date range, with a sparkline.
• Totaal per gemeente — stacked totals across all concepts, per municipality.
• Totaal per periode — stacked totals across all concepts over time, with a zoomable slider.
• Concept histograms — per-status breakdown per granularity (maand / week / dag).
• Active aanbieders — providers (KVK + name) that had at least one record in scope.

Filters: gemeente / samenwerkingsverband, aanbieder, granularity, exclude dummy entities (Rex Thuiszorg, Molendijk aan Zee).

First-time setup

1. Copy the example config.

   cp src/config.example.json src/config.json

   Then edit src/config.json and fill in the real values for your environment:

   • AWS_PROFILE — the SSO profile name in ~/.aws/config (e.g. admin-test-profile, admin-prod-profile).
   • TABLE_NAME — the DynamoDB table for that env (e.g. basisbeeld-providers-test).
   • CONTENT_BUCKET — the S3 bucket holding the gmfiles/ provider-name objects.
   • USER_POOL_ID — the Cognito user pool id (used by paused login tracking).
   • PRE_TOKEN_LOG_GROUP_PREFIX — CloudWatch log group prefix for the pre-token-generation Lambda.

   src/config.json is gitignored so your local profile names and bucket ids stay out of the repo.

2. Make sure your SSO profiles work.

   aws sso login --profile admin-test-profile
   aws sso login --profile admin-prod-profile

   Required permissions per profile. The dashboard is read-only, so a permission set with the following actions on the relevant resources is enough:

   • dynamodb:Scan, dynamodb:Query, dynamodb:GetItem, dynamodb:BatchGetItem, dynamodb:DescribeTable on the configured TABLE_NAME — used to read meetings, meldingen, onderzoeken, vragenlijsten, samenwerkingsverbanden, and aanbieder records.
   • s3:ListBucket, s3:GetObject on the configured CONTENT_BUCKET (limited to the gmfiles/ prefix is enough) — used to resolve KVK numbers to provider names.
   • cognito-idp:ListUserPools, cognito-idp:ListUserPoolClients on the configured USER_POOL_ID — only required if the paused login chart is re-enabled.
   • logs:DescribeLogGroups, logs:StartQuery, logs:GetQueryResults, and cloudtrail:LookupEvents — also paused; needed only when the login/auth chart is restored.

   In practice an AdministratorAccess or equivalent broad read role works, but the minimum needed is the DynamoDB + S3 actions above. The bundled src/ddb.mjs allow-list refuses any write command before the SDK is even called, so a read-only permission set won't break anything.

3. Install dependencies and start.

   npm install
   npm start
   # open http://localhost:4200 (or whatever PORT you set)

Daily use

aws sso login --profile admin-test-profile
npm start

Switch between environments with the Test / Prod toggle in the header. Pressing Reload invalidates the local cache and re-scans DynamoDB.

Read-only safety

This tool will never write to DynamoDB. Three layers:

1. Wrapped client (src/ddb.mjs) — only forwards an allow-list of read commands (Query, Scan, GetItem, BatchGetItem, DescribeTable). Anything else throws before the SDK is called.
2. No write code paths — the codebase imports zero write commands. Verify with npm run check:no-writes.
3. Recommended (infra follow-up) — add a BasisbeeldDashboardReadOnly SSO permission set in basisbeeld-infra so the credentials themselves can't write.

Implementation notes

Each concept is a separate DynamoDB Scan with a FilterExpression on Type and CA between [from, to]. Vragenlijsten reads two Type codes (vrag and the legacy ques) until the infra-side migration runs. Results are file-cached under .cache/ keyed on env + from + to; press Reload (or use the ?nocache=1 query param) to bust the cache.

Reference: data model lives in ../basisbeeld-infra/api/lambdas/basisData/service/dynamodb/entity/.