@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.
Files changed (229) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +266 -1
  3. package/package.json +34 -7
  4. package/src/component/files/__name@dasherize__/__name@dasherize__.component.spec.ts.template +4 -5
  5. package/src/component/files/__name@dasherize__/__name@dasherize__.component.ts.template +1 -1
  6. package/src/entity/files/__name@dasherize__/__name@dasherize__.mock.ts.template +14 -6
  7. package/src/entity/files/__name@dasherize__/__name@dasherize__.model.ts.template +12 -6
  8. package/src/entity/files/__name@dasherize__/__name@dasherize__.store.ts.template +18 -10
  9. package/src/entity/index.js +4 -49
  10. package/src/entity/index.js.map +1 -1
  11. package/src/guard/files/__name@dasherize__.guard.spec.ts.template +0 -1
  12. package/src/ng-add/files/.github/workflows/angular-github-ci.yml.template +3 -0
  13. package/src/ng-add/files/.gitignore.template +3 -0
  14. package/src/ng-add/files/analytics/datasets.js.template +206 -0
  15. package/src/ng-add/files/analytics/entity_sources.js.template +58 -0
  16. package/src/ng-add/files/analytics/entity_sources.test.js.template +57 -0
  17. package/src/ng-add/files/analytics/lib/api_query.js.template +87 -0
  18. package/src/ng-add/files/analytics/lib/api_query.test.js.template +84 -0
  19. package/src/ng-add/files/analytics/lib/bigquery_query_compatibility.test.js.template +53 -0
  20. package/src/ng-add/files/analytics/lib/dataset_schema.js.template +53 -0
  21. package/src/ng-add/files/analytics/lib/dataset_schema.test.js.template +34 -0
  22. package/src/ng-add/files/analytics/lib/entity_sync.js.template +397 -0
  23. package/src/ng-add/files/analytics/lib/entity_sync.test.js.template +212 -0
  24. package/src/ng-add/files/analytics/lib/identifier_salt.js.template +57 -0
  25. package/src/ng-add/files/analytics/lib/identifier_salt.test.js.template +36 -0
  26. package/src/ng-add/files/analytics/lib/snapshot_files.js.template +46 -0
  27. package/src/ng-add/files/analytics/lib/snapshot_files.test.js.template +67 -0
  28. package/src/ng-add/files/analytics/lib/sqlite.js.template +92 -0
  29. package/src/ng-add/files/analytics/lib/upload_entities.js.template +81 -0
  30. package/src/ng-add/files/analytics/lib/upload_entities.test.js.template +86 -0
  31. package/src/ng-add/files/analytics/proxy.conf.json.template +7 -0
  32. package/src/ng-add/files/analytics/scripts/refresh_snapshot.js.template +518 -0
  33. package/src/ng-add/files/analytics/scripts/start.js.template +88 -0
  34. package/src/ng-add/files/analytics/server/server.js.template +212 -0
  35. package/src/ng-add/files/angular.json.template +80 -1
  36. package/src/ng-add/files/bigquery/queries/active_time_by_route.sql.template +27 -8
  37. package/src/ng-add/files/bigquery/queries/active_user_windows.sql.template +67 -0
  38. package/src/ng-add/files/bigquery/queries/dashboard_route_visits.sql.template +47 -0
  39. package/src/ng-add/files/bigquery/queries/data_quality.sql.template +323 -0
  40. package/src/ng-add/files/bigquery/queries/onboarding_funnel.sql.template +512 -0
  41. package/src/ng-add/files/bigquery/queries/onboarding_stage_observations.sql.template +134 -0
  42. package/src/ng-add/files/bigquery/queries/weekly_retention_cohorts.sql.template +90 -0
  43. package/src/ng-add/files/bigquery/scripts/export_entities.js.template +120 -0
  44. package/src/ng-add/files/bigquery/scripts/init_views.js.template +57 -0
  45. package/src/ng-add/files/bigquery/scripts/run_query.js.template +141 -0
  46. package/src/ng-add/files/bigquery/views/events_flat.sql.template +27 -12
  47. package/src/ng-add/files/bigquery/views/logs_latest.sql.template +16 -3
  48. package/src/ng-add/files/docs-infra/analytics-guide.md.template +270 -25
  49. package/src/ng-add/files/docs-infra/analytics-workbench-guide.md.template +307 -0
  50. package/src/ng-add/files/docs-infra/authentication-architecture.md.template +54 -24
  51. package/src/ng-add/files/docs-infra/email-infrastructure.md.template +43 -0
  52. package/src/ng-add/files/docs-infra/firestore-index-checker.md.template +87 -0
  53. package/src/ng-add/files/docs-infra/infrastructure-guide.md.template +108 -29
  54. package/src/ng-add/files/docs-infra/load-system-architecture.md.template +15 -1
  55. package/src/ng-add/files/docs-infra/querying-strategy.md.template +14 -0
  56. package/src/ng-add/files/docs-infra/stream-system-architecture.md.template +21 -7
  57. package/src/ng-add/files/eslint.config.js.template +22 -3
  58. package/src/ng-add/files/functions/package.json.template +1 -0
  59. package/src/ng-add/files/functions/src/email.ts.template +23 -0
  60. package/src/ng-add/files/jest.config.ts.template +3 -2
  61. package/src/ng-add/files/package.json.template +39 -16
  62. package/src/ng-add/files/projects/analytics/src/app/analytics-api.service.ts.template +130 -0
  63. package/src/ng-add/files/projects/analytics/src/app/app.component.html.template +77 -0
  64. package/src/ng-add/files/projects/analytics/src/app/app.component.scss.template +240 -0
  65. package/src/ng-add/files/projects/analytics/src/app/app.component.ts.template +96 -0
  66. package/src/ng-add/files/projects/analytics/src/app/app.routes.ts.template +11 -0
  67. package/src/ng-add/files/projects/analytics/src/app/dashboard-pages.spec.ts.template +151 -0
  68. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.html.template +39 -0
  69. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.scss.template +1 -0
  70. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.ts.template +95 -0
  71. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.html.template +47 -0
  72. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.scss.template +1 -0
  73. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.ts.template +120 -0
  74. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.html.template +40 -0
  75. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.scss.template +1 -0
  76. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.ts.template +98 -0
  77. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.html.template +35 -0
  78. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.scss.template +1 -0
  79. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.ts.template +84 -0
  80. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.html.template +42 -0
  81. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.scss.template +1 -0
  82. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.ts.template +110 -0
  83. package/src/ng-add/files/projects/analytics/src/app/shared/analytics-utils.ts.template +43 -0
  84. package/src/ng-add/files/projects/analytics/src/app/shared/chart-theme.ts.template +42 -0
  85. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-layout.scss.template +239 -0
  86. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.html.template +76 -0
  87. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.scss.template +128 -0
  88. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.spec.ts.template +31 -0
  89. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.ts.template +153 -0
  90. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.html.template +16 -0
  91. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.scss.template +63 -0
  92. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.ts.template +52 -0
  93. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.html.template +5 -0
  94. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.scss.template +56 -0
  95. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.spec.ts.template +30 -0
  96. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.ts.template +15 -0
  97. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.html.template +9 -0
  98. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.scss.template +43 -0
  99. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.ts.template +62 -0
  100. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.html.template +9 -0
  101. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.scss.template +33 -0
  102. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.ts.template +82 -0
  103. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.html.template +15 -0
  104. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.scss.template +45 -0
  105. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.ts.template +55 -0
  106. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.html.template +18 -0
  107. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.scss.template +45 -0
  108. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.ts.template +15 -0
  109. package/src/ng-add/files/projects/analytics/src/app/vega-chart/vega-chart.component.ts.template +121 -0
  110. package/src/ng-add/files/projects/analytics/src/index.html.template +19 -0
  111. package/src/ng-add/files/projects/analytics/src/main.ts.template +16 -0
  112. package/src/ng-add/files/projects/analytics/src/styles.scss.template +28 -0
  113. package/src/ng-add/files/projects/analytics/tsconfig.app.json.template +13 -0
  114. package/src/ng-add/files/projects/analytics/tsconfig.spec.json.template +15 -0
  115. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.spec.ts.template +4 -5
  116. package/src/ng-add/files/src/app/admin/admin-panel/admin-settings/admin-settings.component.spec.ts.template +4 -5
  117. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.spec.ts.template +11 -12
  118. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.ts.template +7 -7
  119. 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
  120. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.ts.template +3 -2
  121. package/src/ng-add/files/src/app/app.component.html.template +1 -1
  122. package/src/ng-add/files/src/app/app.component.scss.template +1 -1
  123. package/src/ng-add/files/src/app/app.component.spec.ts.template +4 -5
  124. package/src/ng-add/files/src/app/app.component.ts.template +1 -2
  125. package/src/ng-add/files/src/app/app.config.ts.template +21 -15
  126. package/src/ng-add/files/src/app/auth-routing.spec.ts.template +4 -5
  127. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.spec.ts.template +46 -29
  128. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.ts.template +27 -18
  129. package/src/ng-add/files/src/app/core/auth/auth.providers.spec.ts.template +112 -0
  130. package/src/ng-add/files/src/app/core/auth/auth.providers.ts.template +48 -0
  131. package/src/ng-add/files/src/app/core/auth/auth.service.ts.template +9 -23
  132. package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.spec.ts.template +3 -14
  133. package/src/ng-add/files/src/app/core/firebase/data.providers.prod.ts.template +21 -0
  134. package/src/ng-add/files/src/app/core/firebase/data.providers.ts.template +13 -0
  135. package/src/ng-add/files/src/app/core/local-storage/session.service.spec.ts.template +43 -0
  136. package/src/ng-add/files/src/app/core/local-storage/session.service.ts.template +7 -0
  137. package/src/ng-add/files/src/app/core/store/app-data.spec.ts.template +76 -0
  138. package/src/ng-add/files/src/app/core/store/auth/auth.mock.ts.template +19 -67
  139. package/src/ng-add/files/src/app/core/store/auth/auth.store.spec.ts.template +102 -12
  140. package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +32 -237
  141. package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +17 -12
  142. package/src/ng-add/files/src/app/core/store/user/user.model.ts.template +6 -7
  143. package/src/ng-add/files/src/app/core/store/user/user.store.ts.template +14 -10
  144. package/src/ng-add/files/src/app/core/store/user-context/user-context.mock.ts.template +20 -8
  145. package/src/ng-add/files/src/app/core/store/user-context/user-context.model.ts.template +5 -6
  146. package/src/ng-add/files/src/app/core/store/user-context/user-context.store.ts.template +14 -10
  147. package/src/ng-add/files/src/app/core/store/user-private/user-private.mock.ts.template +20 -7
  148. package/src/ng-add/files/src/app/core/store/user-private/user-private.model.ts.template +5 -6
  149. package/src/ng-add/files/src/app/core/store/user-private/user-private.store.ts.template +14 -10
  150. package/src/ng-add/files/src/app/core/testing/app-mocks.ts.template +42 -0
  151. package/src/ng-add/files/src/app/first-time/consent/consent.component.html.template +2 -1
  152. package/src/ng-add/files/src/app/first-time/consent/consent.component.scss.template +7 -3
  153. package/src/ng-add/files/src/app/first-time/consent/consent.component.spec.ts.template +31 -11
  154. package/src/ng-add/files/src/app/first-time/consent/consent.component.ts.template +16 -1
  155. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +15 -15
  156. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +11 -3
  157. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.html.template +2 -1
  158. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.scss.template +7 -3
  159. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.spec.ts.template +20 -6
  160. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.ts.template +2 -0
  161. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.spec.ts.template +4 -5
  162. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.spec.ts.template +17 -1
  163. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.ts.template +15 -0
  164. package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +4 -5
  165. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +15 -0
  166. package/src/ng-add/files/src/app/first-time/landing/landing.component.spec.ts.template +2 -0
  167. package/src/ng-add/files/src/app/first-time/login/login.component.spec.ts.template +21 -3
  168. package/src/ng-add/files/src/app/first-time/login/login.component.ts.template +26 -0
  169. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.spec.ts.template +4 -2
  170. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.ts.template +1 -1
  171. package/src/ng-add/files/src/app/main/account-profile/account-profile.component.spec.ts.template +2 -2
  172. package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.spec.ts.template +2 -2
  173. package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.spec.ts.template +4 -4
  174. package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.spec.ts.template +2 -2
  175. package/src/ng-add/files/src/app/main/home/home.component.spec.ts.template +4 -5
  176. package/src/ng-add/files/src/app/main/home/home.component.ts.template +1 -1
  177. package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.spec.ts.template +4 -4
  178. package/src/ng-add/files/src/app/shared/navbar/navbar.component.spec.ts.template +2 -2
  179. package/src/ng-add/files/tsconfig.spec.json.template +3 -1
  180. package/src/ng-add/index.js +7 -0
  181. package/src/ng-add/index.js.map +1 -1
  182. package/src/shared/entity-registry.d.ts +8 -0
  183. package/src/shared/entity-registry.js +28 -0
  184. package/src/shared/entity-registry.js.map +1 -0
  185. package/.agents/skills/publish-npm/SKILL.md +0 -37
  186. package/.agents/skills/publish-npm/eval.yaml +0 -32
  187. package/.agents/skills/publish-npm/fixtures/package-v21.json.template +0 -8
  188. package/.husky/commit-msg +0 -1
  189. package/.husky/pre-commit +0 -1
  190. package/.t4g/agent-memory.db +0 -0
  191. package/src/component/index_spec.d.ts +0 -1
  192. package/src/component/index_spec.js +0 -68
  193. package/src/component/index_spec.js.map +0 -1
  194. package/src/entity/index_spec.d.ts +0 -1
  195. package/src/entity/index_spec.js +0 -153
  196. package/src/entity/index_spec.js.map +0 -1
  197. package/src/guard/index_spec.d.ts +0 -1
  198. package/src/guard/index_spec.js +0 -64
  199. package/src/guard/index_spec.js.map +0 -1
  200. package/src/ng-add/files/bigquery/scripts/export_entities.py.template +0 -143
  201. package/src/ng-add/files/bigquery/scripts/run_query.py.template +0 -167
  202. package/src/ng-add/files/src/app/core/firebase/cached-listeners.service.ts.template +0 -500
  203. package/src/ng-add/files/src/app/core/firebase/database.service.ts.template +0 -73
  204. package/src/ng-add/files/src/app/core/firebase/email-link-context.service.spec.ts.template +0 -59
  205. package/src/ng-add/files/src/app/core/firebase/email-link-context.service.ts.template +0 -147
  206. package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +0 -453
  207. package/src/ng-add/files/src/app/core/firebase/firebase.service.spec.ts.template +0 -116
  208. package/src/ng-add/files/src/app/core/firebase/firebase.service.ts.template +0 -639
  209. package/src/ng-add/files/src/app/core/firebase/simulate-load.spec.ts.template +0 -104
  210. package/src/ng-add/files/src/app/core/firebase/simulate-stream.spec.ts.template +0 -127
  211. package/src/ng-add/files/src/app/core/firebase/simulation.mock.ts.template +0 -38
  212. package/src/ng-add/files/src/app/core/firebase/stream-multiplexer.ts.template +0 -445
  213. package/src/ng-add/files/src/app/core/logging/logging.service.spec.ts.template +0 -118
  214. package/src/ng-add/files/src/app/core/logging/logging.service.ts.template +0 -168
  215. package/src/ng-add/files/src/app/core/store/app.model.ts.template +0 -21
  216. package/src/ng-add/files/src/app/core/store/app.store.spec.ts.template +0 -920
  217. package/src/ng-add/files/src/app/core/store/app.store.ts.template +0 -1320
  218. package/src/ng-add/files/src/app/core/store/batch-write.firebase.service.ts.template +0 -58
  219. package/src/ng-add/files/src/app/core/store/batch-write.mock.service.ts.template +0 -105
  220. package/src/ng-add/files/src/app/core/store/batch-write.service.ts.template +0 -126
  221. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.html.template +0 -9
  222. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.scss.template +0 -46
  223. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.spec.ts.template +0 -69
  224. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.ts.template +0 -39
  225. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.spec.ts.template +0 -122
  226. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.ts.template +0 -88
  227. package/src/ng-add/index_spec.d.ts +0 -1
  228. package/src/ng-add/index_spec.js +0 -108
  229. 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 | `src/app/core/firebase/firebase.service.ts` |
