Salvia Onboarding & Frontend Architecture Plan

[REM-moe]

1. Is Phase 1 Complete?

Yes, the core foundation of Phase 1 is complete. The backend successfully handles:

• Authentication: Registration, Login, and JWT Token generation.
• Multi-tenancy: Organizations and Staff roles/permissions (RBAC).
• Core Entities: Beneficiaries, Groups, Generated Notes, Document Flows, and Activity Logs.
• Robust Schema: The database is highly structured with strict constraints and automated triggers (e.g., unique organization slugs).

However, the system is not yet fully "Apt" for Paid Subscriptions.
Currently, the /auth/register endpoint allows anyone to create an organization for free. The database does not yet have tables for Subscriptions, Packages, or Stripe Customer IDs. To support your new flow, we need to add a billing layer.

---

2. Proposed SaaS Onboarding Flow

Your proposed flow is excellent and aligns perfectly with modern SaaS best practices. Here is the recommended architecture for the new flow:

Phase A: The External Marketing Site (Web)

1. Pricing Page: Displays the predefined monthly packages (e.g., Basic, Pro) and a "Contact Us" option for Custom packages.
2. Checkout Process: When a user selects a package, they fill out the basic admin/owner data (Name, Email, Org Name).
3. Payment (Stripe): The user enters payment details. Best Practice: Use Stripe Checkout (hosted by Stripe) for maximum security and minimal frontend code, or Stripe Elements if you want a fully custom UI.

Phase B: The Webhook & Account Creation (Backend)

When the payment is successful, Stripe automatically triggers a webhook to our backend.

1. Stripe Webhook Handler: The backend receives a checkout.session.completed event.
2. Automated Provisioning:
   • The backend automatically creates the Organization and the User (Admin).
   • Since the user didn't enter a password during checkout, the backend generates a secure, random provisional password.
3. Email Dispatch: The backend sends a "Welcome to Salvia" email.
   • Best Practice: The email contains a secure, one-time "Setup Your Account" link, rather than sending a raw password in plain text. This link directs them to a Set Password screen on the frontend.

Phase C: First Login & Activation (Frontend App)

1. Password Setup: The user clicks the email link, lands on the Salvia Web App (or Mobile App deep link), and sets their permanent password.
2. Initial Login: Upon saving the password, the user is immediately logged in (tokens are stored securely).
3. Guided Onboarding: The user lands on a "Welcome" dashboard that guides them to their first "Aha!" moment (e.g., "Add your first Staff member" or "Create your first Beneficiary").

---

3. Plan for the Frontend Developers (Flutter Web + Mobile)

Based on the architecture above, the frontend teams should divide their work into these core modules:

Module 1: The Marketing & Checkout Gateway (Web)

• Landing & Pricing Pages: Showcase features and packages.
• Data Collection Form: Collect first_name, last_name, email, and org_name prior to payment.
• Stripe Integration: Integrate Stripe SDK to securely handle credit card inputs and initiate the subscription.

Module 2: Authentication & Onboarding (Web + Mobile)

• Set Password Screen: A screen that securely accepts a token from the welcome email and allows the user to set their password.
• Login Screen: Standard Email/Password login.
• Forgot/Reset Password Flow: Essential for account recovery.

Module 3: Core Application Dashboard (Web + Mobile)

• Note: Mobile will likely focus more on the daily tasks (recording audio, viewing beneficiaries), while Web will handle rich admin tasks (managing billing, heavy data entry).
• Beneficiary Management: Views to list, add, and view beneficiary profiles.
• Audio Recording (Mobile Priority): The core feature allowing staff to record and upload audio notes.
• Note Verification: UI for reviewing, editing, and approving AI-generated clinical notes.
• Staff/Admin Settings (Web Priority): Interfaces to invite new staff members, manage roles, and (eventually) manage the Stripe subscription (upgrade/downgrade/cancel).

---

4. Next Steps for Backend (To Support Frontend)

To unblock the frontend's payment flow, the backend team (us) needs to complete the following:

1. Database Updates: Add packages, subscriptions, and update organizations to link to a stripe_customer_id.
2. Stripe Integration: Implement the Stripe Go SDK to create checkout sessions and handle webhooks.
3. Email Service: Integrate an email provider (e.g., SendGrid, AWS SES) to send the Welcome/Password Setup emails.
4. Password Setup Endpoint: Create a secure endpoint to handle the one-time token and set the initial password.