Next.js App - Personalized Email Invitation System for Web App

# Email Invite System for Existing [login to view URL] + Supabase Web App ## Project overview We have an existing web application built in Lovable using [login to view URL], Supabase, and Tailwind CSS, deployed on Vercel. The app is a self-assessment tool used by companies, where each company has an admin user and one or more team members. We need to replace the current shared invite link flow with a personalized email invite system. Each invite must be tied to a specific email address, sent via transactional email, and only usable by the named recipient. This is a focused backend and integration project. No new visual design work is required. The existing dashboard UI will receive a functional update to the invite section, but the broader design system is already established. ## Current state The app already has: - Working authentication via Supabase Auth - A `companies` table and a `company_members` table with role distinctions - A functioning company dashboard for admins - A shared invite link flow that allows anyone with the link to join a company (this is what we are replacing) - Vercel deployment with a production environment at a subdomain of [login to view URL] ## Detailed scope ### 1. Email infrastructure setup - Create and configure a Resend account on the free tier - Verify the [login to view URL] domain in Resend, including all required DNS records (SPF, DKIM, DMARC as applicable) - Store the Resend API key as a Supabase secret named `RESEND_API_KEY` - Confirm test emails deliver to inbox (not spam) from at least three major providers (Gmail, Outlook, Apple Mail) ### 2. Database schema Create a new table in Supabase called `company_invites` with the following columns: - `id` (uuid, primary key, default `gen_random_uuid()`) - `company_id` (uuid, foreign key to `[login to view URL]`, on delete cascade) - `invited_email` (text, not null) - `invite_token` (uuid, default `gen_random_uuid()`, unique) - `status` (text, default 'pending', check constraint: 'pending' | 'accepted' | 'expired') - `invited_by` (uuid, foreign key to `[login to view URL]` or equivalent user table) - `created_at` (timestamp with time zone, default `now()`) - `expires_at` (timestamp with time zone, default `now() + interval '7 days'`) - `accepted_at` (timestamp with time zone, nullable) Add a unique constraint on (`company_id`, `invited_email`) where `status = 'pending'` to prevent duplicate active invites. ### 3. Row-level security policies - Admins of a company can `INSERT` invites for that company - Admins of a company can `SELECT` all invites for their company - A specific invite row is `SELECT`-able by anyone presenting the matching `invite_token` (read-only, via Edge Function preferred over direct client query) - No `UPDATE` or `DELETE` from client-side, only from Edge Functions using the service role key ### 4. Supabase Edge Functions Three Edge Functions, written in TypeScript: **`create-and-send-invite`** - Authenticates the caller and verifies they are an admin of the specified company - Validates the email format - Checks for an existing pending or accepted invite for the same email and company, returns a descriptive error if found - Checks whether the email is already a member of the company, returns a descriptive error if found - Inserts a new row into `company_invites` - Calls `send-invite-email` with the recipient email, company name, and invite token - Returns success or a structured error response **`send-invite-email`** - Accepts `recipientEmail`, `companyName`, and `inviteToken` as parameters - Constructs a clean, functional HTML email with subject "You've been invited to join [companyName] on the North Star Self-Assessment Tool" - Includes a call-to-action button linking to `https://[production-domain]/join/[inviteToken]` - Sends via Resend API - Returns success or error **`accept-invite`** - Accepts an `inviteToken` parameter - Looks up the invite, validates it exists, is not expired, and has status 'pending' - Validates that the calling user's email matches `invited_email` (case-insensitive) - Within a single transaction: marks the invite as 'accepted', sets `accepted_at`, and inserts a row into `company_members` with role 'member' - Returns success with the company ID for redirect, or a descriptive error ### 5. Admin invite UI Replace the existing shared invite link section on the company dashboard with: - A multi-email input that allows entering multiple email addresses separated by commas, spaces, or newlines, with an "Add another" affordance for a clearer one-at-a-time entry mode - A "Send Invites" button that calls `create-and-send-invite` for each address and shows per-email success or error feedback - A pending invites table showing email, date sent, status (pending / accepted / expired), and a "Resend" action for pending or expired invites that refreshes the expiry to 7 days from now and resends the email - Inline validation that prevents sending to emails already pending or accepted for that company - Loading states and clear error messaging throughout UI should match the existing Tailwind-based design language. No new visual design work required, just functional implementation consistent with the current dashboard. ### 6. Invite acceptance flow Create a new page at `/join/[inviteToken]` that handles four distinct scenarios: **Scenario A: New user (no account exists for the invited email)** - Show signup form with email pre-filled and locked - On submit, create the account, call `accept-invite`, redirect to the assessment **Scenario B: Existing user, logged out** - Detect that the email already has an account - Show "Log in to accept invite" prompt with email pre-filled - On successful login, call `accept-invite`, redirect to the assessment **Scenario C: Existing user, currently logged in as the invited email** - Show "Accept invite to join [Company Name]?" confirmation - On accept, call `accept-invite`, redirect to the assessment **Scenario D: Existing user, currently logged in as a different email** - Show "This invite is for [invited email]. You are logged in as [current email]. Please log out and use the correct account." - Provide a "Log out" button Additionally, handle these error states with clear messaging: - Invite token not found - Invite expired (past `expires_at`) - Invite already accepted (single-use) - Database or network error ### 7. Legacy system removal Once the email invite flow is verified working in production: - Remove the existing shared invite link UI from the dashboard - Remove the `/join/[inviteCode]` route - Confirm no other parts of the app reference the old flow - Leave the `company_invites` table and the new `/join/[inviteToken]` route in place ### 8. Testing and handoff - End-to-end test of all four acceptance scenarios in production - Spam folder check across Gmail, Outlook, and Apple Mail - Brief handoff document covering: how to add new admins, how to monitor Resend deliverability, how to manually expire or revoke invites if needed, and a list of the deployed Edge Functions with their purposes ## Out of scope The following will not be addressed under this engagement: - Visual redesign of the dashboard or other app surfaces - Changes to the assessment tool itself - Migration of any data from the existing shared-link invites - Custom email template design beyond a clean functional layout - Ongoing maintenance beyond a 14-day post-launch bug fix window - Multi-language support - Bulk CSV upload for invitations (single email entry only) ## Technical requirements - All code written in TypeScript where applicable - Edge Functions written for Deno runtime per Supabase standards - Frontend code consistent with existing [login to view URL] + Tailwind patterns in the project - All database changes made via Supabase migration files, not direct SQL in the dashboard - Code committed to the existing GitHub repository on a feature branch, with a clean commit history and a pull request for review - No new third-party dependencies introduced without justification ## What we will provide - Access to Lovable, Supabase, Vercel, GitHub, and the domain registrar - Resend account creation (we will handle this ourselves and share API keys securely) - Timely responses to questions within 2 business days - Review feedback within 3 business days of receiving a milestone - A staging environment for testing before production deployment ## What we are looking for in a bidder - Demonstrated experience with Supabase, specifically Edge Functions and Row-Level Security - Experience integrating Resend or a comparable transactional email provider - A portfolio that includes at least one production auth or invite flow - Clear written English communication - Ability to commit to the agreed timeline ## Timeline We are targeting completion within 4 to 6 weeks from project start, with weekly progress check-ins. Bidders should propose their own timeline and milestone breakdown. ## Bid format To be considered, your bid must include: 1. Your proposed fixed price for the scope above 2. Your proposed timeline with at least three milestones 3. Links to two relevant past projects, ideally involving Supabase or invite/auth flows 4. A brief response (3 to 5 sentences) to this question: "Looking at the scope above, what is the most likely source of unexpected complexity, and how would you handle it?" Bids that do not address question 4 will not be reviewed. We are using this question to filter for bidders who have actually read the brief and have real experience with this type of work. About us North Star Project is a mission-driven organization developing ethical standards for the emerging psychedelics industry. We work with care, transparency, and an emphasis on building things well rather than fast. We are looking for a contractor who shares those values.

Project ID: 40450625