# seyfert-labs/seyf-p architecture

> Architecture diagram of the GitHub repository seyfert-labs/seyf-p, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seyfert-labs/seyf-p
- Repository: https://github.com/seyfert-labs/seyf-p

## Overview

SEYF is a Spanish-language savings app on Stellar: users sign in with Pollar, establish a sponsored USDC-capable account, save through a DeFindex vault, and may borrow against future vault yield through the Soroban advance contract. The repository also includes Etherfuse KYC/onramp flows and exchange/conversion functionality. README statements support the principal transaction flow; sampled imports support selected internal calls. Most API route implementations and contract entrypoints were not sampled, so broader links are documented relationships rather than claims about unseen code.

Main entry points: [`src/lib/pollar/client-api.ts`](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/pollar/client-api.ts) (Pollar wallet), [`soroban/seyf_advance/src/lib.rs`](https://github.com/seyfert-labs/seyf-p/blob/meridian/soroban/seyf_advance/src/lib.rs) (Advance contract), [`src/app/app/page.tsx`](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/app/page.tsx) (App screens), [`src/app/api/convert/route.ts`](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/convert/route.ts) (Conversion route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Savings app"]
  node_appui["App screens<br/>[page.tsx]"]
  node_appdata["App data<br/>[data.ts]"]
  node_retiroctx["Retiro context<br/>[RetiroContext.tsx]"]
end

subgraph group_identity["Identity and wallet"]
  node_wallet["Pollar wallet<br/>[client-api.ts]"]
  node_pollar["Pollar service"]
  node_sep10["SEP-10 auth<br/>[route.ts]"]
  node_sep10client["SEP-10 client<br/>[sep10-client.ts]"]
  node_sponsor["Sponsored account"]
end

subgraph group_onchain["Stellar savings"]
  node_stellar["Stellar network<br/>[network.ts]"]
  node_vaultui["Vault management"]
  node_vaultapi["DeFindex routes"]
  node_defindex[("DeFindex vault")]
  node_blend[("Blend pool")]
end

subgraph group_advance["Yield advance"]
  node_advanceui["Advance experience<br/>[useAdvance.ts]"]
  node_advanceapi["Advance routes"]
  node_contract["Advance contract<br/>[lib.rs]"]
  node_contractstate[("Contract storage<br/>[storage.rs]")]
end

subgraph group_integrations["Financial integrations"]
  node_etherfusekyc["Etherfuse KYC<br/>[route.ts]"]
  node_etherfuse["Etherfuse service<br/>[client.ts]"]
  node_etherwebhook["Deposit webhook<br/>[route.ts]"]
  node_supabase[("Supabase metadata<br/>[db.ts]")]
  node_convert["Conversion route<br/>[route.ts]"]
  node_bitso["Bitso exchange"]
  node_juno["Juno payments"]
end

node_saver(("Saver"))
node_keeper(("Keeper"))

node_saver -->|"uses"| node_appui
node_appui -.->|"signs in"| node_wallet
node_wallet -->|"creates wallet"| node_pollar
node_wallet -.->|"authenticates"| node_sep10
node_sep10 -->|"uses"| node_sep10client
node_sep10client -->|"requests signing"| node_pollar
node_appui -.->|"reads state"| node_retiroctx
node_retiroctx -->|"resolves network"| node_stellar
node_wallet -->|"signs transactions"| node_sponsor
node_sponsor -->|"submits fee-bump"| node_stellar
node_appdata -->|"stores metadata"| node_supabase
node_vaultui -->|"requests positions"| node_vaultapi
node_vaultapi -->|"builds vault transactions"| node_defindex
node_defindex -->|"supplies assets"| node_blend
node_wallet -->|"deposits USDC"| node_defindex
node_appui -.->|"opens advance"| node_advanceui
node_advanceui -.->|"requests quote"| node_advanceapi
node_advanceapi -->|"builds transactions"| node_contract
node_contract -.->|"reads and writes"| node_contractstate
node_contract -->|"locks vault shares"| node_defindex
node_contract -->|"pays advance"| node_wallet
node_keeper -->|"settles advances"| node_contract
node_saver -.->|"submits KYC"| node_etherfusekyc
node_etherfusekyc -->|"submits identity"| node_etherfuse
node_etherwebhook -->|"updates KYC state"| node_supabase
node_etherwebhook -->|"checks order details"| node_etherfuse
node_convert -->|"reserves ledger entry"| node_supabase
node_convert -->|"places order"| node_bitso
node_convert -->|"issues MXNB"| node_juno

click node_appui "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/app/page.tsx"
click node_appdata "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/components/app/data.ts"
click node_retiroctx "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/components/app/RetiroContext.tsx"
click node_wallet "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/pollar/client-api.ts"
click node_sep10 "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/auth/sep10/route.ts"
click node_sep10client "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/stellar/sep10-client.ts"
click node_sponsor "https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/stellar/sponsor"
click node_stellar "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/stellar/network.ts"
click node_vaultui "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/hooks/useStellarVaults.ts"
click node_vaultapi "https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/defindex"
click node_advanceui "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/hooks/useAdvance.ts"
click node_advanceapi "https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/advance"
click node_contract "https://github.com/seyfert-labs/seyf-p/blob/meridian/soroban/seyf_advance/src/lib.rs"
click node_contractstate "https://github.com/seyfert-labs/seyf-p/blob/meridian/soroban/seyf_advance/src/storage.rs"
click node_etherfusekyc "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/seyf/kyc/submit/route.ts"
click node_etherfuse "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/etherfuse/client.ts"
click node_etherwebhook "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/webhooks/etherfuse/route.ts"
click node_supabase "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/supabase/db.ts"
click node_convert "https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/convert/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_appui,node_appdata,node_retiroctx toneBlue
class node_wallet,node_pollar,node_sep10,node_sep10client,node_sponsor toneAmber
class node_stellar,node_vaultui,node_vaultapi,node_defindex,node_blend toneMint
class node_advanceui,node_advanceapi,node_contract,node_contractstate toneRose
class node_etherfusekyc,node_etherfuse,node_etherwebhook,node_supabase,node_convert,node_bitso,node_juno,node_saver,node_keeper toneIndigo
```

## Components

### Savings app

- [App screens](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/app/page.tsx): `src/app/app/page.tsx`
- [App data](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/components/app/data.ts): `src/components/app/data.ts`
- [Retiro context](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/components/app/RetiroContext.tsx): `src/components/app/RetiroContext.tsx`

### Identity and wallet

- [Pollar wallet](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/pollar/client-api.ts): `src/lib/pollar/client-api.ts`
- **Pollar service**
- [SEP-10 auth](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/auth/sep10/route.ts): `src/app/api/auth/sep10/route.ts`
- [SEP-10 client](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/stellar/sep10-client.ts): `src/lib/stellar/sep10-client.ts`
- [Sponsored account](https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/stellar/sponsor): `src/app/api/stellar/sponsor`

### Stellar savings

- [Stellar network](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/stellar/network.ts): `src/lib/stellar/network.ts`
- [Vault management](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/hooks/useStellarVaults.ts): `src/hooks/useStellarVaults.ts`
- [DeFindex routes](https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/defindex): `src/app/api/defindex`
- **DeFindex vault**
- **Blend pool**

### Yield advance

- [Advance experience](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/hooks/useAdvance.ts): `src/hooks/useAdvance.ts`
- [Advance routes](https://github.com/seyfert-labs/seyf-p/tree/meridian/src/app/api/advance): `src/app/api/advance`
- [Advance contract](https://github.com/seyfert-labs/seyf-p/blob/meridian/soroban/seyf_advance/src/lib.rs): `soroban/seyf_advance/src/lib.rs`
- [Contract storage](https://github.com/seyfert-labs/seyf-p/blob/meridian/soroban/seyf_advance/src/storage.rs): `soroban/seyf_advance/src/storage.rs`

### Financial integrations

- [Etherfuse KYC](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/seyf/kyc/submit/route.ts): `src/app/api/seyf/kyc/submit/route.ts`
- [Etherfuse service](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/etherfuse/client.ts): `src/lib/etherfuse/client.ts`
- [Deposit webhook](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/webhooks/etherfuse/route.ts): `src/app/api/webhooks/etherfuse/route.ts`
- [Supabase metadata](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/lib/supabase/db.ts): `src/lib/supabase/db.ts`
- [Conversion route](https://github.com/seyfert-labs/seyf-p/blob/meridian/src/app/api/convert/route.ts): `src/app/api/convert/route.ts`
- **Bitso exchange**
- **Juno payments**

### Other components

- **Saver**
- **Keeper**

## Connections

- Saver → App screens: uses (evidence: `README.md`)
- App screens → Pollar wallet: signs in
- Pollar wallet → Pollar service: creates wallet (evidence: `README.md`)
- Pollar wallet → SEP-10 auth: authenticates
- SEP-10 auth → SEP-10 client: uses (evidence: `src/app/api/auth/sep10/route.ts`)
- SEP-10 client → Pollar service: requests signing (evidence: `src/lib/stellar/sep10-client.ts`)
- App screens → Retiro context: reads state
- Retiro context → Stellar network: resolves network (evidence: `src/components/app/RetiroContext.tsx`)
- Pollar wallet → Sponsored account: signs transactions (evidence: `README.md`)
- Sponsored account → Stellar network: submits fee-bump (evidence: `README.md`)
- App data → Supabase metadata: stores metadata (evidence: `src/components/app/data.ts`)
- Vault management → DeFindex routes: requests positions (evidence: `src/hooks/useStellarVaults.ts`)
- DeFindex routes → DeFindex vault: builds vault transactions (evidence: `README.md`)
- DeFindex vault → Blend pool: supplies assets (evidence: `README.md`)
- Pollar wallet → DeFindex vault: deposits USDC (evidence: `README.md`)
- App screens → Advance experience: opens advance
- Advance experience → Advance routes: requests quote
- Advance routes → Advance contract: builds transactions (evidence: `README.md`)
- Advance contract → Contract storage: reads and writes
- Advance contract → DeFindex vault: locks vault shares (evidence: `README.md`)
- Advance contract → Pollar wallet: pays advance (evidence: `README.md`)
- Keeper → Advance contract: settles advances (evidence: `README.md`)
- Saver → Etherfuse KYC: submits KYC
- Etherfuse KYC → Etherfuse service: submits identity (evidence: `src/app/api/seyf/kyc/submit/route.ts`)
- Deposit webhook → Supabase metadata: updates KYC state (evidence: `src/app/api/webhooks/etherfuse/route.ts`)
- Deposit webhook → Etherfuse service: checks order details (evidence: `src/app/api/webhooks/etherfuse/route.ts`)
- Conversion route → Supabase metadata: reserves ledger entry (evidence: `src/app/api/convert/route.ts`)
- Conversion route → Bitso exchange: places order (evidence: `src/app/api/convert/route.ts`)
- Conversion route → Juno payments: issues MXNB (evidence: `src/app/api/convert/route.ts`)
