@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,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.
@@ -1,5 +1,12 @@
1
+ import { DATA_ACCESS } from '@tech4good/platform-data';
1
2
  # Infrastructure Guide
2
3
 
4
+ > Import shared infrastructure directly from `@tech4good/platform-data`,
5
+ > `@tech4good/platform-data/firestore`, or `@tech4good/platform-data/testing`.
6
+ > Local forwarding files are not generated. Improve the engine in the package;
7
+ > keep app entities, domain methods, seeds, auth policies and query choices here.
8
+
9
+
3
10
  This document describes the custom infrastructure patterns in repositories generated using `@techgood/angular-schematics` that differ from standard Angular conventions. Understanding these is essential for contributing code correctly.
4
11
 
5
12
  ---
@@ -15,22 +22,28 @@ All entities share reserved system fields:
15
22
  | Field | Type | Purpose |
16
23
  |-------|------|---------|
17
24
  | `__id` | `string` | Primary key (matches Firestore document ID) |
18
- | `_createdAt` | `Timestamp` | Set automatically on creation |
19
- | `_updatedAt` | `Timestamp` | Set automatically on every write |
25
+ | `_createdAt` | `DataTimestamp` | Set automatically on creation |
26
+ | `_updatedAt` | `DataTimestamp` | Set automatically on every write |
20
27
  | `_deleted` | `boolean` | Soft-delete flag — **entities are never hard-deleted** |
21
28
 
29
+ All four fields are required on stored entities. `_deleted` is used by active
30
+ and soft-delete queries; `_updatedAt` drives incremental loads and nested-stream
31
+ change detection. `_createdAt` records creation time. Use `NewDataEntity<YourEntity>`
32
+ for creation inputs: `store.add()` supplies identity and metadata. Mock seeds and
33
+ records passed to `store.init()` must contain complete stored metadata.
34
+
22
35
  Foreign keys use the `__` prefix (e.g. `__ownerId`, `__communityId`). This is a project convention, not an Angular or Firebase one.
23
36
 
24
37
  **Example** (community.model.ts):
25
38
  ```typescript
26
- export interface Community {
27
- __id: string;
28
- _createdAt?: Timestamp;
29
- _updatedAt?: Timestamp;
30
- _deleted?: boolean;
39
+ import { DataEntity, defineEntity } from '@tech4good/platform-data';
40
+
41
+ export interface Community extends DataEntity {
31
42
  name: string;
32
43
  __ownerId: string;
33
44
  }
45
+
46
+ export const communityEntity = defineEntity<Community>({ collection: 'communitys' });
34
47
  ```
35
48
 
36
49
  ### 1.2 Entity File Set
@@ -39,38 +52,67 @@ Each entity lives in `src/app/core/store/<entity-name>/` and consists of exactly
39
52
 
40
53
  | File | Purpose |
41
54
  |------|---------|
42
- | `<entity>.model.ts` | TypeScript interface |
55
+ | `<entity>.model.ts` | TypeScript interface and exported `defineEntity<T>({ collection })` |
43
56
  | `<entity>.store.ts` | ngrx signal store with `withEntitiesAndDBMethods` |
44
- | `<entity>.mock.ts` | Mock signal store with `withEntitiesForMockDB` + seed data array |
57
+ | `<entity>.mock.ts` | Mock signal store, seeds, and exported `defineEntityMock` wiring |
45
58
 
46
- > [!IMPORTANT]
47
- > **Do NOT create entity files manually.** Use the schematic: `ng generate entity <name>`. This registers the entity in several other files (e.g. `app.model.ts` `AnyEntity` union, `firebase.mock.service.ts` DB map). Missing these registrations will cause runtime errors.
59
+ Use `ng generate @tech4good/angular-schematics:entity <name>` to generate all
60
+ three files and refresh the registries. Manual entity files following the same
61
+ convention are discovered too; no central service edits are required.
48
62
 
49
63
  ### 1.3 Collection Naming
50
64
 
51
- The Firestore collection name is always the **pluralized entity name** and is hardcoded in the store and mock files. Note the convention is simply appending `s` (e.g. `'communitys'`, not `'communities'`). This matches the Firestore collection naming.
65
+ Declare the exact collection name once with `defineEntity` in the model file.
66
+ Stores and mock stores use `communityEntity.collection`. The schematic preserves
67
+ existing naming (append `s`, e.g. `communitys`); it does not rename database data.
68
+ Use a string literal so tooling can resolve it without executing application code.
52
69
 
