@tech4good/angular-schematics 21.6.0 → 21.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -0
- package/README.md +266 -1
- package/package.json +34 -7
- package/src/component/files/__name@dasherize__/__name@dasherize__.component.spec.ts.template +4 -5
- package/src/component/files/__name@dasherize__/__name@dasherize__.component.ts.template +1 -1
- package/src/entity/files/__name@dasherize__/__name@dasherize__.mock.ts.template +14 -6
- package/src/entity/files/__name@dasherize__/__name@dasherize__.model.ts.template +12 -6
- package/src/entity/files/__name@dasherize__/__name@dasherize__.store.ts.template +18 -10
- package/src/entity/index.js +4 -49
- package/src/entity/index.js.map +1 -1
- package/src/guard/files/__name@dasherize__.guard.spec.ts.template +0 -1
- package/src/ng-add/files/.github/workflows/angular-github-ci.yml.template +3 -0
- package/src/ng-add/files/.gitignore.template +3 -0
- package/src/ng-add/files/analytics/datasets.js.template +206 -0
- package/src/ng-add/files/analytics/entity_sources.js.template +58 -0
- package/src/ng-add/files/analytics/entity_sources.test.js.template +57 -0
- package/src/ng-add/files/analytics/lib/api_query.js.template +87 -0
- package/src/ng-add/files/analytics/lib/api_query.test.js.template +84 -0
- package/src/ng-add/files/analytics/lib/bigquery_query_compatibility.test.js.template +53 -0
- package/src/ng-add/files/analytics/lib/dataset_schema.js.template +53 -0
- package/src/ng-add/files/analytics/lib/dataset_schema.test.js.template +34 -0
- package/src/ng-add/files/analytics/lib/entity_sync.js.template +397 -0
- package/src/ng-add/files/analytics/lib/entity_sync.test.js.template +212 -0
- package/src/ng-add/files/analytics/lib/identifier_salt.js.template +57 -0
- package/src/ng-add/files/analytics/lib/identifier_salt.test.js.template +36 -0
- package/src/ng-add/files/analytics/lib/snapshot_files.js.template +46 -0
- package/src/ng-add/files/analytics/lib/snapshot_files.test.js.template +67 -0
- package/src/ng-add/files/analytics/lib/sqlite.js.template +92 -0
- package/src/ng-add/files/analytics/lib/upload_entities.js.template +81 -0
- package/src/ng-add/files/analytics/lib/upload_entities.test.js.template +86 -0
- package/src/ng-add/files/analytics/proxy.conf.json.template +7 -0
- package/src/ng-add/files/analytics/scripts/refresh_snapshot.js.template +518 -0
- package/src/ng-add/files/analytics/scripts/start.js.template +88 -0
- package/src/ng-add/files/analytics/server/server.js.template +212 -0
- package/src/ng-add/files/angular.json.template +80 -1
- package/src/ng-add/files/bigquery/queries/active_time_by_route.sql.template +27 -8
- package/src/ng-add/files/bigquery/queries/active_user_windows.sql.template +67 -0
- package/src/ng-add/files/bigquery/queries/dashboard_route_visits.sql.template +47 -0
- package/src/ng-add/files/bigquery/queries/data_quality.sql.template +323 -0
- package/src/ng-add/files/bigquery/queries/onboarding_funnel.sql.template +512 -0
- package/src/ng-add/files/bigquery/queries/onboarding_stage_observations.sql.template +134 -0
- package/src/ng-add/files/bigquery/queries/weekly_retention_cohorts.sql.template +90 -0
- package/src/ng-add/files/bigquery/scripts/export_entities.js.template +120 -0
- package/src/ng-add/files/bigquery/scripts/init_views.js.template +57 -0
- package/src/ng-add/files/bigquery/scripts/run_query.js.template +141 -0
- package/src/ng-add/files/bigquery/views/events_flat.sql.template +27 -12
- package/src/ng-add/files/bigquery/views/logs_latest.sql.template +16 -3
- package/src/ng-add/files/docs-infra/analytics-guide.md.template +270 -25
- package/src/ng-add/files/docs-infra/analytics-workbench-guide.md.template +307 -0
- package/src/ng-add/files/docs-infra/authentication-architecture.md.template +54 -24
- package/src/ng-add/files/docs-infra/email-infrastructure.md.template +43 -0
- package/src/ng-add/files/docs-infra/firestore-index-checker.md.template +87 -0
- package/src/ng-add/files/docs-infra/infrastructure-guide.md.template +108 -29
- package/src/ng-add/files/docs-infra/load-system-architecture.md.template +15 -1
- package/src/ng-add/files/docs-infra/querying-strategy.md.template +14 -0
- package/src/ng-add/files/docs-infra/stream-system-architecture.md.template +21 -7
- package/src/ng-add/files/eslint.config.js.template +22 -3
- package/src/ng-add/files/functions/package.json.template +1 -0
- package/src/ng-add/files/functions/src/email.ts.template +23 -0
- package/src/ng-add/files/jest.config.ts.template +3 -2
- package/src/ng-add/files/package.json.template +39 -16
- package/src/ng-add/files/projects/analytics/src/app/analytics-api.service.ts.template +130 -0
- package/src/ng-add/files/projects/analytics/src/app/app.component.html.template +77 -0
- package/src/ng-add/files/projects/analytics/src/app/app.component.scss.template +240 -0
- package/src/ng-add/files/projects/analytics/src/app/app.component.ts.template +96 -0
- package/src/ng-add/files/projects/analytics/src/app/app.routes.ts.template +11 -0
- package/src/ng-add/files/projects/analytics/src/app/dashboard-pages.spec.ts.template +151 -0
- package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.html.template +39 -0
- package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.scss.template +1 -0
- package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.ts.template +95 -0
- package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.html.template +47 -0
- package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.scss.template +1 -0
- package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.ts.template +120 -0
- package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.html.template +40 -0
- package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.scss.template +1 -0
- package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.ts.template +98 -0
- package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.html.template +35 -0
- package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.scss.template +1 -0
- package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.ts.template +84 -0
- package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.html.template +42 -0
- package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.scss.template +1 -0
- package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.ts.template +110 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/analytics-utils.ts.template +43 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/chart-theme.ts.template +42 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-layout.scss.template +239 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.html.template +76 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.scss.template +128 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.spec.ts.template +31 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.ts.template +153 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.html.template +16 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.scss.template +63 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.ts.template +52 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.html.template +5 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.scss.template +56 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.spec.ts.template +30 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.ts.template +15 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.html.template +9 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.scss.template +43 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.ts.template +62 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.html.template +9 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.scss.template +33 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.ts.template +82 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.html.template +15 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.scss.template +45 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.ts.template +55 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.html.template +18 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.scss.template +45 -0
- package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.ts.template +15 -0
- package/src/ng-add/files/projects/analytics/src/app/vega-chart/vega-chart.component.ts.template +121 -0
- package/src/ng-add/files/projects/analytics/src/index.html.template +19 -0
- package/src/ng-add/files/projects/analytics/src/main.ts.template +16 -0
- package/src/ng-add/files/projects/analytics/src/styles.scss.template +28 -0
- package/src/ng-add/files/projects/analytics/tsconfig.app.json.template +13 -0
- package/src/ng-add/files/projects/analytics/tsconfig.spec.json.template +15 -0
- package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/admin/admin-panel/admin-settings/admin-settings.component.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.spec.ts.template +11 -12
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.ts.template +7 -7
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.spec.ts.template +8 -10
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.ts.template +3 -2
- package/src/ng-add/files/src/app/app.component.html.template +1 -1
- package/src/ng-add/files/src/app/app.component.scss.template +1 -1
- package/src/ng-add/files/src/app/app.component.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/app.component.ts.template +1 -2
- package/src/ng-add/files/src/app/app.config.ts.template +21 -15
- package/src/ng-add/files/src/app/auth-routing.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/core/analytics/time-analytics.service.spec.ts.template +46 -29
- package/src/ng-add/files/src/app/core/analytics/time-analytics.service.ts.template +27 -18
- package/src/ng-add/files/src/app/core/auth/auth.providers.spec.ts.template +112 -0
- package/src/ng-add/files/src/app/core/auth/auth.providers.ts.template +48 -0
- package/src/ng-add/files/src/app/core/auth/auth.service.ts.template +9 -23
- package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.spec.ts.template +3 -14
- package/src/ng-add/files/src/app/core/firebase/data.providers.prod.ts.template +21 -0
- package/src/ng-add/files/src/app/core/firebase/data.providers.ts.template +13 -0
- package/src/ng-add/files/src/app/core/local-storage/session.service.spec.ts.template +43 -0
- package/src/ng-add/files/src/app/core/local-storage/session.service.ts.template +7 -0
- package/src/ng-add/files/src/app/core/store/app-data.spec.ts.template +76 -0
- package/src/ng-add/files/src/app/core/store/auth/auth.mock.ts.template +19 -67
- package/src/ng-add/files/src/app/core/store/auth/auth.store.spec.ts.template +102 -12
- package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +32 -237
- package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +17 -12
- package/src/ng-add/files/src/app/core/store/user/user.model.ts.template +6 -7
- package/src/ng-add/files/src/app/core/store/user/user.store.ts.template +14 -10
- package/src/ng-add/files/src/app/core/store/user-context/user-context.mock.ts.template +20 -8
- package/src/ng-add/files/src/app/core/store/user-context/user-context.model.ts.template +5 -6
- package/src/ng-add/files/src/app/core/store/user-context/user-context.store.ts.template +14 -10
- package/src/ng-add/files/src/app/core/store/user-private/user-private.mock.ts.template +20 -7
- package/src/ng-add/files/src/app/core/store/user-private/user-private.model.ts.template +5 -6
- package/src/ng-add/files/src/app/core/store/user-private/user-private.store.ts.template +14 -10
- package/src/ng-add/files/src/app/core/testing/app-mocks.ts.template +42 -0
- package/src/ng-add/files/src/app/first-time/consent/consent.component.html.template +2 -1
- package/src/ng-add/files/src/app/first-time/consent/consent.component.scss.template +7 -3
- package/src/ng-add/files/src/app/first-time/consent/consent.component.spec.ts.template +31 -11
- package/src/ng-add/files/src/app/first-time/consent/consent.component.ts.template +16 -1
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +15 -15
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +11 -3
- package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.html.template +2 -1
- package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.scss.template +7 -3
- package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.spec.ts.template +20 -6
- package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.ts.template +2 -0
- package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/first-time/email-link/email-link.component.spec.ts.template +17 -1
- package/src/ng-add/files/src/app/first-time/email-link/email-link.component.ts.template +15 -0
- package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +15 -0
- package/src/ng-add/files/src/app/first-time/landing/landing.component.spec.ts.template +2 -0
- package/src/ng-add/files/src/app/first-time/login/login.component.spec.ts.template +21 -3
- package/src/ng-add/files/src/app/first-time/login/login.component.ts.template +26 -0
- package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.spec.ts.template +4 -2
- package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.ts.template +1 -1
- package/src/ng-add/files/src/app/main/account-profile/account-profile.component.spec.ts.template +2 -2
- package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.spec.ts.template +2 -2
- package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.spec.ts.template +4 -4
- package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.spec.ts.template +2 -2
- package/src/ng-add/files/src/app/main/home/home.component.spec.ts.template +4 -5
- package/src/ng-add/files/src/app/main/home/home.component.ts.template +1 -1
- package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.spec.ts.template +4 -4
- package/src/ng-add/files/src/app/shared/navbar/navbar.component.spec.ts.template +2 -2
- package/src/ng-add/files/tsconfig.spec.json.template +3 -1
- package/src/ng-add/index.js +7 -0
- package/src/ng-add/index.js.map +1 -1
- package/src/shared/entity-registry.d.ts +8 -0
- package/src/shared/entity-registry.js +28 -0
- package/src/shared/entity-registry.js.map +1 -0
- package/.agents/skills/publish-npm/SKILL.md +0 -37
- package/.agents/skills/publish-npm/eval.yaml +0 -32
- package/.agents/skills/publish-npm/fixtures/package-v21.json.template +0 -8
- package/.husky/commit-msg +0 -1
- package/.husky/pre-commit +0 -1
- package/.t4g/agent-memory.db +0 -0
- package/src/component/index_spec.d.ts +0 -1
- package/src/component/index_spec.js +0 -68
- package/src/component/index_spec.js.map +0 -1
- package/src/entity/index_spec.d.ts +0 -1
- package/src/entity/index_spec.js +0 -153
- package/src/entity/index_spec.js.map +0 -1
- package/src/guard/index_spec.d.ts +0 -1
- package/src/guard/index_spec.js +0 -64
- package/src/guard/index_spec.js.map +0 -1
- package/src/ng-add/files/bigquery/scripts/export_entities.py.template +0 -143
- package/src/ng-add/files/bigquery/scripts/run_query.py.template +0 -167
- package/src/ng-add/files/src/app/core/firebase/cached-listeners.service.ts.template +0 -500
- package/src/ng-add/files/src/app/core/firebase/database.service.ts.template +0 -73
- package/src/ng-add/files/src/app/core/firebase/email-link-context.service.spec.ts.template +0 -59
- package/src/ng-add/files/src/app/core/firebase/email-link-context.service.ts.template +0 -147
- package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +0 -453
- package/src/ng-add/files/src/app/core/firebase/firebase.service.spec.ts.template +0 -116
- package/src/ng-add/files/src/app/core/firebase/firebase.service.ts.template +0 -639
- package/src/ng-add/files/src/app/core/firebase/simulate-load.spec.ts.template +0 -104
- package/src/ng-add/files/src/app/core/firebase/simulate-stream.spec.ts.template +0 -127
- package/src/ng-add/files/src/app/core/firebase/simulation.mock.ts.template +0 -38
- package/src/ng-add/files/src/app/core/firebase/stream-multiplexer.ts.template +0 -445
- package/src/ng-add/files/src/app/core/logging/logging.service.spec.ts.template +0 -118
- package/src/ng-add/files/src/app/core/logging/logging.service.ts.template +0 -168
- package/src/ng-add/files/src/app/core/store/app.model.ts.template +0 -21
- package/src/ng-add/files/src/app/core/store/app.store.spec.ts.template +0 -920
- package/src/ng-add/files/src/app/core/store/app.store.ts.template +0 -1320
- package/src/ng-add/files/src/app/core/store/batch-write.firebase.service.ts.template +0 -58
- package/src/ng-add/files/src/app/core/store/batch-write.mock.service.ts.template +0 -105
- package/src/ng-add/files/src/app/core/store/batch-write.service.ts.template +0 -126
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.html.template +0 -9
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.scss.template +0 -46
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.spec.ts.template +0 -69
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.ts.template +0 -39
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.spec.ts.template +0 -122
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.ts.template +0 -88
- package/src/ng-add/index_spec.d.ts +0 -1
- package/src/ng-add/index_spec.js +0 -108
- package/src/ng-add/index_spec.js.map +0 -1
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Analytics Workbench Architecture Guide
|
|
2
|
+
|
|
3
|
+
This guide explains how the analytics workbench is structured, covering both
|
|
4
|
+
the server-side offline snapshot engine (`analytics/`) and the Angular frontend
|
|
5
|
+
application (`projects/analytics/`).
|
|
6
|
+
|
|
7
|
+
If you're looking for instructions on setting up BigQuery, running snapshots,
|
|
8
|
+
or adding telemetry, see `analytics-guide.md`.
|
|
9
|
+
|
|
10
|
+
## File map
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
analytics/ ← Server & Snapshot Infrastructure
|
|
14
|
+
├── datasets.js ← Dataset schema registry & API filter/sort contracts
|
|
15
|
+
├── entity_sources.js ← Project-specific Firestore entity derivations
|
|
16
|
+
├── proxy.conf.json ← Angular CLI proxy configuration (port 4321)
|
|
17
|
+
│
|
|
18
|
+
├── server/
|
|
19
|
+
│ └── server.js ← Node.js HTTP server: serves SQLite REST API & static Angular app
|
|
20
|
+
│
|
|
21
|
+
├── scripts/
|
|
22
|
+
│ ├── refresh_snapshot.js ← Pulls BigQuery SQL / Firestore, applies salt, builds SQLite db
|
|
23
|
+
│ └── start.js ← Verification launcher script (checks build & snapshot)
|
|
24
|
+
│
|
|
25
|
+
└── lib/
|
|
26
|
+
├── api_query.js ← Query builder: safe filtering/sorting/pagination for dataset APIs
|
|
27
|
+
├── dataset_schema.js ← Metadata generator and column type normalizer
|
|
28
|
+
├── entity_sync.js ← Incremental Firestore document fetcher & pseudonymizer engine
|
|
29
|
+
├── identifier_salt.js ← Manages local secret salt for de-identifying user/session keys
|
|
30
|
+
├── snapshot_files.js ← Atomic snapshot management and current pointer file writing
|
|
31
|
+
├── upload_entities.js ← BigQuery load jobs for entity-derived dimensions
|
|
32
|
+
└── sqlite.js ← Promisified Node sqlite3 database helpers
|
|
33
|
+
|
|
34
|
+
projects/analytics/src/app/ ← Angular Workbench Client
|
|
35
|
+
├── analytics-api.service.ts ← HTTP layer: native Node API + admin-variant selection
|
|
36
|
+
├── app.component.ts ← Root shell: sidebar nav, header, router-outlet
|
|
37
|
+
├── app.routes.ts ← Lazy-loaded route per dashboard page
|
|
38
|
+
├── shared/
|
|
39
|
+
│ ├── analytics-utils.ts ← Formatting helpers (compact, seconds, percent, etc.)
|
|
40
|
+
│ ├── chart-theme.ts ← Color palette + Vega-Lite base config
|
|
41
|
+
│ ├── dashboard-layout.scss ← Shared page/grid/card layout styles
|
|
42
|
+
│ ├── metric-card/ ← Presentational: label, value, note, tone
|
|
43
|
+
│ ├── dashboard-table/ ← Presentational: sortable/filterable data table
|
|
44
|
+
│ ├── status-message/ ← Presentational: loading, error, empty-snapshot states
|
|
45
|
+
│ ├── route-traffic-chart/ ← Vega chart: bar+dot traffic and attention
|
|
46
|
+
│ ├── route-distribution-chart/ ← Vega chart: IQR interval plot
|
|
47
|
+
│ ├── funnel-chart/ ← Vega chart: conversion funnel with stage labels
|
|
48
|
+
│ └── quality-chart/ ← Vega chart: horizontal severity bars
|
|
49
|
+
│
|
|
50
|
+
├── overview/overview-page/ ← Dashboard: snapshot pulse (traffic, conversion, quality)
|
|
51
|
+
├── onboarding/onboarding-page/ ← Dashboard: acquisition and activation funnels
|
|
52
|
+
├── routes/routes-page/ ← Dashboard: route engagement with linked table
|
|
53
|
+
├── engagement/engagement-page/ ← Dashboard: active identities and retention
|
|
54
|
+
├── data-quality/data-quality-page/ ← Dashboard: evidence health diagnostics
|
|
55
|
+
│
|
|
56
|
+
└── vega-chart/
|
|
57
|
+
└── vega-chart.component.ts ← Vega-Lite rendering wrapper with signal bridging
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## How the pieces fit together
|
|
61
|
+
|
|
62
|
+
Each dashboard is a standalone Angular component with its own route:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
URL /overview
|
|
66
|
+
│
|
|
67
|
+
▼
|
|
68
|
+
OverviewPageComponent (lazy-loaded)
|
|
69
|
+
│
|
|
70
|
+
├─ fetches required datasets via ──▶ AnalyticsApiService
|
|
71
|
+
│ │
|
|
72
|
+
│ ▼
|
|
73
|
+
│ localhost:4321
|
|
74
|
+
│ (native Node server → SQLite snapshot)
|
|
75
|
+
│
|
|
76
|
+
├─ computes metrics as signals
|
|
77
|
+
│
|
|
78
|
+
└─ renders directly in its template
|
|
79
|
+
├─ <analytics-metric-card /> ← shared presentational
|
|
80
|
+
├─ <analytics-route-traffic-chart /> ← emits selectionChange
|
|
81
|
+
├─ <analytics-dashboard-table /> ← receives page-filtered rows
|
|
82
|
+
└─ page-local signals connect the chart selection to the table
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
No dynamic dispatch or plugin registry — you can open any page template and
|
|
86
|
+
immediately see what charts, metrics, and tables appear on that page.
|
|
87
|
+
|
|
88
|
+
## Server & Snapshot Engine (`analytics/`)
|
|
89
|
+
|
|
90
|
+
The backend layer provides an offline-first, de-identified data access service backed by local SQLite database snapshots.
|
|
91
|
+
|
|
92
|
+
### Dataset Registry (`datasets.js`)
|
|
93
|
+
|
|
94
|
+
Defines the schema, SQL/Firestore data sources, privacy invariants, and API contracts for all analytics datasets:
|
|
95
|
+
|
|
96
|
+
- **Privacy levels**: Enforces `aggregate` or `deidentified-observation` rules per dataset.
|
|
97
|
+
- **API contracts**: Defines allowed filter fields (`filterFields`), sorting options (`sortFields`), default direction, and `maxRows` limits. Serves as a server-side allowlist to prevent arbitrary SQL parameters.
|
|
98
|
+
|
|
99
|
+
### Firestore Entity Sources (`entity_sources.js`)
|
|
100
|
+
|
|
101
|
+
The generated entity registry derives `user-dimensions` from user documents,
|
|
102
|
+
pseudonymizes each
|
|
103
|
+
document ID with the same lower-case, salted SHA-256 representation used for
|
|
104
|
+
analytics event user IDs, and records role, access state, and source timestamps.
|
|
105
|
+
|
|
106
|
+
Entity rows have two destinations:
|
|
107
|
+
|
|
108
|
+
- the local SQLite snapshot, where all registered datasets are available to the
|
|
109
|
+
workbench; and
|
|
110
|
+
- for definitions with `uploadToBigQuery: true`, a BigQuery dimension table.
|
|
111
|
+
|
|
112
|
+
`user-dimensions` uses the second path to replace `analytics.dim_user` on every
|
|
113
|
+
refresh. Metric queries can therefore join events to current user roles before
|
|
114
|
+
their aggregate results are written locally. The entity sync cache still uses
|
|
115
|
+
incremental Firestore cursors; the BigQuery table uses a full `WRITE_TRUNCATE`
|
|
116
|
+
load of the current derived dimension so removed or changed users do not leave
|
|
117
|
+
stale rows behind.
|
|
118
|
+
|
|
119
|
+
### Snapshot Generation (`scripts/refresh_snapshot.js`)
|
|
120
|
+
|
|
121
|
+
Executed via `npm run analytics:refresh`:
|
|
122
|
+
1. Updates the reusable BigQuery views.
|
|
123
|
+
2. Incrementally syncs Firestore entity sources into the local entity cache and
|
|
124
|
+
applies salted SHA-256 pseudonymization.
|
|
125
|
+
3. Uploads opted-in entity datasets such as `user-dimensions` to BigQuery.
|
|
126
|
+
4. Executes registered BigQuery metrics. Datasets with `adminVariants: true`
|
|
127
|
+
run twice, once including admins and once excluding them, and store the
|
|
128
|
+
discriminator column `_includes_admin` with each row.
|
|
129
|
+
5. Writes query and entity rows into a timestamped SQLite database under
|
|
130
|
+
`.local/analytics/snapshots/`, validates it, and atomically updates
|
|
131
|
+
`.local/analytics/current.json`.
|
|
132
|
+
|
|
133
|
+
### HTTP Server (`server/server.js`)
|
|
134
|
+
|
|
135
|
+
A native Node.js HTTP server running on `http://127.0.0.1:4321`:
|
|
136
|
+
- Opens local SQLite snapshots in **read-only mode** (`sqlite3.OPEN_READONLY`).
|
|
137
|
+
- `GET /api/status` — Returns snapshot metadata (creation time, query durations, schema versions) and dataset availability.
|
|
138
|
+
- `GET /api/datasets/:id?includeAdmin=1|0` — Serves filtered, sorted, and
|
|
139
|
+
paginated dataset rows computed safely by `lib/api_query.js`. For
|
|
140
|
+
admin-variant datasets the server converts this option into an enforced
|
|
141
|
+
`_includes_admin` filter; it is not arbitrary client SQL.
|
|
142
|
+
- Serves static Angular production build assets (`dist/analytics/browser`) when serving client routes.
|
|
143
|
+
|
|
144
|
+
### Support Libraries (`lib/`)
|
|
145
|
+
|
|
146
|
+
- `api_query.js`: Parameterized SQL generator enforcing column allowlists, filter operators, and pagination offsets.
|
|
147
|
+
- `dataset_schema.js`: Validates dataset structures and generates SQLite table definitions.
|
|
148
|
+
- `entity_sync.js`: Manages incremental Firestore collection sync, document hashing, and SQLite caching.
|
|
149
|
+
- `identifier_salt.js`: Generates and manages the local salt key used for de-identifying user and journey keys.
|
|
150
|
+
- `snapshot_files.js`: Handles directory management and pointer updates for `.local/analytics/`.
|
|
151
|
+
- `upload_entities.js`: Loads opted-in entity datasets into BigQuery and waits for the load job result.
|
|
152
|
+
- `sqlite.js`: Async/await wrappers over the `sqlite3` driver.
|
|
153
|
+
|
|
154
|
+
## Shared utilities
|
|
155
|
+
|
|
156
|
+
### `analytics-utils.ts`
|
|
157
|
+
|
|
158
|
+
Pure formatting functions used by page components to compute display values:
|
|
159
|
+
|
|
160
|
+
- `numeric(value)` — safe conversion to finite number
|
|
161
|
+
- `compact(value)` — compact number formatting (e.g. 1.2K)
|
|
162
|
+
- `seconds(value)` — human-readable duration (e.g. "2.5 min", "18 sec")
|
|
163
|
+
- `percent(value)` — percentage formatting
|
|
164
|
+
- `snapshotAge(createdAt)` — relative time string (e.g. "5 min ago")
|
|
165
|
+
- `routeSelection(value)` — extracts a route name from a Vega signal map
|
|
166
|
+
|
|
167
|
+
### `chart-theme.ts`
|
|
168
|
+
|
|
169
|
+
Shared visual identity for all Vega-Lite charts:
|
|
170
|
+
|
|
171
|
+
- `palette` — named colors (forest, mint, gold, clay, ink, grid)
|
|
172
|
+
- `chartConfig` — axis/legend typography and styling
|
|
173
|
+
- `baseSpec()` — returns the Vega-Lite v6 schema base with autosize and container width
|
|
174
|
+
|
|
175
|
+
### `dashboard-layout.scss`
|
|
176
|
+
|
|
177
|
+
Shared SCSS imported by each page component. Defines layout classes:
|
|
178
|
+
`.page`, `.page-header`, `.eyebrow`, `h1`, `.description`, `.metric-grid`,
|
|
179
|
+
`.chart-grid`, `.chart-card`, `.chart-card.wide`, `footer`, and responsive
|
|
180
|
+
breakpoints.
|
|
181
|
+
|
|
182
|
+
## Shared components
|
|
183
|
+
|
|
184
|
+
### `MetricCardComponent`
|
|
185
|
+
|
|
186
|
+
Simple stat display card.
|
|
187
|
+
|
|
188
|
+
| Input | Type | Description |
|
|
189
|
+
|---|---|---|
|
|
190
|
+
| `label` | `string` (required) | Metric name |
|
|
191
|
+
| `value` | `string` (required) | Formatted value |
|
|
192
|
+
| `note` | `string` (required) | Contextual note below the value |
|
|
193
|
+
| `tone` | `'positive' \| 'warning'` | Optional color accent |
|
|
194
|
+
|
|
195
|
+
### `DashboardTableComponent`
|
|
196
|
+
|
|
197
|
+
Sortable, filterable data table with formatted cell values.
|
|
198
|
+
|
|
199
|
+
| Input | Type | Description |
|
|
200
|
+
|---|---|---|
|
|
201
|
+
| `title` | `string` (required) | Table heading |
|
|
202
|
+
| `subtitle` | `string` (required) | Description below heading |
|
|
203
|
+
| `columns` | `TableColumn[]` (required) | Column definitions with key, label, format |
|
|
204
|
+
| `rows` | `Record<string, unknown>[]` (required) | Row data |
|
|
205
|
+
| `sortable` | `boolean` | Enable column sort headers |
|
|
206
|
+
| `routeFilter` | `boolean` | Enable route text filter |
|
|
207
|
+
| `initialSortKey` | `string \| null` | Default sort column |
|
|
208
|
+
| `initialSortDirection` | `'asc' \| 'desc'` | Default sort direction |
|
|
209
|
+
|
|
210
|
+
### `StatusMessageComponent`
|
|
211
|
+
|
|
212
|
+
Handles loading, error, and empty-snapshot states.
|
|
213
|
+
|
|
214
|
+
| Input | Type | Description |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| `loading` | `boolean` | Shows progress bar |
|
|
217
|
+
| `error` | `string \| null` | Shows error card with message |
|
|
218
|
+
| `available` | `boolean` | When false and not loading, shows setup guidance |
|
|
219
|
+
|
|
220
|
+
## Chart components
|
|
221
|
+
|
|
222
|
+
Each chart component wraps `VegaChartComponent` with a specific Vega-Lite
|
|
223
|
+
specification. The spec is a `computed()` signal derived from the input data.
|
|
224
|
+
|
|
225
|
+
| Component | Input | Output | What it renders |
|
|
226
|
+
|---|---|---|---|
|
|
227
|
+
| `RouteTrafficChartComponent` | `rows` | `selectionChange` | Layered bar+point chart of visits and median active time |
|
|
228
|
+
| `RouteDistributionChartComponent` | `rows` | — | IQR interval plot with median marker |
|
|
229
|
+
| `FunnelChartComponent` | `title`, `subtitle`, `rows`, `stageHelp` | — | Vertical bar conversion funnel with stage axis labels |
|
|
230
|
+
| `QualityChartComponent` | `rows` | — | Horizontal bar chart with severity-colored diagnostics |
|
|
231
|
+
|
|
232
|
+
## Page components (dashboards)
|
|
233
|
+
|
|
234
|
+
Each page component follows the same pattern:
|
|
235
|
+
|
|
236
|
+
1. Injects `AnalyticsApiService` and subscribes to `status()` in the constructor
|
|
237
|
+
2. Fetches its required datasets via `forkJoin`
|
|
238
|
+
3. Computes metrics, chart data, and table rows as `computed()` signals
|
|
239
|
+
4. Renders shared and chart components directly in its template
|
|
240
|
+
5. Keeps linked-chart selection in page-local signals where a page needs it
|
|
241
|
+
|
|
242
|
+
| Page | Route | Datasets | Key visualizations |
|
|
243
|
+
|---|---|---|---|
|
|
244
|
+
| `OverviewPageComponent` | `/overview` | route-engagement, onboarding-cohorts, data-quality | Route traffic chart, acquisition funnel |
|
|
245
|
+
| `OnboardingPageComponent` | `/onboarding` | onboarding-cohorts | Pre-sign-in funnel, post-sign-in funnel |
|
|
246
|
+
| `RoutesPageComponent` | `/routes` | route-engagement | Traffic chart, distribution chart, linked statistics table |
|
|
247
|
+
| `EngagementPageComponent` | `/engagement` | active-user-windows, weekly-retention-cohorts | Daily/weekly/monthly active identities, WAU/MAU, retention cohorts |
|
|
248
|
+
| `DataQualityPageComponent` | `/data-quality` | data-quality | Quality diagnostics chart, details table |
|
|
249
|
+
|
|
250
|
+
## Linked chart selection
|
|
251
|
+
|
|
252
|
+
Charts emit `selectionChange` from Vega signals. A page that links a chart and
|
|
253
|
+
table stores the selected value in its own signal, derives filtered rows with a
|
|
254
|
+
`computed()` signal, and clears the local value when Vega emits an empty
|
|
255
|
+
selection. This keeps interaction state visible in the page that owns it and
|
|
256
|
+
avoids hidden cross-page state.
|
|
257
|
+
|
|
258
|
+
## Vega Chart (`vega-chart.component.ts`)
|
|
259
|
+
|
|
260
|
+
A thin wrapper around the `vega-embed` library. It:
|
|
261
|
+
|
|
262
|
+
- Accepts a Vega-Lite `spec` input and renders it into a DOM container
|
|
263
|
+
- Attaches a `ResizeObserver` to keep charts responsive
|
|
264
|
+
- Listens for named Vega signals and emits `selectionChange` events
|
|
265
|
+
- Cleans up view instances and observers on destroy
|
|
266
|
+
|
|
267
|
+
## API Service (`analytics-api.service.ts`)
|
|
268
|
+
|
|
269
|
+
HTTP client that talks to the native Node analytics server (port 4321):
|
|
270
|
+
|
|
271
|
+
- `status()`: `GET /api/status` — snapshot metadata and dataset availability
|
|
272
|
+
- `dataset(id)`: `GET /api/datasets/:id` — filtered/sorted/paginated rows; the
|
|
273
|
+
service automatically appends the current `includeAdmin` signal value
|
|
274
|
+
- Polls `/api/status` every 15 seconds to detect background snapshot refreshes
|
|
275
|
+
- Exposes `hasNewSnapshot` signal so the UI can show a reload prompt
|
|
276
|
+
|
|
277
|
+
## How to add a new dashboard
|
|
278
|
+
|
|
279
|
+
1. **Write the SQL query** in `bigquery/queries/your_query.sql`
|
|
280
|
+
2. **Register the dataset** in `analytics/datasets.js` — define table name,
|
|
281
|
+
columns, types, privacy level, indexes, and allowed filters/sorts. Set
|
|
282
|
+
`adminVariants: true` only when the SQL accepts the admin parameter and
|
|
283
|
+
produces both populations during refresh. Entity definitions use
|
|
284
|
+
`uploadToBigQuery: true` only when downstream SQL needs a BigQuery dimension.
|
|
285
|
+
3. **Create chart components** if you need new visualizations (use
|
|
286
|
+
`ng generate component shared/my-chart --project analytics`)
|
|
287
|
+
4. **Create the page component**:
|
|
288
|
+
```bash
|
|
289
|
+
ng generate component my-dashboard/my-dashboard-page --project analytics
|
|
290
|
+
```
|
|
291
|
+
5. **Implement the page component** — follow the existing pattern in
|
|
292
|
+
`overview-page.component.ts`: inject the API service, fetch datasets,
|
|
293
|
+
compute metrics, and render shared components in the template
|
|
294
|
+
6. **Add the route** in `app.routes.ts`:
|
|
295
|
+
```ts
|
|
296
|
+
{ path: 'my-dashboard', loadComponent: () =>
|
|
297
|
+
import('./my-dashboard/my-dashboard-page/my-dashboard-page.component')
|
|
298
|
+
.then(m => m.MyDashboardPageComponent) },
|
|
299
|
+
```
|
|
300
|
+
7. **Add to sidebar** in `app.component.ts`:
|
|
301
|
+
```ts
|
|
302
|
+
readonly dashboards = [
|
|
303
|
+
// ...existing entries...
|
|
304
|
+
{ id: 'my-dashboard', label: 'My Dashboard', category: 'Research analytics' },
|
|
305
|
+
];
|
|
306
|
+
```
|
|
307
|
+
8. **Refresh and test**: `npm run analytics:refresh` then `npm run analytics`
|
|
@@ -33,11 +33,13 @@ The application intentionally does not call `fetchSignInMethodsForEmail`. Provid
|
|
|
33
33
|
|
|
34
34
|
| Responsibility | Implementation |
|
|
35
35
|
| --- | --- |
|
|
36
|
-
| Firebase SDK operations | `
|
|
37
|
-
|
|
|
36
|
+
| Firebase SDK operations | `FirebaseAuthService` from `@tech4good/platform-auth/firebase` |
|
|
37
|
+
| Backend-independent auth contract | `AUTH_ACCESS` / `AuthAccess` from `@tech4good/platform-auth` |
|
|
38
|
+
| Profile defaults and store cleanup policy | `src/app/core/auth/auth.providers.ts` |
|
|
39
|
+
| Shared profile policy / atomic persistence | `@tech4good/platform-auth/profiles` and `/firebase` |
|
|
38
40
|
| Auth and application-user state | `src/app/core/store/auth/auth.store.ts` |
|
|
39
41
|
| Guard-facing auth resolution | `src/app/core/auth/auth.service.ts` |
|
|
40
|
-
| Email-link same-browser context | `
|
|
42
|
+
| Email-link same-browser context | `EmailLinkContextService` from `@tech4good/platform-auth` |
|
|
41
43
|
| Public entry and guest start | `src/app/first-time/landing/` |
|
|
42
44
|
| Email action and completion views | `src/app/first-time/auth-action/`, `src/app/first-time/email-link/` |
|
|
43
45
|
| Account linking/deletion UI | `src/app/main/account-profile/` |
|
|
@@ -59,7 +61,7 @@ flowchart TD
|
|
|
59
61
|
end
|
|
60
62
|
|
|
61
63
|
subgraph Infra ["Services & Infrastructure"]
|
|
62
|
-
|
|
64
|
+
FirebaseAuthService["FirebaseAuthService<br/>(Firebase Auth SDK operations)"]
|
|
63
65
|
ContextService["EmailLinkContextService<br/>(Cookie & LocalStorage context)"]
|
|
64
66
|
Firestore[("Firestore DB<br/>users/{uid} & userPrivates/{uid}")]
|
|
65
67
|
Functions["Cloud Functions<br/>(deleteAnonymousAccount)"]
|
|
@@ -69,21 +71,26 @@ flowchart TD
|
|
|
69
71
|
AuthService -->|"queries state"| AuthStore
|
|
70
72
|
Views -->|"triggers sign-in / linking"| AuthStore
|
|
71
73
|
AuthStore -->|"derives user"| UserStore
|
|
72
|
-
AuthStore -->|"calls SDK methods"|
|
|
74
|
+
AuthStore -->|"calls SDK methods"| FirebaseAuthService
|
|
73
75
|
AuthStore -->|"provisions profile"| Firestore
|
|
74
|
-
|
|
76
|
+
FirebaseAuthService -->|"stores link context"| ContextService
|
|
75
77
|
Views -->|"invokes backend deletion"| Functions
|
|
76
78
|
```
|
|
77
79
|
|
|
78
80
|
## Session model and local state
|
|
79
81
|
|
|
80
|
-
`
|
|
82
|
+
`FirebaseAuthService.afUser()` exposes Firebase Auth changes as an `AuthSession` containing:
|
|
81
83
|
|
|
82
84
|
- Firebase UID, email, display name, photo URL, anonymous state, and email-verification state;
|
|
83
85
|
- provider IDs (for example `google.com` or `password`);
|
|
84
86
|
- `emailLinkEnabled`, derived from Firebase provider metadata rather than Firestore.
|
|
85
87
|
|
|
86
|
-
`AuthStore`
|
|
88
|
+
`AuthStore` composes `withAuthSession()` from the package and adds the app's user
|
|
89
|
+
selector, guest dialog and navigation. It maintains identity in `afUser` and
|
|
90
|
+
exposes `user` from UserStore only when `authStatus` is `ready`. A session can
|
|
91
|
+
exist before the profile is ready. Profile errors remain visible in `authError`;
|
|
92
|
+
`retryProfile()` retries that identity without signing in again. Guards use
|
|
93
|
+
`AuthService.resolveUser()`, which waits for `whenReady()` and rejects on failure.
|
|
87
94
|
|
|
88
95
|
On an authenticated session, `provisionAndLoadUser()`:
|
|
89
96
|
|
|
@@ -91,26 +98,33 @@ On an authenticated session, `provisionAndLoadUser()`:
|
|
|
91
98
|
2. Loads the application user into `UserStore`.
|
|
92
99
|
3. Starts a real-time stream for that user record.
|
|
93
100
|
|
|
94
|
-
Fresh sign-in methods provision directly after Firebase reports successful sign-in. The background `loadAuth()` subscription observes the same Firebase event, but skips its own provisioning while
|
|
101
|
+
Fresh sign-in methods provision directly after Firebase reports successful sign-in. The background `loadAuth()` subscription observes the same Firebase event, but skips its own provisioning while an explicit login/link operation is in progress. This is important: Firestore can observe Firebase’s auth event before its credentials provider has installed the new token. A duplicate read in that narrow window can fail with `permission-denied` / “Missing or insufficient permissions.”
|
|
95
102
|
|
|
96
|
-
The background subscription is deliberately not unsubscribed on logout. Instead, logout tears down Firestore streams and
|
|
103
|
+
The background subscription is deliberately not unsubscribed on logout. Instead, logout tears down Firestore streams and clears auth-related state while retaining the app-wide Firebase auth observer for the next sign-in or an external auth change.
|
|
97
104
|
|
|
98
|
-
Because RxJS cannot cancel an already-running provisioning Promise, logout and account deletion first block new refresh provisioning and wait for any active refresh provisioning to settle. Only then do they tear down Firestore streams and sign out. This ordering prevents a delayed `userStore.stream()` call from recreating a listener under signed-out credentials.
|
|
105
|
+
Because RxJS cannot cancel an already-running provisioning Promise, logout and account deletion first block new refresh provisioning and wait for any active direct-login and refresh provisioning to settle. Only then do they tear down Firestore streams and sign out. This ordering prevents a delayed `userStore.stream()` call from recreating a listener under signed-out credentials.
|
|
99
106
|
|
|
100
107
|
## Account creation and profile data
|
|
101
108
|
|
|
102
|
-
`ensureUserProfile()`
|
|
109
|
+
`UserProfileService.ensureUserProfile()` runs the app's `createProfile` factory
|
|
110
|
+
when the Firebase UID has no matching document. Both public and private profile
|
|
111
|
+
changes commit atomically in a Firestore transaction; the mock adapter uses the
|
|
112
|
+
same profile policy and an atomic mock batch. Factories/reconciliation callbacks
|
|
113
|
+
must be pure because a transaction can retry them. Existing roles, consent,
|
|
114
|
+
access state and edited names are preserved by default.
|
|
115
|
+
|
|
116
|
+
The app's defaults are:
|
|
103
117
|
|
|
104
118
|
- `users/{uid}` contains the application identity and onboarding state. New accounts begin at `SUBMIT_INTEREST` and are not administrators or consented.
|
|
105
119
|
- `userPrivates/{uid}` contains the email when Firebase provides one, plus email-link capability metadata.
|
|
106
120
|
|
|
107
121
|
Google provides display name and photo URL. Those values are copied to an existing guest profile when available.
|
|
108
122
|
|
|
109
|
-
Email magic links provide a verified email address but do not provide a display name or profile image. The application
|
|
123
|
+
Email magic links provide a verified email address but do not provide a display name or profile image. The application preserves the existing guest profile, displays the email address on the account page, and uses the initials avatar fallback until the user sets a display name. A newly created profile can use the email as its fallback name when no display name is available, matching the original factory.
|
|
110
124
|
|
|
111
125
|
## Google flow
|
|
112
126
|
|
|
113
|
-
`AuthStore.signInWithGoogle()` calls `
|
|
127
|
+
`AuthStore.signInWithGoogle()` calls `FirebaseAuthService.signInWithGoogle()`, which uses `signInWithPopup` and a `GoogleAuthProvider`. The resulting session is provisioned and recorded in `AuthStore`.
|
|
114
128
|
|
|
115
129
|
`AuthStore.linkGoogle()` uses `linkWithPopup` on the current Firebase user rather than creating a second application identity. It refreshes the Firebase ID token, reprovisions the existing UID, and updates the local session. If Firebase reports `auth/credential-already-in-use`, the account page explains that the Google identity belongs to another application profile.
|
|
116
130
|
|
|
@@ -143,7 +157,7 @@ sequenceDiagram
|
|
|
143
157
|
|
|
144
158
|
### Sending
|
|
145
159
|
|
|
146
|
-
`
|
|
160
|
+
`FirebaseAuthService.sendEmailLink()` calls `sendSignInLinkToEmail` with `handleCodeInApp: true` and an action URL based on the active browser origin:
|
|
147
161
|
|
|
148
162
|
```
|
|
149
163
|
https://<current-host>/auth/action?flow=<flow>
|
|
@@ -163,7 +177,7 @@ The account page replaces its guest “Send Magic Link” button with “Magic l
|
|
|
163
177
|
|
|
164
178
|
Firebase opens its hosted action page, which redirects to the app’s `/auth/action` route. `AuthActionComponent` accepts only `mode=signIn` and forwards the request to `/email-link`. `EmailLinkComponent` completes automatically if the email is available from same-browser context; otherwise it asks the person to enter the email again.
|
|
165
179
|
|
|
166
|
-
`
|
|
180
|
+
`FirebaseAuthService.completeEmailSignInLink()` verifies the URL with `isSignInWithEmailLink` and selects a flow:
|
|
167
181
|
|
|
168
182
|
| Flow | Completion action |
|
|
169
183
|
| --- | --- |
|
|
@@ -200,26 +214,37 @@ sequenceDiagram
|
|
|
200
214
|
participant FB as Firebase Auth
|
|
201
215
|
|
|
202
216
|
Guest->>App: Request Guest Account Deletion
|
|
217
|
+
App->>App: Wait for profile provisioning
|
|
218
|
+
App->>App: clearSessionState() (Stop listeners, clear auth-related state)
|
|
203
219
|
App->>CF: Call deleteAnonymousAccount()
|
|
204
220
|
CF->>FS: Delete user-owned data (userContexts by default)
|
|
205
221
|
CF->>FS: Delete users and userPrivates docs
|
|
206
222
|
CF->>FB: Delete anonymous Firebase Auth user
|
|
207
223
|
CF-->>App: Callable returns success
|
|
208
|
-
App->>FS: resetAllStores() (Teardown Firestore listeners)
|
|
209
224
|
App->>FB: Local signOut() & patch auth state to null
|
|
210
225
|
App->>Guest: Route to /landing
|
|
211
226
|
```
|
|
212
227
|
|
|
213
228
|
## Logout and listener teardown
|
|
214
229
|
|
|
215
|
-
Before
|
|
230
|
+
Before explicit logout or guest deletion, shared auth calls the app-owned `AUTH_LIFECYCLE.clearSessionState()` hook:
|
|
231
|
+
|
|
232
|
+
1. Tears down all cached Firestore streams and nested observers, preserving records and load history.
|
|
233
|
+
2. Resets `UserStore` and `UserContextStore` along with their query/per-entity load history, and clears the telemetry session ID.
|
|
216
234
|
|
|
217
|
-
|
|
218
|
-
|
|
235
|
+
Other entity stores retain their records and load history across navigation and
|
|
236
|
+
logout, so subsequent loads can remain incremental. There is no
|
|
237
|
+
package-wide reset registry. Pending ordinary reads/writes can still update local
|
|
238
|
+
records and load history after cleanup; the auth flow separately waits for tracked
|
|
239
|
+
profile provisioning before teardown. After sign-out it clears `afUser` and navigates.
|
|
219
240
|
|
|
220
241
|
Tearing down streams before the token is invalidated avoids post-logout Firestore permission errors from active listeners. It also means views can briefly observe no current application user during teardown; components that derive data from the user must treat that state as valid. For example, the early-access `waitlistData` computed signal returns `null` instead of dereferencing a missing user.
|
|
221
242
|
|
|
222
|
-
The Firebase auth observer remains subscribed after logout. It is necessary for
|
|
243
|
+
The Firebase auth observer remains subscribed after logout. It is necessary for
|
|
244
|
+
future sign-ins and cross-tab changes. Observed sign-out and direct UID changes
|
|
245
|
+
also run the same app cleanup hook. Pending old auth completions cannot reopen
|
|
246
|
+
the old profile stream; ordinary data requests can still finish. Direct login
|
|
247
|
+
and linking methods suppress duplicate provisioning from their SDK notification.
|
|
223
248
|
|
|
224
249
|
## Routing and authorization
|
|
225
250
|
|
|
@@ -232,7 +257,12 @@ Routes in `src/app/app.routes.ts` use four layers of guard behavior:
|
|
|
232
257
|
| `earlyAccessGuard` | Keeps users in the interest/waitlist stage until their access state advances. |
|
|
233
258
|
| `requireAuthAndConsent` | Requires authentication, completion of early access, and consent before home/onboarding routes. |
|
|
234
259
|
|
|
235
|
-
`AuthService.resolveUser()`
|
|
260
|
+
`AuthService.resolveUser()` waits for shared auth's `whenReady()`, then reads the
|
|
261
|
+
app's ready-user selector or returns signed-out null. If profile assurance/loading
|
|
262
|
+
fails, the observable errors instead of waiting indefinitely. The app owns its
|
|
263
|
+
error/retry UI. `resolveSession()` still resolves raw provider metadata for guards
|
|
264
|
+
that need provider state. `AppComponent` must start `loadAuth()` before these
|
|
265
|
+
profile guards can finish.
|
|
236
266
|
|
|
237
267
|
## Firestore authorization relationship
|
|
238
268
|
|
|
@@ -261,8 +291,8 @@ When changing authentication behavior, verify:
|
|
|
261
291
|
## Related implementation references
|
|
262
292
|
|
|
263
293
|
- `src/app/core/store/auth/auth.store.ts`
|
|
264
|
-
-
|
|
265
|
-
- `src/app/core/
|
|
294
|
+
- `@tech4good/platform-auth/firebase`
|
|
295
|
+
- `@tech4good/platform-auth` and `src/app/core/auth/auth.providers.ts`
|
|
266
296
|
- `src/app/core/auth/auth.service.ts`
|
|
267
297
|
- `src/app/core/auth/guards/`
|
|
268
298
|
- `src/app/main/account-profile/`
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Transactional Email Infrastructure
|
|
2
|
+
|
|
3
|
+
<%= classify(project) %> sends automated server-side transactional emails from Firebase Cloud Functions using `@tech4good/platform-email` backed by [Resend](https://resend.com).
|
|
4
|
+
|
|
5
|
+
> **Server-side only:** Keep `@tech4good/platform-email` and `RESEND_API_KEY` strictly inside `functions/`. Never bundle email API keys into the Angular browser app.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Architecture
|
|
10
|
+
|
|
11
|
+
- **Automated transactional email**: Sent from Cloud Functions via `createAppEmailSender()` in `functions/src/email.ts`, which wraps `@tech4good/platform-email` (`createResendEmailSender`).
|
|
12
|
+
- **Authentication email**: Handled by Firebase Auth's built-in verification and password-reset templates (`/auth/action`).
|
|
13
|
+
- **Human support inbox**: Handled by your regular domain mail host (e.g., Porkbun or Google Workspace), referenced via `EMAIL_REPLY_TO` so user replies reach a real inbox.
|
|
14
|
+
|
|
15
|
+
Using Resend directly from Cloud Functions avoids storing recipient email addresses and message bodies in a Firestore `mail` collection (unlike `firestore-send-email`) and requires zero extra runtime npm dependencies.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 2. Domain & DNS Setup
|
|
20
|
+
|
|
21
|
+
1. Create a Resend account and add a dedicated sending subdomain (e.g., `mail.tech4good.dev` or `mail.<your-domain>`). Using a subdomain isolates sender reputation and leaves root domain MX records untouched.
|
|
22
|
+
2. Leave Resend's **click tracking** and **open tracking** disabled for privacy.
|
|
23
|
+
3. Add the DNS records Resend provides (DKIM `TXT` and SPF `CNAME` / `MX`+`TXT` records) in your DNS host and verify the domain.
|
|
24
|
+
4. Create a scoped Resend API key with **Sending access** restricted to your verified sending domain.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 3. Firebase Secret & Deployment
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 1. Store the Resend API key in Firebase Secret Manager
|
|
32
|
+
firebase functions:secrets:set RESEND_API_KEY --project <project-id>
|
|
33
|
+
|
|
34
|
+
# 2. (Optional) Configure sender addresses in functions/.env.<project-id>:
|
|
35
|
+
# EMAIL_FROM="<%= classify(project) %> <notifications@mail.tech4good.dev>"
|
|
36
|
+
# EMAIL_REPLY_TO="support@<your-domain>"
|
|
37
|
+
|
|
38
|
+
# 3. Build and deploy Cloud Functions
|
|
39
|
+
npm --prefix functions run build
|
|
40
|
+
firebase deploy --only functions --project <project-id>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
When `RESEND_API_KEY` is unset (for example, in local Firebase emulators), `createAppEmailSender()` runs in safe dry-run mode and logs a warning instead of failing.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Checking Firestore indexes
|
|
2
|
+
|
|
3
|
+
Run `npm run check:indexes` before deploying query changes. CI runs the same
|
|
4
|
+
command. These scripts run the compiled CLI from the `@tech4good/platform-tooling` dev
|
|
5
|
+
dependency; no copied checker script or TypeScript loader is needed.
|
|
6
|
+
|
|
7
|
+
It compares supported queries under `src/app` with the local
|
|
8
|
+
`firestore.indexes.json`. It does not contact Firestore or check deployed index
|
|
9
|
+
readiness. Tests, declaration files, and the shared database/store runtime
|
|
10
|
+
implementations are excluded; their behavior is modeled at feature call sites.
|
|
11
|
+
|
|
12
|
+
`npm run fix:indexes` appends missing composite indexes, preserves existing
|
|
13
|
+
definitions and other JSON settings, and leaves unresolved checks as failures.
|
|
14
|
+
Review the changes and deploy them with
|
|
15
|
+
`firebase deploy --only firestore:indexes`. Repeated fixes do not add duplicates.
|
|
16
|
+
|
|
17
|
+
Use `npm run check:indexes -- --project-root /path/to/app` to check another
|
|
18
|
+
application, or `npm run check:indexes -- --help` for CLI usage. Exit code 0
|
|
19
|
+
means the analyzed queries passed (or were fixed), 1 means missing indexes or
|
|
20
|
+
unresolved checks, and 2 means invalid command arguments.
|
|
21
|
+
|
|
22
|
+
Upgrade the `@tech4good/platform-tooling` dependency and commit the updated lockfile to
|
|
23
|
+
receive checker fixes. Review its release notes and run `npm run check:indexes`.
|
|
24
|
+
Application queries and index definitions remain in this repository.
|
|
25
|
+
|
|
26
|
+
## Understand missing-index messages
|
|
27
|
+
|
|
28
|
+
Starting with `0.1.0-alpha.1`, the checker labels each requirement by its query purpose:
|
|
29
|
+
|
|
30
|
+
- **Initial load**: your filters plus the store's `_deleted` filter.
|
|
31
|
+
- **Incremental reload**: a subsequent load with empty query options also adds
|
|
32
|
+
`_updatedAt > lastLoadTime` to fetch changes since the previous load.
|
|
33
|
+
- **Full load with query options**: non-empty options cause the full query to be
|
|
34
|
+
used on subsequent loads too, without an automatic `_updatedAt` cutoff.
|
|
35
|
+
- **Stream**, **count**, **aggregate**, or **direct database query**: the index
|
|
36
|
+
supports that operation, without the store's incremental-load expansion.
|
|
37
|
+
|
|
38
|
+
A range load such as `load([['problemCount', '>', 3]], {})` can need separate
|
|
39
|
+
indexes for the initial and incremental queries. Equality-only initial loads
|
|
40
|
+
may already be covered by automatic indexes, leaving only an incremental index
|
|
41
|
+
to create. If multiple calls or load stages need the same definition,
|
|
42
|
+
**Also needed for** lists their purposes and locations; the fixer adds it once.
|
|
43
|
+
Version `0.1.0-alpha.0` has the earlier messages; upgrade to `0.1.0-alpha.1` or
|
|
44
|
+
later, or trial an in-development build, to see the labels.
|
|
45
|
+
|
|
46
|
+
## Supported queries
|
|
47
|
+
|
|
48
|
+
- Store `load`, `stream`, `count`, and `aggregate` calls.
|
|
49
|
+
- Store parameters and properties typed as `InstanceType<typeof Store>`, including
|
|
50
|
+
aliases of locally imported store constructors.
|
|
51
|
+
- `Load<Entity>.create` and `Stream<Entity>.create` factories. Collection names
|
|
52
|
+
are discovered from store definitions and query-class constructors.
|
|
53
|
+
- Database `getEntities`, `streamEntities`, `streamEntitiesChanges`, `count`,
|
|
54
|
+
and `aggregate` calls with a resolvable collection path.
|
|
55
|
+
- Literal arrays/objects, constant variables and imports, readonly properties,
|
|
56
|
+
type assertions, and constant array/object spreads. Filter values can be
|
|
57
|
+
computed at runtime; field names, operators, and sort directions must resolve.
|
|
58
|
+
|
|
59
|
+
Streams use the supplied filters. Counts and aggregates add `_deleted`.
|
|
60
|
+
Loads check both initial reads and incremental reads with `_updatedAt` when
|
|
61
|
+
query options are empty. Direct single-document ID loads are exempt, while
|
|
62
|
+
factory loads may be batched into collection queries.
|
|
63
|
+
|
|
64
|
+
The checker accounts for automatic indexes, equality index merging, array modes,
|
|
65
|
+
sort direction and sequence, implicit inequality ordering, document-name
|
|
66
|
+
ordering, and collection scope. Disabled automatic indexes are reported for
|
|
67
|
+
manual review instead of changing `fieldOverrides` automatically.
|
|
68
|
+
|
|
69
|
+
Existing vector index definitions are accepted and preserved by `fix:indexes`.
|
|
70
|
+
The supported `vectorConfig` has an integer dimension from 1 to 2048 and `flat: {}`.
|
|
71
|
+
Each field must have exactly one index mode: `order`, `arrayConfig`, or `vectorConfig`.
|
|
72
|
+
Vector indexes are excluded when matching ordinary queries. Accepting their
|
|
73
|
+
configuration does not verify nearest-neighbor queries or their index coverage.
|
|
74
|
+
|
|
75
|
+
## Coverage limits
|
|
76
|
+
|
|
77
|
+
An unresolved supported call fails the check and includes its file and line.
|
|
78
|
+
Move constant filter structures into `const` declarations when possible. A
|
|
79
|
+
dynamic builder, mutable query structure, or unresolved collection must be
|
|
80
|
+
reviewed explicitly; the fixer cannot infer these safely.
|
|
81
|
+
|
|
82
|
+
Raw Firebase SDK calls, custom query APIs, collection-group queries, vector-search
|
|
83
|
+
queries, and code outside `src/app` are outside this check's coverage. A successful check means
|
|
84
|
+
the analyzed call sites have local index coverage, not that every possible
|
|
85
|
+
runtime query has been verified. Filter values that become `undefined` are
|
|
86
|
+
removed by the database runtime; the checker models the declared filter shape.
|
|
87
|
+
Use runtime validation for such conditional query shapes.
|