Skip to content
SeedTrust Docs

SeedTrust Domain Knowledge

This document provides a central repository of domain knowledge for the SeedTrust platform. Its purpose is to help team members (new and old) understand the business logic, architecture, and core concepts of the application.

1. Overview

SeedTrust is a platform for managing the financial aspects of surrogacy and egg donation journeys. It provides a dedicated team of Escrow specialists, Payment Admins, and more to review contracts, create disbursement requests, and manage transactions. The goal is to provide a good user experience, with transparency and efficiency.

2. Core Concepts & Terminology

  • Intended Parents (IPs): The individuals or couple who will be the legal parents of the child.
  • Intended Parent Representative (IP Rep ip_company): Represents the Intended Parent as if they were the intended parent. Uncommon, but is a user in the system as well.
  • Surrogate (GC - Gestational Carrier): The person who carries the pregnancy.
  • Agency: The organization that facilitates the surrogacy arrangement.
  • Disbursement Request (DRs): A payment made from the escrow account for an approved expense.
  • Ledger (Transactions): The detailed record of all financial transactions within a case.
  • Escrow Agreement: The legal document outlining the terms of the fund management.
  • GSA (Gestational Surrogacy Agreement): The legal contract between intended parents and surrogate that defines compensation, responsibilities, and terms of the surrogacy arrangement.
  • Case (ip_case): Represents the surrogacy or egg donor journey. This is the glue for the intended parent, surrogate/donor, and agency.
  • ACH Form: A form that collects banking information and authorization for Automated Clearing House (ACH) transactions. This allows electronic transfers between bank accounts for payments and deposits. The form captures personal details, banking information (routing/account numbers), and required authorizations for processing electronic payments. An ACH form can belong to an Agency, Vendor, Surrogate, or Intended Parent.
  • Scheduled Payment (SPC): Scheduled payment calendar of payments that are to be paid based on the contract for the case.
  • Compensation: Compensation records can represent a created scheduled payment, or is a disbursement request type. The differentiator is mostly the calendar_date field
  • Nacha (National Automated Clearing House Association): The organization that governs the ACH Network in the United States. Nacha establishes the rules, standards, and guidelines for ACH transactions, including formatting requirements, processing timelines, and compliance obligations. When processing ACH payments through forms like MasterACHForm, transactions must comply with Nacha rules for proper routing, settlement, and risk management. This has a dashboard and generally only 1 admin is approving it and creating the file.
  • Deposit Notifications: Deposits that are either submitted by a user that generally aren’t approved or confirmed yet. Once confirmed in the bank, and Admin approves it and it becomes a real transaction.
  • Redaction: In SeedTrust there are a few redaction rules. Futher rules for redaction are below.
  • Lost Wages (LWC): Lost Wages Calculator represents the tool in the admin/user side to calculate the lost wages that will be owed to the surrogate.
  • Agency Teams (Teams): There is a teams system that is used to group together escrow specialists and assign them to agencies.
  • Case Actions: Are actions performed by different users to make a timeline of what user has done what to a case.

3. User Roles & Permissions

  • Admin (admin): The SeedTrust operations team. This includes Escrow Specialists, Payment Admins, and Sales Admins. There are additional roles, and these are customized based on a comprehensive permission system that provides custom granular permissions for nearly every feature in SeedTrust.
  • Agency Owner (agency_owner): The owner of an agency, or a higher level user of the agency. Gives access to the agencies banking information editing. Can only access cases that are within the agency.
  • Case Manager (CM): Oversees the entire surrogacy journey from start to finish. Prior to having a GSA (Gestational Surrogacy Agreement) on file, all disbursement requests are reviewed by the CM. The CM provides SeedTrust with the GSA and journey updates including all pregnancy milestones (transfer, heartbeat confirmation, and delivery updates). They act as a guide to both the Intended Parents and Gestational Carrier, supporting the journey and ensuring clear communication and understanding of all aspects of the surrogacy process. CMs are assigned to cases and can theoretically work with different agencies, though this is not typically the case.
  • Intended Parent (IP): Intended parent is the parent of the case. There can be multiple of these on the same case. They are able to submit DR’s, view scheduled payments, view the ledger for their cases, and sign their escrow agreement.
  • IP Rep (ip_company): IP Rep’s are the representatives for IP’s. They are able to operate in place of the Intended Parent in most
  • Surrogate/Donor (surrogate): The surrogate or donor are interchangeable roughly in our system. They are able to view lost wages, create DR’s (if setting enabled), view documents, and sign documents.

4. Application Architecture

The SeedTrust platform is composed of several key components:

  • seedtrust_cli: The CLI is used for running the app, and keeping databases organized.
    • Location: seedtrust_cli/
    • Tech Stack: Python
  • seedtrust_flask (Flask): The Flask application is the primary SeedTrust application and the strategic destination for consolidation. It is used in production by the majority of users. There are several branches hosted for clients including master, overhaul_lite, legacy_master, and seedtrust_lite. Master is the current production, and the others aren’t worked on outside of very necessary changes, but are used in dedicated production environments for clients that don’t want change.
    • Location: seedtrust_flask/
    • Purpose: This houses the frontend and backend that are most used currently. New product work should move toward a simpler Flask-centered application, using Jinja/server-rendered pages, Alpine/HTMX interactions, and JSON APIs for partial data updates where needed.
  • seedtrustapi (FastAPI): Existing API backend for the mobile PWA and integrations.
    • Location: seedtrustapi/
    • Purpose: Maintain current mobile/API behavior while useful flows are backfilled into Flask over time. Do not treat it as the long-term home for new product ownership.
  • app (NextJS): Mobile App Experience.
    • Location: app/
    • Purpose: Currently serves as a mobile experience in the form of a PWA. Maintain it only as needed during Flask consolidation.
  • Database: MySQL with SQLAlchemy
  • External Services:

