SynapsVault is a decentralised marketplace where creators publish paywalled digital resources — APIs, datasets, documents, and research — secured by x402 Stellar micropayments and Soroban smart contracts. Buyers pay once (or subscribe) and get on-chain proof of access.
This repo is the React/Vite web UI.
Browser (React/Vite)
│ Freighter wallet (Stellar)
│ x402/fetch — payment over HTTP
▼
SynapsVault-backend (Express + Supabase)
│ Stellar Horizon RPC
▼
SynapsVault-contracts (Soroban — vault-registry, access-lease, subscription)
| Layer | Choice |
|---|---|
| Framework | React 18 + TypeScript |
| Build | Vite |
| Styling | Tailwind CSS + custom design system (CSS vars) |
| Wallet | Stellar Freighter via @stellar/freighter-api |
| Payments | x402 protocol via @x402/fetch + @x402/stellar |
| i18n | i18next (English + Español included) |
| Testing | Vitest + React Testing Library |
| Error tracking | Sentry |
| CI | GitHub Actions (lint, typecheck, test, build, Docker smoke test) |
# Prerequisites: Node 20+
git clone https://github.com/SynapsVault/frontend SynapsVault-frontend
cd SynapsVault-frontend
npm install
# Environment
cp .env.example .env
# Edit .env — VITE_API_KEY if you're a publisher. Leave VITE_API_URL empty in dev.
# Run the backend (SynapsVault/backend) on http://localhost:3000, then:
npm run dev # http://localhost:5173 (API routes are proxied to the backend)
npm run lint # ESLint (typescript-eslint + react-hooks)
npm run typecheck # type checking
npm run test # unit tests
npm run build # production build → dist/
npm run check # everything CI runs: lint, typecheck, test, build + bundle budgetsdocker build \
--build-arg VITE_API_URL=https://api.yourdomain.com \
--build-arg VITE_NETWORK=mainnet \
-t synapsvault-frontend .
docker run -p 8080:80 synapsvault-frontend| Variable | Required | Description |
|---|---|---|
VITE_API_URL |
Production | Backend API base URL. Leave empty in development: the dev server proxies all API routes to VITE_DEV_PROXY_TARGET (default http://localhost:3000). Must be set for production builds, or API calls return the app's HTML. |
VITE_DEV_PROXY_TARGET |
❌ | Backend the dev server proxies to (default http://localhost:3000) |
VITE_API_KEY |
Publisher only | API key for creator features |
Security warning:
VITE_API_KEYis bundled into client-side JavaScript and is visible to every visitor. Do not use it for a secret publisher credential. |VITE_NETWORK| ✅ |testnetormainnet: payments, signing, explorer links | |VITE_SENTRY_DSN| ❌ | Sentry DSN for error tracking |
See CONTRIBUTING.md for the full branch strategy and commit format.
Every push to main or dev, and every PR targeting those branches, runs three jobs: lint + typecheck + test, build + bundle
budgets (initial JS ≤ 250 KB gz, any chunk ≤ 800 KB gz, total ≤ 1 MB gz, and no
circular chunk imports — see scripts/check-bundle-size.mjs), and a Docker
smoke test that boots nginx and checks /health and SPA routing.
Push to main/dev or PR to main/dev ──► CI (lint + typecheck + test + build + docker)
Token-driven (primitive scales → semantic tokens → components) with first-class
light and dark themes, WCAG AA contrast, and reduced-motion support. Tokens live
in src/styles/tokens.css and are exposed to Tailwind
as semantic classes (bg-surface, text-fg-muted, border-line, bg-accent, …).
See DESIGN_SYSTEM.md for the full reference.
Press ? in the app for the full list. Highlights: / search, 1–6 switch tabs, T toggle theme, L switch language, Esc close dialogs.
| Tab | Description |
|---|---|
| Catalog | Browse + search + filter all listed resources |
| My Vault | Creator dashboard — manage, price, register your resources |
| Analytics | Revenue charts, access counts, payment history |
| Purchases | All resources you've bought |
| Leaderboard | Top publishers by revenue |
| Agent | AI agent status and live reasoning feed |
| Repo | Description |
|---|---|
| SynapsVault-backend | Express API + Supabase |
| SynapsVault-contracts | Soroban smart contracts |
MIT © 2025 Busiii-adetiba