Product: Section 1 | Coordinator: Invite Guest

[rpradheap]

🧩 Overview

Define and document the functionality to enable Coordinators to send an email invitation to Guests directly from the Dashboard. This invite allows the Guest to create an account and begin their application (Intake Profile) in the HUU system.

We need to provide Coordinators with a seamless digital tool to invite Guests to the platform so that they can begin the onboarding and intake process without relying on physical forms.

🧩 Objective

Create a documented feature specification for email-based Guest invitations initiated by Coordinators, including data entry, validation, email content, backend tracking, and assignment logic.

Example: Deliver a complete, testable specification that ensures reliable account invites, intuitive UX, and proper data linkage between Guests and Coordinators.

🔍 Context / Background

Host Home Handbook: Offers complete insight into the Coordinator role, onboarding workflows, and importance of digitizing the guest intake process.

Problem 4.pdf: Describes the current limitation (paper-based invite process) and proposes the new invite feature, including its goals, acceptance criteria, and UX expectations .

Figma Link

Related Engineering Issues:

#477 – Guest Invite Feature

#461 – Dashboard Enhancements

#405 – Guest Account Linking

#699 – Coordinator Dashboard

📌 Scope of Work

Design email invite UI on the Coordinator dashboard

Define input fields (name, email) with validation rules

Document invite email content and formatting

Design error/success states for invite workflow

Define backend logic to store invite metadata

Assign the Coordinator to the Guest at point of invite

Capture and store timestamps and status updates

Ensure alignment with status flow logic (Invite Sent → Account Confirmed)

Link invite to analytics for tracking invite-to-signup conversion rate

🧠 Problem Statement

Currently, Coordinators rely on paper forms to initiate guest applications. This creates logistical delays, increases administrative work, and limits data accuracy. A digital invitation flow will streamline the process and improve platform adoption.

🙋‍♀️ User Story

As a Coordinator, I want to send an email to invite Guests, So that they can create an account and start their application (Intake Profile) in the HUU system.

🎯 Acceptance Criteria (Definition of Done)

• [ ] Coordinator can initiate invite flow from the dashboard
• [ ] UI accepts First Name (required), Middle Name (optional), Last Name (required), and Email (required)
• [ ] Input fields are validated (email syntax, required fields) before sending
• [ ] Coordinator receives feedback on success/failure of the invitation
• [ ] Sent invitations are stored and viewable in dashboard table (per Issue #501)
• [ ] Timestamps are saved in backend for all invites
• [ ] Guest status is updated to "Invite Sent" → "Account Confirmed" when applicable
• [ ] Invited Guests are automatically assigned to the inviting Coordinator
• [ ] Email content includes explanation and account creation link
• [ ] Feature is documented and handed off for design and engineering

🖼️ Design Notes (Preliminary)

✅ Ready for Design

Refer to existing Figma dashboard invite components

Style should align with HUU design system (form fields, modals)

Feedback alerts should be inline and clear (e.g., red for error, green for success)

Consider progressive disclosure for advanced invite options in the future (e.g., resend, revoke)

🛑 Constraints / Risks / Workflow Dependency

No revoke or resend functionality in MVP – scope for future phase

Must validate Coordinator permissions to invite Guests

Ensure backend mapping between Guest, Coordinator, and email status

Compliance: Email content must respect privacy policies (GDPR, etc.)

Risk of duplicate invites if email isn’t verified prior to sending – handle duplicate cases gracefully

[pardhama]

Check with engineering regarding personalization of email text and work on the draft

[sanya301]

Check if invites expire, and define a flow in the story for what happens if it does expire What happens if co-ordinator sends two invites which are still in the "active" timeframe

[erikguntner]

The temporary passwords in the invite do expire. The default is 7 days and can be adjusted all the way up to 365 days. I'll look into sending new invites.

[stevbark]

I can work on this for the Engineering side. One note is that it says this has both front and back end components and I am focused on backend atm.

[edela0015]

Quick question: are we giving the coordinator the ability to revoke the invite as well? or resend? thank you.

[randelbrot]

Hi @edela0015,

Is there a user scenario that you are envisioning for revoke invite? If we think it will be an infrequent occurrence and it's not critical, it's ok to leave out in the first version.

For resend, my take is that we keep it simple/low effort in this version and just allow Coordinators to go through the user flow again to invite a user, versus build dedicated re-send invite functionality.

[KowDesign]

https://www.figma.com/file/BNWqZk8SHKbtN1nw8BB7VM/HUU-Everything-Figma-Nov-2022?type=design&node-id=5872-72669&mode=design&t=6P4UHiA7FqyFeQuC-4

[rpradheap]

@KowDesign - Please check my comment in Figma about the Invite Guest Button placement. I think the pages once we click the invite - name and email looks good .

[erikguntner]

@stevbark The back end is actually already in place for this. @rochun is currently working on the front end

[erikguntner]

@stevbark scratch that. It's most of the way there, but still needs some updates

[KowDesign]

@KowDesign - Please check my comment in Figma about the Invite Guest Button placement. I think the pages once we click the invite - name and email looks good .

@rpradheap here is the updated design

[erikguntner]

@KowDesign @rpradheap I put together a user flow so engineering can have a better idea of how this is supposed to work together. Let me know if it looks right and feel free to make changes.

https://www.figma.com/file/BNWqZk8SHKbtN1nw8BB7VM/HUU-Everything-Figma-Nov-2022?type=design&node-id=8071-110097&mode=design&t=qXPmdmA4atJvkami-4

[rochun]

@erikguntner I'm in the process of adding the API route for the host's invite guest functionality. Are we considering separating concerns for files between auth and host API services? Or should I add the invite guest endpoint to the services/auth.ts file?

[erikguntner]

@rochun Yeah, good idea. This should probably go in a separate service for coordinators

[rochun]

@erikguntner okay, sounds good. I'll go ahead and create a new coordinator service.

[sanya301]

@lasryariel to review and close this out, or come up with action items

[lasryariel]

There are a few acceptance criteria that have not been met. will discuss in todays meeting.

[lasryariel]

@tylerthome will be updating dev.homeunite.us to have it show data that matches the data model, rather than dummy data. This will allow us to check things like Coordinator assignment to invited guest, status updates, and other applicable acceptance criteria.

[lasryariel]

Reviewed acceptance criteria, these items remain: Engineering:

• add middle name as optional
• show actual invited guests in coordinator dashboard
• ask engineering about email bounce back

We can discuss with engineering during the next meeting.

PM updates to story:

• leave out high level explanation for invite
• future consideration: make invite guest email configurable by org

[sanya301]

@lasryariel I just discovered, there seems to be another story with the same functionality but marked in a separate section https://github.com/hackforla/HomeUniteUs/issues/405. Can you confirm whether 405 is a duplicate, and that everything in that story is covered here?