5. Key Workflows

The main bread and butter of SeedTrust can look like this:

AdminCMOwnerIPSurrogateIP RepCreates Disbursement or Makesa DepositAdmin reviews and decides actionto take. Can be Approve, Deny,or Send to IP/CM for approvalgenerally.When approved, a transaction willbe sent to a paymentsdashboard to be reviewed by apayment adminMarked as Paid by the PaymentAdminMarked as Credit Card goes tocredit card dashboard where itis considered “CC Processing”and marked paid once cleared.Complete at this point.Nacha DashboardNacha File created or releasedby other means.SPC’s are created for casesbased on the contracts andscheduled. SPC’s are createdwhen an Admin runs a pullpayment action

5.1. Case Creation & Onboarding

  1. Admin creates a case prompted generally through external contact methods such as email.
  2. A multi-step form is filled out:
    1. Agency is selected
    2. Agency settings are carried over as defaults generally, but allowed to be customized on this step. Things include the contract to be given to the case, and minimum account balances etc.
    3. Match sheet upload here
    4. Surrogates, IP rep, Case Manager, IPs, are created.
    5. Agency Credit Card information is input here. These are externally created through a service called Divvy. Currently not automated, and is done manually by the admin creating it. Upon submitting this step, the case is created, but not activated.
    6. Information review and activation step.

5.2. Funding the Escrow Account

  1. Funding the account is through deposit notifications. There are external sources that the users have to fund their accounts.
  2. The Funding Instructions are present on the user sites.

5.3. Requesting & Processing a Disbursement

  1. The Disbursement Requests can be submitted by any user technically. Some users have a setting to turn them on or off.
  2. There is a multistep form for submitting a disbursement request:
    1. Date of occurrence; stare and end date.
    2. The fields for a disbursement line item are (Each disbursement batch can have multiple line items):
      1. Payee
      2. Payee Name
      3. Request Type
      4. Amount
      5. Description
      6. Invoice Number
      7. Date of occurrence
      8. Attachments (multi)
    3. Review/Submission step
  3. Once submitted, depending on the settings for a case, a disbursement request will be reviewed by either a CM, IP, or approved by an Admin. An admin can action a disbursement a few different ways. The statuses of a disbursement request are:
    1. Submitted - The initial created status
    2. Pending - “processing”
    3. Denied
    4. Approved
    5. Send for Approval - Sent from the admin to the CM or IP for approval.

6. Data Models

This section outlines the primary data models in the SeedTrust system. This is not all models, but gives a good idea of what is here.

User & Role Models

These models represent the different actors within the system.

  • Admin: Represents a SeedTrust staff member with administrative privileges.
  • AgencyOwner: The primary contact and decision-maker for an agency.
  • CaseManager: An individual from an agency assigned to manage specific cases.
  • IntendedParent (IP): The client(s) who are becoming parents.
  • IPCompany (IP Rep): A representative or company acting on behalf of the Intended Parents.
  • Surrogate: The gestational carrier or egg donor.

Case Management Models

These models are central to organizing and tracking a surrogacy journey.

  • Case: The core model that links all parties (IPs, Surrogate, Agency) and contains all information related to a specific surrogacy journey.
  • Agency: Represents a surrogacy agency that partners with SeedTrust.
  • CaseAdmin, CaseCM, CaseIP, CaseSurrogate: Junction tables that create many-to-many relationships between the Case model and the various user models.
  • CaseNote: Used for internal notes and communication regarding a case.
  • TransactionFiles: Manages files and documents associated with a case, such as contracts and invoices.

Financial Models

These models handle all the financial aspects of the escrow service.

  • LedgerTransaction: Represents a single entry in the case ledger, tracking all debits and credits.
  • DisbursementRequest (DR): A formal request for payment from the escrow account for a specific expense.
  • Compensation: Defines the schedule and amounts for payments to be made to the surrogate as outlined in the GSA (e.g., monthly allowances, milestone payments). Often referred to as SPCs (Scheduled Payment Calendar).
  • MasterACHForm: Securely stores banking and authorization details for all entities (Surrogates, IPs, Vendors, Agencies) for processing electronic payments via the Automated Clearing House (ACH) network.
  • DepositNotification: Tracks incoming funds from Intended Parents that have been reported but not yet verified by an admin. Becomes a LedgerTransaction upon approval.
  • Vendor: Represents third-party entities that receive payments, such as clinics, attorneys, or insurance companies.
  • NachaBatch: A batch of LedgerTransaction records compiled into a file formatted according to Nacha standards for bulk ACH processing.

Communication Models

  • Message: A single message sent within the platform’s messaging system.
  • MessageChain: A collection of messages that form a conversation thread, typically associated with a specific case.