37
- | Small Firebase abstraction used by stores and tests | `src/app/core/firebase/database.service.ts` |
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 | `src/app/core/firebase/email-link-context.service.ts` |
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
- FirebaseService["FirebaseService<br/>(Firebase Auth SDK operations)"]
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"| FirebaseService
74
+ AuthStore -->|"calls SDK methods"| FirebaseAuthService
73
75
  AuthStore -->|"provisions profile"| Firestore
74
- FirebaseService -->|"stores link context"| ContextService
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
- `FirebaseService.afUser()` exposes Firebase Auth changes as an `AuthSession` containing:
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` maintains the Firebase session in `afUser` and derives `user` by looking up the matching entity in `UserStore`. A Firebase session can therefore exist briefly before the application profile has loaded; guards use `AuthService.resolveUser()` to handle that distinction.
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 `isLoadingLogin` is true. 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.”
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 resets stores while retaining the app-wide Firebase auth observer for the next sign-in or an external auth change.
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()` creates a new application profile when the Firebase UID has no matching document:
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 therefore 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. It does not manufacture a name or avatar from an email address.
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 `FirebaseService.signInWithGoogle()`, which uses `signInWithPopup` and a `GoogleAuthProvider`. The resulting session is provisioned and recorded in `AuthStore`.
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
- `FirebaseService.sendEmailLink()` calls `sendSignInLinkToEmail` with `handleCodeInApp: true` and an action URL based on the active browser origin:
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
- `FirebaseService.completeEmailSignInLink()` verifies the URL with `isSignInWithEmailLink` and selects a flow:
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 any logout or guest deletion, `AuthStore.resetAllStores()`:
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
- 1. Tears down cached Firestore streams.
218
- 2. Resets `UserStore` and `UserContextStore`.
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 future sign-ins, cross-tab changes, and session invalidation. Direct sign-in methods use `isLoadingLogin` to ensure that this observer mirrors the new session without racing the credential-ready provisioning operation.
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()` first observes Firebase Auth. If there is no Firebase session, it immediately resolves `null`; if there is a session, it returns the synchronous store user when already available or waits for the first loaded application user. This avoids guards making decisions from an incomplete Firestore load while preserving immediate redirects for logged-out users.
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
- - `src/app/core/firebase/firebase.service.ts`
265
- - `src/app/core/firebase/email-link-context.service.ts`
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.