53
- ### 1.4 Adding a New Entity to `AnyEntity`
70
+ ### 1.4 Generated Entity Registration
54
71
 
55
- When a new entity is generated, it must be added to the union type in `src/app/core/store/app.model.ts`:
56
- ```typescript
57
- export type AnyEntity = Session | Community | User | UserContext;
58
- ```
72
+ `t4g-entities` discovers exported definitions under `src/app` and writes:
59
73
 
60
- And its MockDB store must be registered in `src/app/core/firebase/firebase.mock.service.ts`:
61
- ```typescript
62
- readonly DB = {
63
- 'sessions': inject(SessionMockDB),
64
- 'communitys': inject(CommunityMockDB),
65
- // ... add new entity here
66
- };
74
+ - `src/app/core/store/entities.generated.ts`: `APP_ENTITIES` and `AppEntityMap`.
75
+ - `src/app/core/store/entity-mocks.generated.ts`: `APP_ENTITY_MOCKS`.
76
+
77
+ Keep these generated files in version control for editor support and review;
78
+ regenerate rather than edit them. There is no handwritten `AnyEntity` union.
79
+ Generic code imports `DataEntity`; concrete stores retain their entity's type.
80
+
81
+ Custom mock wiring belongs beside its fixtures:
82
+
83
+ ```ts
84
+ export const communityMock = defineEntityMock(communityEntity, {
85
+ store: CommunityMockDB,
86
+ seeds: COMMUNITY_DB,
87
+ });
67
88
  ```
68
89
 
90
+ Import `defineEntityMock` from `@tech4good/platform-data/testing` and the entity
91
+ definition directly from its relative model file. An entity without a custom
92
+ mock declaration gets an empty in-memory mock collection. Duplicate collection
93
+ or mock declarations fail generation, with the relevant filename.
94
+
95
+ `npm start`, `npm run watch`, and `npm run test:watch` keep discovery running as
96
+ files are added, changed, renamed, or deleted. Build/test/lint commands regenerate
97
+ before running. Use `npm run generate:entities` after manual edits, and
98
+ `npm run check:entities` in CI before regeneration to detect stale committed files.
99
+ Direct `ng`/`jest` commands bypass this setup; run generation first when using them.
100
+
101
+ The app's `provideAppMocks()` supplies `createMockRegistry(APP_ENTITY_MOCKS)` to the shared `MockDataService`. Tests can seed
102
+ any discovered collection with `provideAppMocks({ collections: { users: [] } })`;
103
+ these overrides are typed and an empty array clears that mock collection.
104
+ Production replaces `data.providers.ts` with `data.providers.prod.ts`, which
105
+ never imports the mock registry or fixture modules.
106
+
107
+ Security rules remain app-owned. The schematic retains its existing development
108
+ rule stub and index generation; replacing the stub with the entity's intended
109
+ access policy is still required.
110
+
69
111
  ---
70
112
 
71
113
  ## 2. Soft Deletes
72
114
 
73
- Entities are **never hard-deleted** from Firestore. Instead, `removeEntity` sets `_deleted: true` and `_updatedAt: Timestamp.now()`.
115
+ Entities are **never hard-deleted** from Firestore. Instead, `removeEntity` sets `_deleted: true` and `_updatedAt` to a backend-generated timestamp.
74
116
 
75
117
  This has several implications:
76
118
 
@@ -85,7 +127,7 @@ This has several implications:
85
127
  - The document was soft-deleted (→ remove from local store)
86
128
  - The document no longer matches the query but still exists (→ keep in store)
87
129
 
88
- The `src/app/core/firebase/cached-listeners.service.ts` handles this by using `entityInQueryResults()` to distinguish the two cases.
130
+ The package `CachedListenersService` handles this by using `entityInQueryResults()` to distinguish the two cases.
89
131
 
90
132
  ---
91
133
 
@@ -199,7 +241,9 @@ export const environment = {
199
241
  ```
200
242
 
201
243
  When `mockDB` is true, `app.config.ts` swaps out:
202
- - `FirebaseService` → `FirebaseMockService` (via `DATABASE_SERVICE` token)
244
+ - `FirestoreDataService` → `MockDataService` (via `DATA_ACCESS` token)
245
+ - `FirebaseAuthService` → `MockAuthService` (via `AUTH_ACCESS` token)
246
+ - Firestore profile persistence → mock profile persistence, with the same app profile defaults
203
247
  - `BatchWriteDBService` → `BatchWriteMockService` (via `BATCH_WRITE_SERVICE` token)
