Skip to content
SeedTrust Docs

SeedTrust Docs

Fintech platform for managing escrow accounts in surrogacy and egg donation journeys.
Get Started Architecture Review

SeedTrust handles case management, payment workflows, ACH disbursements, document signing, and communication between Intended Parents, Surrogates, Case Managers, and Agencies.

The Platform

Three services run in production today, but the strategic target is one application:

ServicePurposeStatus
seedtrust_flaskPrimary Flask application — admin UI, NACHA batches, reports, case management, and the destination for consolidated product workStrategic home
seedtrustapiFastAPI backend — mobile API and Huntington paymentsMaintain while backfilling into Flask
appMobile PWA (Next.js) — interface for IPs, Surrogates, CMs, and AgenciesMaintain only as needed during Flask consolidation
new-stGo/SvelteKit shell/experiment around admin flowsNot the strategic target

Both Python backends share a single MySQL database today. New product work should move SeedTrust toward seedtrust_flask as the only application. The architectural goal is simplicity: fewer codebases, fewer auth systems, and a simpler Flask-centered stack using server-rendered pages, Alpine/HTMX interactions, and JSON APIs that feed partials where dynamic data is needed. See ADR 003.

Where to Start

New to the codebase? Follow the Recommended Reading Order below.

Looking for something specific?

I want to…Go here
Understand the domain languageBusiness Glossary
Set up my dev environmentGetting Started
Understand user roles and permissionsUser Roles · Auth & Permissions
Add a new API endpointMigration Guide
Understand how payments workDisbursement Requests · ACH & Banking
Generate an ACH batchACH Batch Generation Runbook
Add a new admin permissionAdding Permissions Runbook
Understand why something was built this wayArchitecture Decisions

These docs are written to be read in sequence. Each one builds on the one before it.

Foundation (start here)

  1. Business Glossary — The domain vocabulary. Learn what “DR”, “SPC”, “IP”, “GSA”, and “escrow agreement” mean before reading anything else.
  2. User Roles — The six user types and the 122-permission admin RBAC system.
  3. Getting Started — Run the full stack locally with one command.
  4. Architecture Review — The system map. Shows how all three services connect and what each owns.

Core Business Logic

  1. Authentication & Permissions — Three auth systems (Flask session, FastAPI JWT, NextAuth). Required context before touching any route.
  2. Case Lifecycle — The central business object. Cases are the glue between all parties, all payments, and all documents.
  3. Disbursement Requests — The most complex workflow. Payment requests with a 7-step state machine, multi-party approval, and auto-approval rules.
  4. Ledger & Transactions — How money is recorded. Append-only ledger, running account balance, transaction types and statuses.
  5. ACH & Banking — How money moves out. Two parallel payment paths: NACHA/M&T (non-CA) and Huntington API (CA/TX).
  6. Scheduled Payments — Contract-based payment calendar (SPC). How recurring payments are generated, modified, and paid.

Supporting Systems

  1. Document Management — S3 file storage, signed URLs, escrow agreement signing, access control.
  2. Messaging & Notifications — In-platform inbox, push, email (SendGrid), and SMS (Twilio).
  3. Background Jobs — Flask cron jobs and the Huey worker. What runs without a user and what breaks if they stop.
  4. Reporting — Flask report endpoints, async report generation, PostHog analytics.

Frontend

  1. Next.js App Overview — Route structure, component organization, global state, PWA config.
  2. API Integration — When to use fetchWrapper vs axiosClient, React Query patterns, S3 direct upload flow.

Context & Decisions

  1. Migration Guide — Which service to build in, decision tree for Flask consolidation, step-by-step migration pattern.
  2. ADR 001: FastAPI Alongside Flask — Why a second backend was built instead of extending Flask.
  3. ADR 002: Huntington for CA/TX — Why California and Texas cases use a different payment path.
  4. ADR 003: Consolidate on Flask — Why the plan changed from the Go/SvelteKit rewrite to one simpler Flask application.

Runbooks (reference as needed)

  • ACH Batch Generation — Step-by-step: approve ACH forms, generate a batch, deliver to M&T or Huntington, handle failures.
  • Adding a Permission — Step-by-step: add to the Permission class, sync the DB, assign to roles, protect a route.

Key Concepts at a Glance

TermMeaning
Case (ip_case)A surrogacy or egg donation journey, linking IP, surrogate, and agency
DRDisbursement Request — a payment request requiring multi-party approval
SPCScheduled Payment Calendar — contract-defined recurring payments
GSAGestational Surrogacy Agreement — the signed legal contract
Escrow AgreementFinancial management contract, signed in-app before payments begin
NACHAFile-based ACH format used for M&T Bank (non-CA/TX cases)
HuntingtonDirect API payment integration for CA and TX IPs
HueyFastAPI background task queue (Redis in production, SQLite locally)

See the full Business Glossary for all terms.