@tech4good/angular-schematics 21.5.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 +44 -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 +16 -7
- package/src/entity/files/__name@dasherize__/__name@dasherize__.model.ts.template +13 -6
- package/src/entity/files/__name@dasherize__/__name@dasherize__.store.ts.template +18 -10
- package/src/entity/index.js +61 -49
- package/src/entity/index.js.map +1 -1
- package/src/entity/schema.json +4 -0
- 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 +5 -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 +300 -0
- 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 +123 -38
- 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/firebase.json.template +6 -0
- package/src/ng-add/files/firestore.indexes.json.template +23 -0
- package/src/ng-add/files/firestore.rules.spec.ts.template +84 -15
- package/src/ng-add/files/firestore.rules.template +29 -17
- package/src/ng-add/files/functions/.gitignore.template +3 -0
- package/src/ng-add/files/functions/package.json.template +13 -0
- package/src/ng-add/files/functions/src/email.ts.template +23 -0
- package/src/ng-add/files/functions/src/index.ts.template +44 -0
- package/src/ng-add/files/functions/tsconfig.json.template +13 -0
- package/src/ng-add/files/jest.config.ts.template +3 -2
- package/src/ng-add/files/package.json.template +41 -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.html.template +3 -1
- package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.spec.ts.template +10 -13
- package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.ts.template +2 -0
- 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 +3 -3
- 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 +3 -2
- package/src/ng-add/files/src/app/app.config.ts.template +21 -15
- package/src/ng-add/files/src/app/app.routes.ts.template +6 -0
- package/src/ng-add/files/src/app/auth-routing.spec.ts.template +13 -9
- 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 +14 -23
- package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.spec.ts.template +27 -0
- package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.ts.template +3 -2
- package/src/ng-add/files/src/app/core/auth/guards/require-auth-and-consent.guard.ts.template +7 -2
- 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 +20 -82
- package/src/ng-add/files/src/app/core/store/auth/auth.store.spec.ts.template +217 -0
- package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +36 -172
- package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +18 -15
- package/src/ng-add/files/src/app/core/store/user/user.model.ts.template +7 -8
- 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 +6 -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/auth-action/auth-action.component.html.template +4 -0
- package/src/ng-add/files/src/app/first-time/auth-action/auth-action.component.scss.template +1 -0
- package/src/ng-add/files/src/app/first-time/auth-action/auth-action.component.ts.template +38 -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/consent/consent.guard.ts.template +5 -1
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +27 -16
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +102 -49
- package/src/ng-add/files/src/app/first-time/early-access/early-access.guard.ts.template +5 -1
- 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.html.template +18 -0
- package/src/ng-add/files/src/app/first-time/email-link/email-link.component.scss.template +2 -0
- package/src/ng-add/files/src/app/first-time/email-link/email-link.component.spec.ts.template +56 -0
- package/src/ng-add/files/src/app/first-time/email-link/email-link.component.ts.template +91 -0
- package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +11 -7
- package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.html.template +19 -7
- package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.scss.template +51 -0
- package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +44 -5
- package/src/ng-add/files/src/app/first-time/landing/landing.component.html.template +2 -1
- package/src/ng-add/files/src/app/first-time/landing/landing.component.scss.template +12 -8
- package/src/ng-add/files/src/app/first-time/landing/landing.component.spec.ts.template +33 -10
- package/src/ng-add/files/src/app/first-time/landing/landing.component.ts.template +6 -19
- package/src/ng-add/files/src/app/first-time/login/login.component.html.template +58 -6
- package/src/ng-add/files/src/app/first-time/login/login.component.scss.template +151 -22
- package/src/ng-add/files/src/app/first-time/login/login.component.spec.ts.template +30 -32
- package/src/ng-add/files/src/app/first-time/login/login.component.ts.template +85 -31
- 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.html.template +12 -0
- package/src/ng-add/files/src/app/main/account-profile/account-profile.component.scss.template +39 -0
- package/src/ng-add/files/src/app/main/account-profile/account-profile.component.spec.ts.template +68 -0
- package/src/ng-add/files/src/app/main/account-profile/account-profile.component.ts.template +20 -0
- package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.html.template +24 -0
- package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.scss.template +50 -0
- package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.spec.ts.template +65 -0
- package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.ts.template +59 -0
- package/src/ng-add/files/src/app/main/account-profile/guest-deletion-dialog.component.ts.template +51 -0
- package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.html.template +50 -0
- package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.scss.template +137 -0
- package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.spec.ts.template +57 -0
- package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.ts.template +59 -0
- package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.html.template +133 -0
- package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.scss.template +207 -0
- package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.spec.ts.template +74 -0
- package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.ts.template +130 -0
- 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 -6
- package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.html.template +15 -0
- package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.scss.template +79 -0
- package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.spec.ts.template +59 -0
- package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.ts.template +44 -0
- package/src/ng-add/files/src/app/shared/navbar/navbar.component.html.template +45 -15
- package/src/ng-add/files/src/app/shared/navbar/navbar.component.scss.template +103 -19
- package/src/ng-add/files/src/app/shared/navbar/navbar.component.spec.ts.template +73 -9
- package/src/ng-add/files/src/app/shared/navbar/navbar.component.ts.template +46 -18
- package/src/ng-add/files/src/environments/environment.prod.ts.template +1 -0
- package/src/ng-add/files/src/environments/environment.test.ts.template +1 -0
- package/src/ng-add/files/src/environments/environment.ts.template +1 -1
- 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/tsconfig.json +2 -2
- 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 -494
- package/src/ng-add/files/src/app/core/firebase/database.service.ts.template +0 -56
- package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +0 -366
- package/src/ng-add/files/src/app/core/firebase/firebase.service.ts.template +0 -342
- 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 -1317
- 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
|
@@ -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`
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# Authentication architecture
|
|
2
|
+
|
|
3
|
+
This document is the implementation reference for application authentication. It describes the production system as implemented in the Angular application, Firebase configuration, Firestore rules, and Cloud Functions.
|
|
4
|
+
|
|
5
|
+
## Goals and boundaries
|
|
6
|
+
|
|
7
|
+
The application supports three sign-in paths:
|
|
8
|
+
|
|
9
|
+
| Path | Firebase provider | Intended use |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| Google | `google.com` | One-click sign-in or upgrading a guest account with a Google identity. |
|
|
12
|
+
| Email magic link | Firebase Email/Password provider with email-link credentials | Passwordless sign-in and upgrading a guest account while preserving progress. |
|
|
13
|
+
| Guest | `anonymous` | Immediate, low-friction access; progress remains recoverable only by linking Google or an email address. |
|
|
14
|
+
|
|
15
|
+
The application does not provide password creation, password sign-in, or password reset screens. Firebase’s Email/Password provider remains enabled only because Firebase implements email-link sign-in through that provider.
|
|
16
|
+
|
|
17
|
+
Authentication establishes identity. The Firestore `users/{uid}` document establishes application state such as onboarding progress, consent, and administrator status. Both are required for access to private application routes.
|
|
18
|
+
|
|
19
|
+
## Firebase Console configuration
|
|
20
|
+
|
|
21
|
+
Configure every Firebase project independently (development and production):
|
|
22
|
+
|
|
23
|
+
1. Enable **Google**, **Email link (passwordless sign-in)**, and **Anonymous** under **Authentication → Sign-in method**. Keep the Email/Password provider enabled as required by Firebase for email links.
|
|
24
|
+
2. Keep **Email enumeration protection** enabled.
|
|
25
|
+
3. Use Firebase’s one-account-per-email behavior so Google and email-link credentials for the same email resolve to one Firebase user instead of separate accounts.
|
|
26
|
+
4. Add each deployed host to **Authentication → Settings → Authorized domains**. At minimum this includes project hosts such as `<project-dev>.web.app` and `<project>.web.app`; add custom hosts as they are introduced.
|
|
27
|
+
5. Leave the Firebase email template’s action URL at its project default (`https://<project>.firebaseapp.com/__/auth/action`). The app action then returns the browser to `/auth/action` on the originating application host.
|
|
28
|
+
6. Deploy the `deleteAnonymousAccount` callable Cloud Function before enabling guest deletion.
|
|
29
|
+
|
|
30
|
+
The application intentionally does not call `fetchSignInMethodsForEmail`. Provider discovery would weaken enumeration protection and cannot safely resolve account-collision recovery.
|
|
31
|
+
|
|
32
|
+
## Main application components
|
|
33
|
+
|
|
34
|
+
| Responsibility | Implementation |
|
|
35
|
+
| --- | --- |
|
|
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` |
|
|
40
|
+
| Auth and application-user state | `src/app/core/store/auth/auth.store.ts` |
|
|
41
|
+
| Guard-facing auth resolution | `src/app/core/auth/auth.service.ts` |
|
|
42
|
+
| Email-link same-browser context | `EmailLinkContextService` from `@tech4good/platform-auth` |
|
|
43
|
+
| Public entry and guest start | `src/app/first-time/landing/` |
|
|
44
|
+
| Email action and completion views | `src/app/first-time/auth-action/`, `src/app/first-time/email-link/` |
|
|
45
|
+
| Account linking/deletion UI | `src/app/main/account-profile/` |
|
|
46
|
+
| Guest deletion backend | `functions/src/index.ts` |
|
|
47
|
+
|
|
48
|
+
`AppComponent` calls `AuthStore.loadAuth()` once during application startup. That long-lived subscription remains active for the lifetime of the app so the UI can react to sign-in, sign-out, session revocation, and authentication changes from another tab.
|
|
49
|
+
|
|
50
|
+
```mermaid
|
|
51
|
+
flowchart TD
|
|
52
|
+
subgraph UI ["UI & Routing Layer"]
|
|
53
|
+
Views["Views & Components<br/>(Landing, Action, Security)"]
|
|
54
|
+
Guards["Route Guards<br/>(requireAuth, requireAuthAndConsent, etc.)"]
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
subgraph State ["State Management Layer"]
|
|
58
|
+
AuthStore["AuthStore<br/>(afUser session & profile loading)"]
|
|
59
|
+
UserStore["UserStore<br/>(User profile & access state)"]
|
|
60
|
+
AuthService["AuthService<br/>(Guard authentication resolution)"]
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
subgraph Infra ["Services & Infrastructure"]
|
|
64
|
+
FirebaseAuthService["FirebaseAuthService<br/>(Firebase Auth SDK operations)"]
|
|
65
|
+
ContextService["EmailLinkContextService<br/>(Cookie & LocalStorage context)"]
|
|
66
|
+
Firestore[("Firestore DB<br/>users/{uid} & userPrivates/{uid}")]
|
|
67
|
+
Functions["Cloud Functions<br/>(deleteAnonymousAccount)"]
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
Guards -->|"resolves auth"| AuthService
|
|
71
|
+
AuthService -->|"queries state"| AuthStore
|
|
72
|
+
Views -->|"triggers sign-in / linking"| AuthStore
|
|
73
|
+
AuthStore -->|"derives user"| UserStore
|
|
74
|
+
AuthStore -->|"calls SDK methods"| FirebaseAuthService
|
|
75
|
+
AuthStore -->|"provisions profile"| Firestore
|
|
76
|
+
FirebaseAuthService -->|"stores link context"| ContextService
|
|
77
|
+
Views -->|"invokes backend deletion"| Functions
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Session model and local state
|
|
81
|
+
|
|
82
|
+
`FirebaseAuthService.afUser()` exposes Firebase Auth changes as an `AuthSession` containing:
|
|
83
|
+
|
|
84
|
+
- Firebase UID, email, display name, photo URL, anonymous state, and email-verification state;
|
|
85
|
+
- provider IDs (for example `google.com` or `password`);
|
|
86
|
+
- `emailLinkEnabled`, derived from Firebase provider metadata rather than Firestore.
|
|
87
|
+
|
|
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.
|
|
94
|
+
|
|
95
|
+
On an authenticated session, `provisionAndLoadUser()`:
|
|
96
|
+
|
|
97
|
+
1. Calls `ensureUserProfile()` to create missing `users/{uid}` and `userPrivates/{uid}` records, or update available Google profile fields.
|
|
98
|
+
2. Loads the application user into `UserStore`.
|
|
99
|
+
3. Starts a real-time stream for that user record.
|
|
100
|
+
|
|
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.”
|
|
102
|
+
|
|
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.
|
|
104
|
+
|
|
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.
|
|
106
|
+
|
|
107
|
+
## Account creation and profile data
|
|
108
|
+
|
|
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:
|
|
117
|
+
|
|
118
|
+
- `users/{uid}` contains the application identity and onboarding state. New accounts begin at `SUBMIT_INTEREST` and are not administrators or consented.
|
|
119
|
+
- `userPrivates/{uid}` contains the email when Firebase provides one, plus email-link capability metadata.
|
|
120
|
+
|
|
121
|
+
Google provides display name and photo URL. Those values are copied to an existing guest profile when available.
|
|
122
|
+
|
|
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.
|
|
124
|
+
|
|
125
|
+
## Google flow
|
|
126
|
+
|
|
127
|
+
`AuthStore.signInWithGoogle()` calls `FirebaseAuthService.signInWithGoogle()`, which uses `signInWithPopup` and a `GoogleAuthProvider`. The resulting session is provisioned and recorded in `AuthStore`.
|
|
128
|
+
|
|
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.
|
|
130
|
+
|
|
131
|
+
## Email magic-link flows
|
|
132
|
+
|
|
133
|
+
```mermaid
|
|
134
|
+
sequenceDiagram
|
|
135
|
+
autonumber
|
|
136
|
+
actor User
|
|
137
|
+
participant App as Application UI
|
|
138
|
+
participant Context as EmailLinkContextService
|
|
139
|
+
participant FB as Firebase Auth SDK
|
|
140
|
+
participant Mail as User Email Inbox
|
|
141
|
+
participant Store as AuthStore / UserStore
|
|
142
|
+
|
|
143
|
+
User->>App: Request Magic Link
|
|
144
|
+
App->>Context: Store flow context (email, flow type, current UID)
|
|
145
|
+
App->>FB: sendSignInLinkToEmail(email, actionUrl)
|
|
146
|
+
FB->>Mail: Send email with magic link
|
|
147
|
+
Mail->>User: Click magic link
|
|
148
|
+
User->>FB: Open Firebase action URL
|
|
149
|
+
FB->>App: Redirect to /auth/action?mode=signIn -> /email-link
|
|
150
|
+
App->>Context: Retrieve stored context (same-browser verification)
|
|
151
|
+
App->>FB: completeEmailSignInLink() / linkWithCredential()
|
|
152
|
+
FB-->>App: Return authenticated credentials
|
|
153
|
+
App->>Store: provisionAndLoadUser()
|
|
154
|
+
Store-->>App: Load/create profile & establish active session
|
|
155
|
+
App->>User: Route to main application (/home)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Sending
|
|
159
|
+
|
|
160
|
+
`FirebaseAuthService.sendEmailLink()` calls `sendSignInLinkToEmail` with `handleCodeInApp: true` and an action URL based on the active browser origin:
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
https://<current-host>/auth/action?flow=<flow>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Before sending, `EmailLinkContextService` stores three values in both local storage (when available) and a 30-minute, `SameSite=Lax` cookie:
|
|
167
|
+
|
|
168
|
+
- requested email address;
|
|
169
|
+
- requested flow (`sign-in`, `guest-upgrade`, or `link-email`);
|
|
170
|
+
- current UID for flows that must retain the existing account.
|
|
171
|
+
|
|
172
|
+
The context makes the normal same-browser flow automatic and prevents a link intended to upgrade one guest account from being used to attach credentials to a different session. If storage is unavailable, the cookie provides the fallback.
|
|
173
|
+
|
|
174
|
+
The account page replaces its guest “Send Magic Link” button with “Magic link sent” after a successful send. A send failure leaves the button available for retry.
|
|
175
|
+
|
|
176
|
+
### Callback and completion
|
|
177
|
+
|
|
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.
|
|
179
|
+
|
|
180
|
+
`FirebaseAuthService.completeEmailSignInLink()` verifies the URL with `isSignInWithEmailLink` and selects a flow:
|
|
181
|
+
|
|
182
|
+
| Flow | Completion action |
|
|
183
|
+
| --- | --- |
|
|
184
|
+
| `sign-in` | `signInWithEmailLink`, creating or restoring an email-linked Firebase session. |
|
|
185
|
+
| `guest-upgrade` | Requires the original same-browser UID, then calls `linkWithCredential` so guest progress stays on that UID. |
|
|
186
|
+
| `link-email` | Requires the original same-browser UID, then calls `linkWithCredential` to add passwordless email sign-in to an existing account. |
|
|
187
|
+
|
|
188
|
+
After completion, the Firebase token is refreshed, the short-lived email-link context is cleared, and `AuthStore` provisions/refreshes the application profile. The callback view routes to `/home`; route guards then send users to any incomplete early-access or consent step.
|
|
189
|
+
|
|
190
|
+
If the callback is opened on a different device or browser for an upgrade/linking flow, the app does not guess which account should receive the credential. It displays the `auth/link-requires-original-session` guidance instead.
|
|
191
|
+
|
|
192
|
+
## Guest flow and account deletion
|
|
193
|
+
|
|
194
|
+
Choosing guest access calls `AuthStore.loginAnonymously()`, which creates an anonymous Firebase user, provisions the matching application profile, and then navigates through normal route guards.
|
|
195
|
+
|
|
196
|
+
Guests can preserve progress by linking Google or an email magic link. Deleting a guest account is intentionally destructive and requires confirmation.
|
|
197
|
+
|
|
198
|
+
The `deleteAnonymousAccount` callable function:
|
|
199
|
+
|
|
200
|
+
1. Requires an authenticated request whose `sign_in_provider` is `anonymous`.
|
|
201
|
+
2. Deletes guest-owned `userContexts` documents in batches. Extend `QUERY_COLLECTIONS` when the application adds other user-owned collections.
|
|
202
|
+
3. Deletes the UID-keyed `users` and `userPrivates` documents.
|
|
203
|
+
4. Deletes the Firebase Auth user.
|
|
204
|
+
|
|
205
|
+
After the callable succeeds, `AuthStore.deleteAnonymousAccount()` explicitly calls local Firebase `signOut`, patches local auth state to `null`, and routes to `/landing`. The explicit local sign-out matters: deleting a Firebase Auth user on the server does not necessarily clear the browser’s in-memory Firebase session before the landing guard runs. Without it, the guard could wait indefinitely for an application profile that the callable had already deleted.
|
|
206
|
+
|
|
207
|
+
```mermaid
|
|
208
|
+
sequenceDiagram
|
|
209
|
+
autonumber
|
|
210
|
+
actor Guest as Guest User
|
|
211
|
+
participant App as Application UI / AuthStore
|
|
212
|
+
participant CF as Cloud Function (deleteAnonymousAccount)
|
|
213
|
+
participant FS as Firestore DB
|
|
214
|
+
participant FB as Firebase Auth
|
|
215
|
+
|
|
216
|
+
Guest->>App: Request Guest Account Deletion
|
|
217
|
+
App->>App: Wait for profile provisioning
|
|
218
|
+
App->>App: clearSessionState() (Stop listeners, clear auth-related state)
|
|
219
|
+
App->>CF: Call deleteAnonymousAccount()
|
|
220
|
+
CF->>FS: Delete user-owned data (userContexts by default)
|
|
221
|
+
CF->>FS: Delete users and userPrivates docs
|
|
222
|
+
CF->>FB: Delete anonymous Firebase Auth user
|
|
223
|
+
CF-->>App: Callable returns success
|
|
224
|
+
App->>FB: Local signOut() & patch auth state to null
|
|
225
|
+
App->>Guest: Route to /landing
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## Logout and listener teardown
|
|
229
|
+
|
|
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.
|
|
234
|
+
|
|
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.
|
|
240
|
+
|
|
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.
|
|
242
|
+
|
|
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.
|
|
248
|
+
|
|
249
|
+
## Routing and authorization
|
|
250
|
+
|
|
251
|
+
Routes in `src/app/app.routes.ts` use four layers of guard behavior:
|
|
252
|
+
|
|
253
|
+
| Guard | Purpose |
|
|
254
|
+
| --- | --- |
|
|
255
|
+
| `redirectIfAuthenticated` | Keeps authenticated users off public landing/login routes; redirects them to home. |
|
|
256
|
+
| `requireAuth` | Requires a resolved application user; otherwise redirects to landing. |
|
|
257
|
+
| `earlyAccessGuard` | Keeps users in the interest/waitlist stage until their access state advances. |
|
|
258
|
+
| `requireAuthAndConsent` | Requires authentication, completion of early access, and consent before home/onboarding routes. |
|
|
259
|
+
|
|
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.
|
|
266
|
+
|
|
267
|
+
## Firestore authorization relationship
|
|
268
|
+
|
|
269
|
+
Firestore rules are in `firestore.rules`. The main principle is that authentication alone is not enough for every action:
|
|
270
|
+
|
|
271
|
+
- Anonymous users, Google users, and verified-email users are permitted where `isVerifiedOrAnonymous()` applies.
|
|
272
|
+
- Users can create and update their own user and private records, subject to application-state restrictions; they cannot grant themselves administrator access or bypass protected onboarding transitions.
|
|
273
|
+
- User-owned `userContexts` documents are restricted to their owning UID, with administrator exceptions.
|
|
274
|
+
- Applications must add equivalent owner checks for every additional user-owned collection they introduce.
|
|
275
|
+
|
|
276
|
+
The callable guest-deletion function uses the Admin SDK and therefore performs controlled server-side deletion rather than relying on the client to clean up every collection.
|
|
277
|
+
|
|
278
|
+
## Operational checklist
|
|
279
|
+
|
|
280
|
+
When changing authentication behavior, verify:
|
|
281
|
+
|
|
282
|
+
1. The Firebase Console providers and authorized domains are configured in both environments.
|
|
283
|
+
2. Email links return to `/auth/action` on the correct host and work in the same browser that initiated account linking.
|
|
284
|
+
3. Guest login creates one profile and does not emit Firestore permission errors after a previous guest deletion.
|
|
285
|
+
4. Guest deletion removes data, signs out locally, and lands on `/landing`.
|
|
286
|
+
5. Google and email-link upgrades preserve the existing UID and its progress.
|
|
287
|
+
6. Firestore listeners are torn down before sign-out, while the top-level auth observer remains active.
|
|
288
|
+
7. Route guards redirect unauthenticated users to landing and incomplete users to the appropriate onboarding stage.
|
|
289
|
+
8. `npm run lint`, `npm run build`, `npm run test`, and `npm run test:rules` pass before deployment.
|
|
290
|
+
|
|
291
|
+
## Related implementation references
|
|
292
|
+
|
|
293
|
+
- `src/app/core/store/auth/auth.store.ts`
|
|
294
|
+
- `@tech4good/platform-auth/firebase`
|
|
295
|
+
- `@tech4good/platform-auth` and `src/app/core/auth/auth.providers.ts`
|
|
296
|
+
- `src/app/core/auth/auth.service.ts`
|
|
297
|
+
- `src/app/core/auth/guards/`
|
|
298
|
+
- `src/app/main/account-profile/`
|
|
299
|
+
- `functions/src/index.ts`
|
|
300
|
+
- `firestore.rules`
|
|
@@ -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.
|