204
248
  - Firebase providers are not loaded at all
205
249
 
@@ -219,25 +263,32 @@ Each `<entity>.mock.ts` exports a seed data array (e.g. `COMMUNITY_DB = [...]`).
219
263
 
220
264
  ## 6. Authentication & Access Flow
221
265
 
222
- ### 6.1 Auth State
266
+ ### 6.1 Authentication system
223
267
 
224
- Auth state lives in `src/app/core/store/auth/auth.store.ts`:
225
- - `authStore.afUser` — the Firebase Auth user (uid, email, displayName, photoURL)
226
- - `authStore.user` — a computed signal that looks up the database `User` entity by `afUser.uid`
268
+ The generated application supports Google, passwordless email links, and anonymous guest
269
+ sessions. `AuthStore.afUser` holds the normalized Firebase `AuthSession`; `AuthStore.user`
270
+ resolves the matching Firestore application profile.
227
271
 
228
- On app start, `AppComponent.ngOnInit()` calls `authStore.loadAuth()`, which:
229
- 1. Subscribes to the Firebase auth state (`db.afUser()`)
230
- 2. Performs a blocking `userStore.load()` to ensure the user is in the store before guards run
231
- 3. Then sets up a background `userStore.stream()` for real-time updates
232
- 4. Creates a new database User if one doesn't exist yet
272
+ `AppComponent.ngOnInit()` starts one app-lifetime Firebase auth observer. Fresh sign-in
273
+ methods provision the profile directly after Firebase credentials are ready. Logout and
274
+ guest deletion tear down Firestore streams and reset auth-related state (including
275
+ load history for those reset stores) before invalidating
276
+ the local session.
277
+
278
+ See [`docs-infra/authentication-architecture.md`](authentication-architecture.md) for the
279
+ complete provider flows, same-browser email-link context, account linking, callable guest
280
+ deletion, Firestore rules, and deployment checklist.
233
281
 
234
282
  ### 6.2 Access Pipeline (Guards)
235
283
 
236
284
  Users progress through access states defined in `AccessState`:
237
285
  ```
238
- SUBMIT_INTEREST → WAITING → DONE (+ consented)
286
+ SUBMIT_INTEREST → WAITING → CONSENT → DONE
239
287
  ```
240
288
 
289
+ When `environment.hasWaitlist` is `false`, interest submission moves directly from
290
+ `SUBMIT_INTEREST` to `CONSENT`.
291
+
241
292
  The guard hierarchy is:
242
293
 
243
294
  | Guard | Purpose |
@@ -359,7 +410,7 @@ The project uses `@tech4good/angular-schematics` for code generation. Key schema
359
410
 
360
411
  | Command | What it generates |
361
412
  |---------|-------------------|
362
- | `ng generate entity <name>` | Model + Store + MockDB + seed data array, registers in `AnyEntity` union and `FirebaseMockService.DB` |
413
+ | `ng generate entity <name>` | Model + Store + MockDB + seed data array, defines collection identity in the model and regenerates entity/mock registries |
363
414
  | `ng generate component <name>` | Standard Angular component with the project's section layout and comment headers |
364
415
 
365
416
  > [!CAUTION]
