@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.
Files changed (273) hide show
  1. package/CHANGELOG.md +44 -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 +16 -7
  7. package/src/entity/files/__name@dasherize__/__name@dasherize__.model.ts.template +13 -6
  8. package/src/entity/files/__name@dasherize__/__name@dasherize__.store.ts.template +18 -10
  9. package/src/entity/index.js +61 -49
  10. package/src/entity/index.js.map +1 -1
  11. package/src/entity/schema.json +4 -0
  12. package/src/guard/files/__name@dasherize__.guard.spec.ts.template +0 -1
  13. package/src/ng-add/files/.github/workflows/angular-github-ci.yml.template +3 -0
  14. package/src/ng-add/files/.gitignore.template +5 -0
  15. package/src/ng-add/files/analytics/datasets.js.template +206 -0
  16. package/src/ng-add/files/analytics/entity_sources.js.template +58 -0
  17. package/src/ng-add/files/analytics/entity_sources.test.js.template +57 -0
  18. package/src/ng-add/files/analytics/lib/api_query.js.template +87 -0
  19. package/src/ng-add/files/analytics/lib/api_query.test.js.template +84 -0
  20. package/src/ng-add/files/analytics/lib/bigquery_query_compatibility.test.js.template +53 -0
  21. package/src/ng-add/files/analytics/lib/dataset_schema.js.template +53 -0
  22. package/src/ng-add/files/analytics/lib/dataset_schema.test.js.template +34 -0
  23. package/src/ng-add/files/analytics/lib/entity_sync.js.template +397 -0
  24. package/src/ng-add/files/analytics/lib/entity_sync.test.js.template +212 -0
  25. package/src/ng-add/files/analytics/lib/identifier_salt.js.template +57 -0
  26. package/src/ng-add/files/analytics/lib/identifier_salt.test.js.template +36 -0
  27. package/src/ng-add/files/analytics/lib/snapshot_files.js.template +46 -0
  28. package/src/ng-add/files/analytics/lib/snapshot_files.test.js.template +67 -0
  29. package/src/ng-add/files/analytics/lib/sqlite.js.template +92 -0
  30. package/src/ng-add/files/analytics/lib/upload_entities.js.template +81 -0
  31. package/src/ng-add/files/analytics/lib/upload_entities.test.js.template +86 -0
  32. package/src/ng-add/files/analytics/proxy.conf.json.template +7 -0
  33. package/src/ng-add/files/analytics/scripts/refresh_snapshot.js.template +518 -0
  34. package/src/ng-add/files/analytics/scripts/start.js.template +88 -0
  35. package/src/ng-add/files/analytics/server/server.js.template +212 -0
  36. package/src/ng-add/files/angular.json.template +80 -1
  37. package/src/ng-add/files/bigquery/queries/active_time_by_route.sql.template +27 -8
  38. package/src/ng-add/files/bigquery/queries/active_user_windows.sql.template +67 -0
  39. package/src/ng-add/files/bigquery/queries/dashboard_route_visits.sql.template +47 -0
  40. package/src/ng-add/files/bigquery/queries/data_quality.sql.template +323 -0
  41. package/src/ng-add/files/bigquery/queries/onboarding_funnel.sql.template +512 -0
  42. package/src/ng-add/files/bigquery/queries/onboarding_stage_observations.sql.template +134 -0
  43. package/src/ng-add/files/bigquery/queries/weekly_retention_cohorts.sql.template +90 -0
  44. package/src/ng-add/files/bigquery/scripts/export_entities.js.template +120 -0
  45. package/src/ng-add/files/bigquery/scripts/init_views.js.template +57 -0
  46. package/src/ng-add/files/bigquery/scripts/run_query.js.template +141 -0
  47. package/src/ng-add/files/bigquery/views/events_flat.sql.template +27 -12
  48. package/src/ng-add/files/bigquery/views/logs_latest.sql.template +16 -3
  49. package/src/ng-add/files/docs-infra/analytics-guide.md.template +270 -25
  50. package/src/ng-add/files/docs-infra/analytics-workbench-guide.md.template +307 -0
  51. package/src/ng-add/files/docs-infra/authentication-architecture.md.template +300 -0
  52. package/src/ng-add/files/docs-infra/email-infrastructure.md.template +43 -0
  53. package/src/ng-add/files/docs-infra/firestore-index-checker.md.template +87 -0
  54. package/src/ng-add/files/docs-infra/infrastructure-guide.md.template +123 -38
  55. package/src/ng-add/files/docs-infra/load-system-architecture.md.template +15 -1
  56. package/src/ng-add/files/docs-infra/querying-strategy.md.template +14 -0
  57. package/src/ng-add/files/docs-infra/stream-system-architecture.md.template +21 -7
  58. package/src/ng-add/files/eslint.config.js.template +22 -3
  59. package/src/ng-add/files/firebase.json.template +6 -0
  60. package/src/ng-add/files/firestore.indexes.json.template +23 -0
  61. package/src/ng-add/files/firestore.rules.spec.ts.template +84 -15
  62. package/src/ng-add/files/firestore.rules.template +29 -17
  63. package/src/ng-add/files/functions/.gitignore.template +3 -0
  64. package/src/ng-add/files/functions/package.json.template +13 -0
  65. package/src/ng-add/files/functions/src/email.ts.template +23 -0
  66. package/src/ng-add/files/functions/src/index.ts.template +44 -0
  67. package/src/ng-add/files/functions/tsconfig.json.template +13 -0
  68. package/src/ng-add/files/jest.config.ts.template +3 -2
  69. package/src/ng-add/files/package.json.template +41 -16
  70. package/src/ng-add/files/projects/analytics/src/app/analytics-api.service.ts.template +130 -0
  71. package/src/ng-add/files/projects/analytics/src/app/app.component.html.template +77 -0
  72. package/src/ng-add/files/projects/analytics/src/app/app.component.scss.template +240 -0
  73. package/src/ng-add/files/projects/analytics/src/app/app.component.ts.template +96 -0
  74. package/src/ng-add/files/projects/analytics/src/app/app.routes.ts.template +11 -0
  75. package/src/ng-add/files/projects/analytics/src/app/dashboard-pages.spec.ts.template +151 -0
  76. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.html.template +39 -0
  77. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.scss.template +1 -0
  78. package/src/ng-add/files/projects/analytics/src/app/data-quality/data-quality-page/data-quality-page.component.ts.template +95 -0
  79. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.html.template +47 -0
  80. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.scss.template +1 -0
  81. package/src/ng-add/files/projects/analytics/src/app/engagement/engagement-page/engagement-page.component.ts.template +120 -0
  82. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.html.template +40 -0
  83. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.scss.template +1 -0
  84. package/src/ng-add/files/projects/analytics/src/app/onboarding/onboarding-page/onboarding-page.component.ts.template +98 -0
  85. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.html.template +35 -0
  86. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.scss.template +1 -0
  87. package/src/ng-add/files/projects/analytics/src/app/overview/overview-page/overview-page.component.ts.template +84 -0
  88. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.html.template +42 -0
  89. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.scss.template +1 -0
  90. package/src/ng-add/files/projects/analytics/src/app/routes/routes-page/routes-page.component.ts.template +110 -0
  91. package/src/ng-add/files/projects/analytics/src/app/shared/analytics-utils.ts.template +43 -0
  92. package/src/ng-add/files/projects/analytics/src/app/shared/chart-theme.ts.template +42 -0
  93. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-layout.scss.template +239 -0
  94. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.html.template +76 -0
  95. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.scss.template +128 -0
  96. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.spec.ts.template +31 -0
  97. package/src/ng-add/files/projects/analytics/src/app/shared/dashboard-table/dashboard-table.component.ts.template +153 -0
  98. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.html.template +16 -0
  99. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.scss.template +63 -0
  100. package/src/ng-add/files/projects/analytics/src/app/shared/funnel-chart/funnel-chart.component.ts.template +52 -0
  101. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.html.template +5 -0
  102. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.scss.template +56 -0
  103. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.spec.ts.template +30 -0
  104. package/src/ng-add/files/projects/analytics/src/app/shared/metric-card/metric-card.component.ts.template +15 -0
  105. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.html.template +9 -0
  106. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.scss.template +43 -0
  107. package/src/ng-add/files/projects/analytics/src/app/shared/quality-chart/quality-chart.component.ts.template +62 -0
  108. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.html.template +9 -0
  109. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.scss.template +33 -0
  110. package/src/ng-add/files/projects/analytics/src/app/shared/route-distribution-chart/route-distribution-chart.component.ts.template +82 -0
  111. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.html.template +15 -0
  112. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.scss.template +45 -0
  113. package/src/ng-add/files/projects/analytics/src/app/shared/route-traffic-chart/route-traffic-chart.component.ts.template +55 -0
  114. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.html.template +18 -0
  115. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.scss.template +45 -0
  116. package/src/ng-add/files/projects/analytics/src/app/shared/status-message/status-message.component.ts.template +15 -0
  117. package/src/ng-add/files/projects/analytics/src/app/vega-chart/vega-chart.component.ts.template +121 -0
  118. package/src/ng-add/files/projects/analytics/src/index.html.template +19 -0
  119. package/src/ng-add/files/projects/analytics/src/main.ts.template +16 -0
  120. package/src/ng-add/files/projects/analytics/src/styles.scss.template +28 -0
  121. package/src/ng-add/files/projects/analytics/tsconfig.app.json.template +13 -0
  122. package/src/ng-add/files/projects/analytics/tsconfig.spec.json.template +15 -0
  123. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.html.template +3 -1
  124. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.spec.ts.template +10 -13
  125. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.ts.template +2 -0
  126. package/src/ng-add/files/src/app/admin/admin-panel/admin-settings/admin-settings.component.spec.ts.template +4 -5
  127. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.spec.ts.template +11 -12
  128. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.ts.template +7 -7
  129. 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
  130. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.ts.template +3 -2
  131. package/src/ng-add/files/src/app/app.component.html.template +3 -3
  132. package/src/ng-add/files/src/app/app.component.scss.template +1 -1
  133. package/src/ng-add/files/src/app/app.component.spec.ts.template +4 -5
  134. package/src/ng-add/files/src/app/app.component.ts.template +3 -2
  135. package/src/ng-add/files/src/app/app.config.ts.template +21 -15
  136. package/src/ng-add/files/src/app/app.routes.ts.template +6 -0
  137. package/src/ng-add/files/src/app/auth-routing.spec.ts.template +13 -9
  138. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.spec.ts.template +46 -29
  139. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.ts.template +27 -18
  140. package/src/ng-add/files/src/app/core/auth/auth.providers.spec.ts.template +112 -0
  141. package/src/ng-add/files/src/app/core/auth/auth.providers.ts.template +48 -0
  142. package/src/ng-add/files/src/app/core/auth/auth.service.ts.template +14 -23
  143. package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.spec.ts.template +27 -0
  144. package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.ts.template +3 -2
  145. package/src/ng-add/files/src/app/core/auth/guards/require-auth-and-consent.guard.ts.template +7 -2
  146. package/src/ng-add/files/src/app/core/firebase/data.providers.prod.ts.template +21 -0
  147. package/src/ng-add/files/src/app/core/firebase/data.providers.ts.template +13 -0
  148. package/src/ng-add/files/src/app/core/local-storage/session.service.spec.ts.template +43 -0
  149. package/src/ng-add/files/src/app/core/local-storage/session.service.ts.template +7 -0
  150. package/src/ng-add/files/src/app/core/store/app-data.spec.ts.template +76 -0
  151. package/src/ng-add/files/src/app/core/store/auth/auth.mock.ts.template +20 -82
  152. package/src/ng-add/files/src/app/core/store/auth/auth.store.spec.ts.template +217 -0
  153. package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +36 -172
  154. package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +18 -15
  155. package/src/ng-add/files/src/app/core/store/user/user.model.ts.template +7 -8
  156. package/src/ng-add/files/src/app/core/store/user/user.store.ts.template +14 -10
  157. package/src/ng-add/files/src/app/core/store/user-context/user-context.mock.ts.template +20 -8
  158. package/src/ng-add/files/src/app/core/store/user-context/user-context.model.ts.template +5 -6
  159. package/src/ng-add/files/src/app/core/store/user-context/user-context.store.ts.template +14 -10
  160. package/src/ng-add/files/src/app/core/store/user-private/user-private.mock.ts.template +20 -7
  161. package/src/ng-add/files/src/app/core/store/user-private/user-private.model.ts.template +6 -6
  162. package/src/ng-add/files/src/app/core/store/user-private/user-private.store.ts.template +14 -10
  163. package/src/ng-add/files/src/app/core/testing/app-mocks.ts.template +42 -0
  164. package/src/ng-add/files/src/app/first-time/auth-action/auth-action.component.html.template +4 -0
  165. package/src/ng-add/files/src/app/first-time/auth-action/auth-action.component.scss.template +1 -0
  166. package/src/ng-add/files/src/app/first-time/auth-action/auth-action.component.ts.template +38 -0
  167. package/src/ng-add/files/src/app/first-time/consent/consent.component.html.template +2 -1
  168. package/src/ng-add/files/src/app/first-time/consent/consent.component.scss.template +7 -3
  169. package/src/ng-add/files/src/app/first-time/consent/consent.component.spec.ts.template +31 -11
  170. package/src/ng-add/files/src/app/first-time/consent/consent.component.ts.template +16 -1
  171. package/src/ng-add/files/src/app/first-time/consent/consent.guard.ts.template +5 -1
  172. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +27 -16
  173. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +102 -49
  174. package/src/ng-add/files/src/app/first-time/early-access/early-access.guard.ts.template +5 -1
  175. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.html.template +2 -1
  176. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.scss.template +7 -3
  177. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.spec.ts.template +20 -6
  178. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.ts.template +2 -0
  179. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.spec.ts.template +4 -5
  180. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.html.template +18 -0
  181. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.scss.template +2 -0
  182. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.spec.ts.template +56 -0
  183. package/src/ng-add/files/src/app/first-time/email-link/email-link.component.ts.template +91 -0
  184. package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +11 -7
  185. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.html.template +19 -7
  186. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.scss.template +51 -0
  187. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +44 -5
  188. package/src/ng-add/files/src/app/first-time/landing/landing.component.html.template +2 -1
  189. package/src/ng-add/files/src/app/first-time/landing/landing.component.scss.template +12 -8
  190. package/src/ng-add/files/src/app/first-time/landing/landing.component.spec.ts.template +33 -10
  191. package/src/ng-add/files/src/app/first-time/landing/landing.component.ts.template +6 -19
  192. package/src/ng-add/files/src/app/first-time/login/login.component.html.template +58 -6
  193. package/src/ng-add/files/src/app/first-time/login/login.component.scss.template +151 -22
  194. package/src/ng-add/files/src/app/first-time/login/login.component.spec.ts.template +30 -32
  195. package/src/ng-add/files/src/app/first-time/login/login.component.ts.template +85 -31
  196. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.spec.ts.template +4 -2
  197. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.ts.template +1 -1
  198. package/src/ng-add/files/src/app/main/account-profile/account-profile.component.html.template +12 -0
  199. package/src/ng-add/files/src/app/main/account-profile/account-profile.component.scss.template +39 -0
  200. package/src/ng-add/files/src/app/main/account-profile/account-profile.component.spec.ts.template +68 -0
  201. package/src/ng-add/files/src/app/main/account-profile/account-profile.component.ts.template +20 -0
  202. package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.html.template +24 -0
  203. package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.scss.template +50 -0
  204. package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.spec.ts.template +65 -0
  205. package/src/ng-add/files/src/app/main/account-profile/delete-guest-card/delete-guest-card.component.ts.template +59 -0
  206. package/src/ng-add/files/src/app/main/account-profile/guest-deletion-dialog.component.ts.template +51 -0
  207. package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.html.template +50 -0
  208. package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.scss.template +137 -0
  209. package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.spec.ts.template +57 -0
  210. package/src/ng-add/files/src/app/main/account-profile/profile-details-card/profile-details-card.component.ts.template +59 -0
  211. package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.html.template +133 -0
  212. package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.scss.template +207 -0
  213. package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.spec.ts.template +74 -0
  214. package/src/ng-add/files/src/app/main/account-profile/sign-in-methods-card/sign-in-methods-card.component.ts.template +130 -0
  215. package/src/ng-add/files/src/app/main/home/home.component.spec.ts.template +4 -5
  216. package/src/ng-add/files/src/app/main/home/home.component.ts.template +1 -6
  217. package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.html.template +15 -0
  218. package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.scss.template +79 -0
  219. package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.spec.ts.template +59 -0
  220. package/src/ng-add/files/src/app/shared/guest-warning-bar/guest-warning-bar.component.ts.template +44 -0
  221. package/src/ng-add/files/src/app/shared/navbar/navbar.component.html.template +45 -15
  222. package/src/ng-add/files/src/app/shared/navbar/navbar.component.scss.template +103 -19
  223. package/src/ng-add/files/src/app/shared/navbar/navbar.component.spec.ts.template +73 -9
  224. package/src/ng-add/files/src/app/shared/navbar/navbar.component.ts.template +46 -18
  225. package/src/ng-add/files/src/environments/environment.prod.ts.template +1 -0
  226. package/src/ng-add/files/src/environments/environment.test.ts.template +1 -0
  227. package/src/ng-add/files/src/environments/environment.ts.template +1 -1
  228. package/src/ng-add/files/tsconfig.spec.json.template +3 -1
  229. package/src/ng-add/index.js +7 -0
  230. package/src/ng-add/index.js.map +1 -1
  231. package/src/shared/entity-registry.d.ts +8 -0
  232. package/src/shared/entity-registry.js +28 -0
  233. package/src/shared/entity-registry.js.map +1 -0
  234. package/tsconfig.json +2 -2
  235. package/.agents/skills/publish-npm/SKILL.md +0 -37
  236. package/.agents/skills/publish-npm/eval.yaml +0 -32
  237. package/.agents/skills/publish-npm/fixtures/package-v21.json.template +0 -8
  238. package/.husky/commit-msg +0 -1
  239. package/.husky/pre-commit +0 -1
  240. package/.t4g/agent-memory.db +0 -0
  241. package/src/component/index_spec.d.ts +0 -1
  242. package/src/component/index_spec.js +0 -68
  243. package/src/component/index_spec.js.map +0 -1
  244. package/src/entity/index_spec.d.ts +0 -1
  245. package/src/entity/index_spec.js +0 -153
  246. package/src/entity/index_spec.js.map +0 -1
  247. package/src/guard/index_spec.d.ts +0 -1
  248. package/src/guard/index_spec.js +0 -64
  249. package/src/guard/index_spec.js.map +0 -1
  250. package/src/ng-add/files/bigquery/scripts/export_entities.py.template +0 -143
  251. package/src/ng-add/files/bigquery/scripts/run_query.py.template +0 -167
  252. package/src/ng-add/files/src/app/core/firebase/cached-listeners.service.ts.template +0 -494
  253. package/src/ng-add/files/src/app/core/firebase/database.service.ts.template +0 -56
  254. package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +0 -366
  255. package/src/ng-add/files/src/app/core/firebase/firebase.service.ts.template +0 -342
  256. package/src/ng-add/files/src/app/core/firebase/simulate-load.spec.ts.template +0 -104
  257. package/src/ng-add/files/src/app/core/firebase/simulate-stream.spec.ts.template +0 -127
  258. package/src/ng-add/files/src/app/core/firebase/simulation.mock.ts.template +0 -38
  259. package/src/ng-add/files/src/app/core/firebase/stream-multiplexer.ts.template +0 -445
  260. package/src/ng-add/files/src/app/core/logging/logging.service.spec.ts.template +0 -118
  261. package/src/ng-add/files/src/app/core/logging/logging.service.ts.template +0 -168
  262. package/src/ng-add/files/src/app/core/store/app.model.ts.template +0 -21
  263. package/src/ng-add/files/src/app/core/store/app.store.spec.ts.template +0 -920
  264. package/src/ng-add/files/src/app/core/store/app.store.ts.template +0 -1317
  265. package/src/ng-add/files/src/app/core/store/batch-write.firebase.service.ts.template +0 -58
  266. package/src/ng-add/files/src/app/core/store/batch-write.mock.service.ts.template +0 -105
  267. package/src/ng-add/files/src/app/core/store/batch-write.service.ts.template +0 -126
  268. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.html.template +0 -9
  269. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.scss.template +0 -46
  270. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.spec.ts.template +0 -69
  271. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.ts.template +0 -39
  272. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.spec.ts.template +0 -122
  273. 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.