Responses to the HeyTalia dev team's questions, grounded in RFC-027, RFC-028, and the in-progress PG integration.
1. Frontend delivery
Q: Will HeyTalia be rendered as a REST-only model where TW renders all UI and we only provide responses? If not, then how will it be rendered — iframe / etc?
HT lives inside the TW monolith as an app under web/apps/heytalia/*. Not REST-only, not iframe. Same pattern PG is following.
The HT React frontend is rebuilt (or progressively ported) inside web/apps/heytalia/* against TW's shared design system. HT's backend (Lambdas, DDB, Bedrock KB) stays where it is and becomes a private service called by TW BFF.
2. Authentication
Q: How does a TW-logged-in teacher authenticate to ht-core's backend? Today ht-core trusts PG's backend and a shared API key. For TW we need either (i) a TW backend endpoint that performs the equivalent server-side proxy, (ii) a way for TW's existing identity provider to issue a token that ht-core can validate, or (iii) something else.
TW BFF terminates auth. HT backend trusts a short-lived JWT from TW BFF instead of a browser-side x-api-key.
- Browser ↔ TW: session cookie, session in Valkey
- TW BFF ↔ HT:
Authorization: Bearer <JWT>, HS256 initially, JWKS later
- Short-lived (minutes), per downstream call
- HT validates
iss=tw, aud=heytalia, exp
Migration: Phase A, TW BFF forwards the existing API key alongside the JWT, HT accepts either. Phase B, HT adds JWT validation, API key removed from the request path.
3. Request shape
Q: Where do pgStaffId, pgSchoolId, staffEmailAdd come from in a TW request? Do TW's user identifiers map 1:1 onto PG's identifiers?
pgStaffId, pgSchoolId, staffEmailAdd are PG-specific. TW BFF will map TW identity into HT's expected shape:
staffEmailAdd ← TW emailpgStaffId ← TW mims_staff_idpgSchoolId ← TW school_code
This only works for users who are also PG users. Recommend renaming these to staffId/schoolId on HT side before onboarding non-PG users.
4. Draft destination
Q: Where do generated announcements and consent forms go after HeyTalia creates them? Does HeyTalia need to emit a new output format, or will it go to TW's equivalent of an Announcement / Form creation page?
Lean: HT writes to its own draft store, TW renders it inside /heytalia/*. A separate "Send to PG" action calls the PG proxy explicitly. Avoids cross-app coupling.
5. UX boundaries
Q: How much of HeyTalia's current features survives inside TW's sidebar — rich-text editing, file upload, modals, conversation history, feedback buttons, placeholder-filling workflow? Some of these will conflict with other LLM's UI.
HT renders inside the TW shell using TW's shared components. Rich-text editor, file upload, modals, conversation history, placeholder filling all stay. Modals use TW's modal system. Feedback thumbs see §9.
6. User base
Q: The KB today is populated with past PG announcements and consent forms tagged by school. If TW users span a different set of schools / users that are not PG users, we need to verify that existing school-level data isolation still holds. If TW spans a broader set of data beyond PG, are there opportunities to expose this data to HT to build up HT's KB for more use cases?
KB isolation: HT's KB is school-tagged. Please confirm retrieval is school-scoped at the query layer, not just the UI, and document the ACL model.
Broader TW data feeding HT's KB: out of scope for migration. Follow-up RFC.
7. Chat input ownership
Q: Does TW own the chat input box or does each agent bring its own?
Lean: each app brings its own input for v1. A global TW chat router is a much bigger commitment and isn't on the RFC-027 roadmap. Revisit when there are 2+ chat agents.
8. Features
Q: Can agents open modals, take over more screen, or accept file uploads?
- Modals: yes, via TW shared modal
- Screen takeover: HT owns the
/heytalia/* route subtree. Cannot take over TW chrome
- File upload: yes, via TW shared upload, HT keeps its S3/extraction pipeline
9. Monitoring and feedback
Q: When HeyTalia looks broken inside TW, who owns triage? When TW's sidebar changes and HeyTalia renders incorrectly as a result, who notices first? Users will likely give feedback on the whole TW experience rather than being aware which part is HT vs PG vs TW — how does feedback flow down, and what if a user gives feedback about TW stuff via HT's existing feedback functionality?
Triage:
- TW shell breaks → TW platform
- HT functionality breaks → HT
- HT renders wrong because TW shell changed → joint, TW first responder
TW propagates a request ID; HT logs include it. HT's CloudWatch dashboards stay.
Feedback: TW owns one platform feedback widget. Submissions tagged with active app + route, fanned out. HT-tagged feedback writes to HT's existing feedback-handler. HT removes its in-chat thumbs UI but keeps its feedback backend.
10. Claims
Q: What claims are available about an authenticated user? Specifically: a stable and unique user identifier, email, full name, role(s), school identifier (or list), and organisation identifier.
Proposed JWT claims TW BFF mints for HT:
sub — stable MIMS user idemailnamerolesschool_codeorg_idmims_staff_id
11. Session lifetime
Q: What is the session lifetime on TW's side? We need to design a token/session refresh strategy that does not log teachers out of HeyTalia before TW does.
- TW session: proposed 8h sliding (TBC)
- JWT TW→HT: ~5 min, minted per call
- HT holds no session of its own. HT cannot log a user out before TW does.
12. Reference integration and context intelligence
Q: Is there a reference implementation of an already-integrated agent we can study? There was mention of a context intelligence layer in TW during the DXD town hall — how does the HT migration synergize with this layer?
PG is the first and only app being integrated under RFC-027/028. See PG-INTEGRATION-APPROACH.md, PG-API-CONTRACT.md, PG-PROXY-CONTRACT.md in the TW repo.
Context intelligence layer: addressed separately.
On HT's architecture concern
Q (Platform architecture & hosting): Is there an architecture diagram? Does the eventual architecture allow for independent deployment / backwards compatibility across integrations? RFC-027 suggests building HT frontend code inside the TW monolith (same as PG today), which goes against the long-term vision for HT to be scalable/embeddable across platforms. This sounds counterproductive unless the long-term bet is that all HT use cases live within TW.
RFC-027 explicitly puts app FE code inside the TW monolith, which conflicts with HT's "embeddable across platforms" vision. RFC-027 calls this out in Drawbacks ("Independent deployment not supported without future architectural changes"). The current bet is that for the next 12 months, all HT use cases worth supporting live inside TW. If HT needs to embed in a non-TW host later, that's a future RFC for runtime bundle integration. Known constraint, not an oversight.
Responses to the HeyTalia dev team's questions, grounded in RFC-027, RFC-028, and the in-progress PG integration.
1. Frontend delivery
Q: Will HeyTalia be rendered as a REST-only model where TW renders all UI and we only provide responses? If not, then how will it be rendered — iframe / etc?
HT lives inside the TW monolith as an app under
web/apps/heytalia/*. Not REST-only, not iframe. Same pattern PG is following.The HT React frontend is rebuilt (or progressively ported) inside
web/apps/heytalia/*against TW's shared design system. HT's backend (Lambdas, DDB, Bedrock KB) stays where it is and becomes a private service called by TW BFF.2. Authentication
Q: How does a TW-logged-in teacher authenticate to ht-core's backend? Today ht-core trusts PG's backend and a shared API key. For TW we need either (i) a TW backend endpoint that performs the equivalent server-side proxy, (ii) a way for TW's existing identity provider to issue a token that ht-core can validate, or (iii) something else.
TW BFF terminates auth. HT backend trusts a short-lived JWT from TW BFF instead of a browser-side
x-api-key.Authorization: Bearer <JWT>, HS256 initially, JWKS lateriss=tw,aud=heytalia,expMigration: Phase A, TW BFF forwards the existing API key alongside the JWT, HT accepts either. Phase B, HT adds JWT validation, API key removed from the request path.
3. Request shape
Q: Where do
pgStaffId,pgSchoolId,staffEmailAddcome from in a TW request? Do TW's user identifiers map 1:1 onto PG's identifiers?pgStaffId,pgSchoolId,staffEmailAddare PG-specific. TW BFF will map TW identity into HT's expected shape:staffEmailAdd← TWemailpgStaffId← TWmims_staff_idpgSchoolId← TWschool_codeThis only works for users who are also PG users. Recommend renaming these to
staffId/schoolIdon HT side before onboarding non-PG users.4. Draft destination
Q: Where do generated announcements and consent forms go after HeyTalia creates them? Does HeyTalia need to emit a new output format, or will it go to TW's equivalent of an Announcement / Form creation page?
Lean: HT writes to its own draft store, TW renders it inside
/heytalia/*. A separate "Send to PG" action calls the PG proxy explicitly. Avoids cross-app coupling.5. UX boundaries
Q: How much of HeyTalia's current features survives inside TW's sidebar — rich-text editing, file upload, modals, conversation history, feedback buttons, placeholder-filling workflow? Some of these will conflict with other LLM's UI.
HT renders inside the TW shell using TW's shared components. Rich-text editor, file upload, modals, conversation history, placeholder filling all stay. Modals use TW's modal system. Feedback thumbs see §9.
6. User base
Q: The KB today is populated with past PG announcements and consent forms tagged by school. If TW users span a different set of schools / users that are not PG users, we need to verify that existing school-level data isolation still holds. If TW spans a broader set of data beyond PG, are there opportunities to expose this data to HT to build up HT's KB for more use cases?
KB isolation: HT's KB is school-tagged. Please confirm retrieval is school-scoped at the query layer, not just the UI, and document the ACL model.
Broader TW data feeding HT's KB: out of scope for migration. Follow-up RFC.
7. Chat input ownership
Q: Does TW own the chat input box or does each agent bring its own?
Lean: each app brings its own input for v1. A global TW chat router is a much bigger commitment and isn't on the RFC-027 roadmap. Revisit when there are 2+ chat agents.
8. Features
Q: Can agents open modals, take over more screen, or accept file uploads?
/heytalia/*route subtree. Cannot take over TW chrome9. Monitoring and feedback
Q: When HeyTalia looks broken inside TW, who owns triage? When TW's sidebar changes and HeyTalia renders incorrectly as a result, who notices first? Users will likely give feedback on the whole TW experience rather than being aware which part is HT vs PG vs TW — how does feedback flow down, and what if a user gives feedback about TW stuff via HT's existing feedback functionality?
Triage:
TW propagates a request ID; HT logs include it. HT's CloudWatch dashboards stay.
Feedback: TW owns one platform feedback widget. Submissions tagged with active app + route, fanned out. HT-tagged feedback writes to HT's existing
feedback-handler. HT removes its in-chat thumbs UI but keeps its feedback backend.10. Claims
Q: What claims are available about an authenticated user? Specifically: a stable and unique user identifier, email, full name, role(s), school identifier (or list), and organisation identifier.
Proposed JWT claims TW BFF mints for HT:
sub— stable MIMS user idemailnamerolesschool_codeorg_idmims_staff_id11. Session lifetime
Q: What is the session lifetime on TW's side? We need to design a token/session refresh strategy that does not log teachers out of HeyTalia before TW does.
12. Reference integration and context intelligence
Q: Is there a reference implementation of an already-integrated agent we can study? There was mention of a context intelligence layer in TW during the DXD town hall — how does the HT migration synergize with this layer?
PG is the first and only app being integrated under RFC-027/028. See
PG-INTEGRATION-APPROACH.md,PG-API-CONTRACT.md,PG-PROXY-CONTRACT.mdin the TW repo.Context intelligence layer: addressed separately.
On HT's architecture concern
Q (Platform architecture & hosting): Is there an architecture diagram? Does the eventual architecture allow for independent deployment / backwards compatibility across integrations? RFC-027 suggests building HT frontend code inside the TW monolith (same as PG today), which goes against the long-term vision for HT to be scalable/embeddable across platforms. This sounds counterproductive unless the long-term bet is that all HT use cases live within TW.
RFC-027 explicitly puts app FE code inside the TW monolith, which conflicts with HT's "embeddable across platforms" vision. RFC-027 calls this out in Drawbacks ("Independent deployment not supported without future architectural changes"). The current bet is that for the next 12 months, all HT use cases worth supporting live inside TW. If HT needs to embed in a non-TW host later, that's a future RFC for runtime bundle integration. Known constraint, not an oversight.