@@ -388,3 +439,37 @@ await this.batch.batchWrite(async (batchConfig) => {
388
439
  ```
389
440
 
390
441
  If an `__id` is not provided to `store.add()`, one is generated automatically. But when you need to reference the ID in a related entity within the same batch, you must pre-generate it.
442
+
443
+
444
+ Shared entity timestamps use `DataTimestamp` and helpers imported directly from
445
+ `@tech4good/platform-data`. Use `dataTimestampNow()` in seeds and
446
+ `dataTimestampToDate(value)` for UI display. The `/firestore` adapter converts
447
+ native SDK timestamps, including domain fields in nested maps/arrays, at the
448
+ read/write/query boundary. Persisted Firestore documents still use native
449
+ Firestore timestamps. The current timestamp-based delta algorithm is unchanged.
450
+
451
+
452
+ ## Shared Runtime Logging
453
+
454
+ Import `injectLogger` from `@tech4good/platform-logging` in an Angular field
455
+ initializer or provider factory:
456
+
457
+ ```ts
458
+ private readonly logger = injectLogger('auth');
459
+ ```
460
+
461
+ Keep the returned logger for later callbacks. Configure logging once using
462
+ `providePlatformLogging` in `app.config.ts`; the data package uses its `data`
463
+ namespace. New generated apps start with logging disabled and opt in to saved
464
+ settings and the DevTools handle only during development:
465
+
466
+ ```js
467
+ debugLogger.enable('data,auth');
468
+ debugLogger.disable();
469
+ ```
470
+
471
+ Namespaces match exactly. Existing saved `query` filters must change to `data`.
472
+ All levels follow the filter. A custom `sink` receives `{ namespace, level,
473
+ values }` for tests or application-specific output. Logging state belongs to its
474
+ Angular injector; no copied local service or data-specific logger provider is
475
+ needed. The application's analytics event logging remains a separate concern.
@@ -1,5 +1,11 @@
1
1
  # Load System Architecture
2
2
 
3
+ > Import shared infrastructure directly from `@tech4good/platform-data`,
4
+ > `@tech4good/platform-data/firestore`, or `@tech4good/platform-data/testing`.
5
+ > Local forwarding files are not generated. Improve the engine in the package;
6
+ > keep app entities, domain methods, seeds, auth policies and query choices here.
7
+
8
+
3
9
  This document details the code-level architecture of the `load()` method in the query system. For a high-level overview of our querying strategy, refer to [querying-strategy.md](./querying-strategy.md).
4
10
 
5
11
  ## 1. Data Structures & State Management
@@ -138,7 +144,7 @@ However, we face a temporal problem: we want to only fetch data that has changed
138
144
  Instead, we group the IDs into **5-minute Time Buckets**:
139
145
 
140
146
  ```typescript
141
- // From app.store.ts
147
+ // From platform-data/src/entity-store.ts
142
148
  const BUCKET_MS = 5 * 60 * 1000;
143
149
  const groupsByBucket = new Map<number, { minTime: number, values: string[] }>();
144
150
 
@@ -164,3 +170,11 @@ The system iterates over these buckets, chunks them into batches of up to 30 (Fi
164
170
  By rounding to the nearest 5-minute bucket, we sacrifice a tiny amount of over-fetching (fetching up to 5 minutes of redundant data) in exchange for keeping the DB reads massively batched.
165
171
 
166
172
  After the fetch completes, **all IDs in the batch are assigned the exact same `newLoadTime`**. This convergence ensures that these entities group together perfectly in future requests, eliminating fragmentation over time.
173
+
174
+
175
+ Shared entity timestamps use `DataTimestamp` and helpers imported directly from
176
+ `@tech4good/platform-data`. Use `dataTimestampNow()` in seeds and
177
+ `dataTimestampToDate(value)` for UI display. The `/firestore` adapter converts
178
+ native SDK timestamps, including domain fields in nested maps/arrays, at the
179
+ read/write/query boundary. Persisted Firestore documents still use native
180
+ Firestore timestamps. The current timestamp-based delta algorithm is unchanged.
@@ -1,5 +1,11 @@
1
1
  # @tech4good/angular-schematics Querying Strategy
2
2
 
3
+ > Import shared infrastructure directly from `@tech4good/platform-data`,
4
+ > `@tech4good/platform-data/firestore`, or `@tech4good/platform-data/testing`.
5
+ > Local forwarding files are not generated. Improve the engine in the package;
6
+ > keep app entities, domain methods, seeds, auth policies and query choices here.
7
+
8
+
3
9
  This document provides a high-level overview of the @tech4good/angular-schematics framework's querying strategy. It is designed to help developers and AI agents think through the best approach for fetching, streaming, and managing database state for highly collaborative systems.
4
10
 
5
11
  ## 1. Designing Collaborative Systems (The Big Picture)
@@ -155,3 +161,11 @@ To solve these problems, the framework uses a complex **Global Multiplexer with
155
161
  If you have a complex scenario that doesn't fit these rules, you must either denormalize the data into the parent document, or use `load()` instead.
156
162
 
157
163
  > **Deep Dive**: See [Stream System Architecture](./stream-system-architecture.md) for code-level details on the Global Multiplexer and listener teardown logic.
164
+
165
+
166
+ Shared entity timestamps use `DataTimestamp` and helpers imported directly from
167
+ `@tech4good/platform-data`. Use `dataTimestampNow()` in seeds and
168
+ `dataTimestampToDate(value)` for UI display. The `/firestore` adapter converts
169
+ native SDK timestamps, including domain fields in nested maps/arrays, at the
170
+ read/write/query boundary. Persisted Firestore documents still use native
171
+ Firestore timestamps. The current timestamp-based delta algorithm is unchanged.
@@ -1,5 +1,11 @@
1
1
  # Stream System Architecture
2
2
 
3
+ > Import shared infrastructure directly from `@tech4good/platform-data`,
4
+ > `@tech4good/platform-data/firestore`, or `@tech4good/platform-data/testing`.
5
+ > Local forwarding files are not generated. Improve the engine in the package;
6
+ > keep app entities, domain methods, seeds, auth policies and query choices here.
7
+
8
+
3
9
  This document details the code-level architecture of the `stream()` method. While `load()` is a one-shot fetch, `stream()` maintains an active websocket to Firestore. For a high-level overview of our querying strategy, refer to [querying-strategy.md](./querying-strategy.md).
4
10
 
5
11
  ## 1. Data Structures & Connection Caching
@@ -9,7 +15,7 @@ Because websockets are expensive and Firestore limits active listeners (100 conc
9
15
  The `CachedListenersService` maintains the cache for complex legacy queries:
10
16
 
11
17
  ```typescript
12
- // From cached-listeners.service.ts
18
+ // From platform-data/src/cached-listeners.ts
13
19
  // Key: "collection.queryParams.queryOptions"
14
20
  private connectionByQueryKey: Record<string, CachedConnection> = {};
15
21
 
@@ -22,7 +28,7 @@ export interface CachedConnection {
22
28
  Separately, the `CachedListenersService` maintains a map of generic `StreamMultiplexer` instances, which are delegated to handle simple queries:
23
29
 
24
30
  ```typescript
25
- // From cached-listeners.service.ts
31
+ // From platform-data/src/cached-listeners.ts
26
32
  // Key: "collection.field"
27
33
  private streamMultiplexers = new Map<string, StreamMultiplexer>();
28
34
  ```
@@ -30,7 +36,7 @@ private streamMultiplexers = new Map<string, StreamMultiplexer>();
30
36
  Inside the `StreamMultiplexer` class itself, the state is split to track component lifecycles and batch pools:
31
37
 
32
38
  ```typescript
33
- // From stream-multiplexer.ts
39
+ // From platform-data/src/stream-multiplexer.ts
34
40
  export class StreamMultiplexer {
35
41
  // Bi-directional tracking between a unique ID and the components (DestroyRefs) that requested it
36
42
  private destroyRefsById = new Map<string, Set<DestroyRef>>();
@@ -180,7 +186,7 @@ Before attempting a complex repack, the system identifies any batch or single li
180
186
  For the remaining streams that contain a mix of active and orphaned IDs, the multiplexer executes a greedy algorithm to mathematically consolidate them:
181
187
 
182
188
  ```typescript
183
- // From stream-multiplexer.ts: executeSmartRepack()
189
+ // From platform-data/src/stream-multiplexer.ts: executeSmartRepack()
184
190
 
185
191
  // 1. Gather all "sparse" single listeners and candidate batches (<= 25 active IDs)
186
192
  const candidateBatches = this.batchedListeners
@@ -207,7 +213,7 @@ for (let i = 0; i < candidateBatches.length; i++) {
207
213
  To ensure absolutely zero UI flickering during this repack, the multiplexer implements an **overlapping teardown** mechanism.
208
214
 
209
215
  ```typescript
210
- // From stream-multiplexer.ts: startNewBatches()
216
+ // From platform-data/src/stream-multiplexer.ts: startNewBatches()
211
217
 
212
218
  // We pass the old sockets as an argument, but we do NOT unsubscribe them yet.
213
219
  const unsubscribeBatch = this.db.streamEntitiesChanges(this.collection, queryParams, {}).subscribe(changes => {
@@ -230,7 +236,7 @@ When a component is finally destroyed, it triggers the teardown sequence. Becaus
230
236
  For standard cached connections, the `CachedListenersService` waits 5 seconds (the "Grace Period") before unsubscribing from Firestore. If the user clicks a link and navigates away but immediately comes back, we don't want to tear down and rebuild the websocket, which causes UI flicker and burns DB reads.
231
237
 
232
238
  ```typescript
233
- // From cached-listeners.service.ts
239
+ // From platform-data/src/cached-listeners.ts
234
240
  destroyRef.onDestroy(() => {
235
241
  setTimeout(() => {
236
242
  connection.registeredSet.delete(destroyRef);
@@ -247,7 +253,7 @@ destroyRef.onDestroy(() => {
247
253
  For simple multiplexed queries, `StreamMultiplexer` also employs a 5-second grace period. However, because a component might have requested a dozen specific IDs, the multiplexer must selectively remove that component's "claim" on each individual ID.
248
254
 
249
255
  ```typescript
250
- // From stream-multiplexer.ts
256
+ // From platform-data/src/stream-multiplexer.ts
251
257
  destroyRef.onDestroy(() => {
252
258
  setTimeout(() => {
253
259
  let triggeredRemove = false;
@@ -281,3 +287,11 @@ destroyRef.onDestroy(() => {
281
287
  ```
282
288
 
283
289
  As seen in the code, tearing down Path B rarely results in an immediate websocket disconnection unless a socket is 100% abandoned. Most often, the IDs simply become "orphaned" and are cleaned up asynchronously during the next Smart Repack.
290
+
291
+
292
+ Shared entity timestamps use `DataTimestamp` and helpers imported directly from
293
+ `@tech4good/platform-data`. Use `dataTimestampNow()` in seeds and
294
+ `dataTimestampToDate(value)` for UI display. The `/firestore` adapter converts
295
+ native SDK timestamps, including domain fields in nested maps/arrays, at the
296
+ read/write/query boundary. Persisted Firestore documents still use native
297
+ Firestore timestamps. The current timestamp-based delta algorithm is unchanged.
@@ -14,7 +14,7 @@ const compat = new FlatCompat({
14
14
 
15
15
  export default defineConfig([
16
16
  // Global ignore
17
- globalIgnores(["projects/**/*"]),
17
+ globalIgnores(["dist/**/*", ".cache/**/*", ".local/**/*"]),
18
18
 
19
19
  // TypeScript files
20
20
  {
@@ -33,7 +33,13 @@ export default defineConfig([
33
33
  // We include app and spec tsconfigs because the root tsconfig.json
34
34
  // explicitly excludes files ("files": []) and only serves to reference the others.
35
35
  // Without these explicit references, ESLint cannot discover the application files.
36
- project: ["tsconfig.json", "tsconfig.app.json", "tsconfig.spec.json"],
36
+ project: [
37
+ "tsconfig.json",
38
+ "tsconfig.app.json",
39
+ "tsconfig.spec.json",
40
+ "projects/analytics/tsconfig.app.json",
41
+ "projects/analytics/tsconfig.spec.json",
42
+ ],
37
43
  createDefaultProgram: true,
38
44
  },
39
45
  },
@@ -97,4 +103,17 @@ export default defineConfig([
97
103
  "@typescript-eslint/no-explicit-any": "off"
98
104
  }
99
105
  },
100
- ]);
106
+ {
107
+ files: ["projects/analytics/**/*.ts"],
108
+ rules: {
109
+ "@angular-eslint/component-selector": [
110
+ "error",
111
+ { prefix: "analytics", style: "kebab-case", type: "element" },
112
+ ],
113
+ "@angular-eslint/directive-selector": [
114
+ "error",
115
+ { prefix: "analytics", style: "camelCase", type: "attribute" },
116
+ ],
117
+ },
118
+ },
119
+ ]);
@@ -5,6 +5,12 @@
5
5
  "rules": "firestore.rules",
6
6
  "indexes": "firestore.indexes.json"
7
7
  },
8
+ "functions": {
9
+ "source": "functions",
10
+ "predeploy": [
11
+ "npm --prefix \"$RESOURCE_DIR\" run build"
12
+ ]
13
+ },
8
14
  "hosting": {
9
15
  "public": "dist/<%= dasherize(project) %>/browser",
10
16
  "ignore": [
@@ -1,5 +1,28 @@
1
1
  {
2
2
  "indexes": [
3
+ {
4
+ "collectionGroup": "userContexts",
5
+ "queryScope": "COLLECTION",
6
+ "fields": [
7
+ {
8
+ "fieldPath": "__userId",
9
+ "order": "ASCENDING"
10
+ },
11
+ {
12
+ "fieldPath": "_deleted",
13
+ "order": "ASCENDING"
14
+ },
15
+ {
16
+ "fieldPath": "_updatedAt",
17
+ "order": "ASCENDING"
18
+ },
19
+ {
20
+ "fieldPath": "__name__",
21
+ "order": "ASCENDING"
22
+ }
23
+ ],
24
+ "density": "SPARSE_ALL"
25
+ },
3
26
  {
4
27
  "collectionGroup": "users",
5
28
  "queryScope": "COLLECTION",