# alanriouss/tripvault architecture

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

- Interactive diagram: https://gitdiagram.com/alanriouss/tripvault
- Repository: https://github.com/alanriouss/tripvault

## Overview

TripVault is a shared-trip expense and time-locked USDC settlement app. Members create or join a trip, record and review external VND bills, fund a shared vault, then settle net balances after the trip. The graph separates trip collaboration, bill accounting, wallet/vault operations, and server state. Source excerpts show server setup, persistence, and math delegation; README statements support the broader product flow. Some UI-to-server and wallet-to-chain wiring is documented but not visible in the sampled calls.

Main entry points: [`work/tripvault-room-bill-ui.js`](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-bill-ui.js) (Bill review UI), [`work/tripvault-rooms-ui.js`](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-rooms-ui.js) (Trip workspace UI), [`packages/server/src/api.js`](https://github.com/alanriouss/tripvault/blob/main/packages/server/src/api.js) (Room API), [`work/tripvault-room-server/server.js`](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-server/server.js) (Room server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collab["Trip collaboration"]
  node_trip_ui["Trip workspace UI"]
  node_invite["Invite codes"]
  node_room_api["Room API<br/>[api.js]"]
  node_demo_ui["Local demo mode"]
end

subgraph group_accounting["Bills and balances"]
  node_bill_ui["Bill review UI"]
  node_bill_events["Bill notifications"]
  node_balance_math["Split and settlement math<br/>[math.js]"]
  node_funding_calc["Funding shortfalls"]
  node_vnd_records["External VND bills"]
end

subgraph group_vault["Wallet and vault"]
  node_funding_ui["Funding controls"]
  node_fuji_ui["Fuji vault panel"]
  node_vault_contract["Trip vault contract<br/>[TripVaultFuji.sol]"]
end

subgraph group_runtime["App runtime"]
  node_room_store[("Room database<br/>[server.js]")]
  node_room_server["Room server<br/>[server.js]"]
end

node_member(("Trip members"))
node_fuji_network{{"Avalanche Fuji"}}
node_wallet(("Member wallet"))

node_member -.->|"uses"| node_trip_ui
node_trip_ui -.->|"creates or joins"| node_invite
node_trip_ui -.->|"requests rooms"| node_room_api
node_room_server -->|"creates API"| node_room_api
node_room_server -->|"opens database"| node_room_store
node_member -.->|"records and reviews"| node_bill_ui
node_bill_ui -.->|"records expenses"| node_vnd_records
node_bill_events -.->|"notifies about bills"| node_bill_ui
node_room_api -->|"calculates shortfalls"| node_balance_math
node_member -.->|"deposits USDC"| node_funding_ui
node_funding_ui -.->|"checks funding"| node_funding_calc
node_member -.->|"manages vault"| node_fuji_ui
node_fuji_ui -.->|"uses vault"| node_vault_contract
node_wallet -.->|"signs transactions"| node_fuji_network
node_vault_contract -.->|"runs on"| node_fuji_network
node_member -.->|"tries simulation"| node_demo_ui
node_bill_ui -.->|"uses split logic"| node_balance_math

click node_trip_ui "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-rooms-ui.js"
click node_invite "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-rooms-ui.js"
click node_room_api "https://github.com/alanriouss/tripvault/blob/main/packages/server/src/api.js"
click node_room_store "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-server/server.js"
click node_bill_ui "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-bill-ui.js"
click node_bill_events "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-notifications.js"
click node_balance_math "https://github.com/alanriouss/tripvault/blob/main/packages/core/src/math.js"
click node_funding_ui "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-funding-ui.js"
click node_funding_calc "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-funding.js"
click node_fuji_ui "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-fuji-panel.js"
click node_vault_contract "https://github.com/alanriouss/tripvault/blob/main/work/fuji-contract/src/TripVaultFuji.sol"
click node_demo_ui "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-demo-ui.js"
click node_room_server "https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-server/server.js"

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_trip_ui,node_invite,node_room_api,node_demo_ui toneBlue
class node_bill_ui,node_bill_events,node_balance_math,node_funding_calc,node_vnd_records toneAmber
class node_funding_ui,node_fuji_ui,node_vault_contract toneMint
class node_room_store,node_room_server toneRose
class node_member,node_fuji_network,node_wallet toneIndigo
```

## Components

### Trip collaboration

- [Trip workspace UI](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-rooms-ui.js): `work/tripvault-rooms-ui.js`
- [Invite codes](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-rooms-ui.js): `work/tripvault-rooms-ui.js`
- [Room API](https://github.com/alanriouss/tripvault/blob/main/packages/server/src/api.js): `packages/server/src/api.js`
- [Local demo mode](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-demo-ui.js): `work/tripvault-demo-ui.js`

### Bills and balances

- [Bill review UI](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-bill-ui.js): `work/tripvault-room-bill-ui.js`
- [Bill notifications](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-notifications.js): `work/tripvault-room-notifications.js`
- [Split and settlement math](https://github.com/alanriouss/tripvault/blob/main/packages/core/src/math.js): `packages/core/src/math.js`
- [Funding shortfalls](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-funding.js): `work/tripvault-room-funding.js`
- **External VND bills**

### Wallet and vault

- [Funding controls](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-funding-ui.js): `work/tripvault-room-funding-ui.js`
- [Fuji vault panel](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-fuji-panel.js): `work/tripvault-room-fuji-panel.js`
- [Trip vault contract](https://github.com/alanriouss/tripvault/blob/main/work/fuji-contract/src/TripVaultFuji.sol): `work/fuji-contract/src/TripVaultFuji.sol`

### App runtime

- [Room database](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-server/server.js): `work/tripvault-room-server/server.js`
- [Room server](https://github.com/alanriouss/tripvault/blob/main/work/tripvault-room-server/server.js): `work/tripvault-room-server/server.js`

### Other components

- **Trip members**
- **Avalanche Fuji**
- **Member wallet**

## Connections

- Trip members → Trip workspace UI: uses (evidence: `README.md`)
- Trip workspace UI → Invite codes: creates or joins (evidence: `README.md`)
- Trip workspace UI → Room API: requests rooms (evidence: `README.md`)
- Room server → Room API: creates API (evidence: `work/tripvault-room-server/server.js`)
- Room server → Room database: opens database (evidence: `work/tripvault-room-server/server.js`)
- Trip members → Bill review UI: records and reviews (evidence: `README.md`)
- Bill review UI → External VND bills: records expenses (evidence: `README.md`)
- Bill notifications → Bill review UI: notifies about bills (evidence: `README.md`)
- Room API → Split and settlement math: calculates shortfalls (evidence: `packages/server/src/api.js`)
- Trip members → Funding controls: deposits USDC (evidence: `README.md`)
- Funding controls → Funding shortfalls: checks funding
- Trip members → Fuji vault panel: manages vault (evidence: `README.md`)
- Fuji vault panel → Trip vault contract: uses vault (evidence: `README.md`)
- Member wallet → Avalanche Fuji: signs transactions (evidence: `README.md`)
- Trip vault contract → Avalanche Fuji: runs on (evidence: `README.md`)
- Trip members → Local demo mode: tries simulation (evidence: `README.md`)
- Bill review UI → Split and settlement math: uses split logic
