Stellar Remittance Platform

A cross-border remittance application built on the Stellar blockchain, enabling fast and low-cost international money transfers.

This repository includes both frontend and backend services for building a Stellar payment experience.

Features

• Create Stellar accounts
• Check account balances
• Send XLM payments
• Low transaction fees (~$0.00001)
• Fast settlement (3-5 seconds)

Tech Stack

• Backend: Node.js + Express + Stellar SDK
• Frontend: React + Vite
• Blockchain: Stellar (Testnet)

Setup

1. Install dependencies:

npm install

2. Configure backend environment:

cd backend
cp .env.example .env

See backend/CONFIGURATION.md for environment options, validation rules, and optional encrypted secrets.

3. Configure frontend environment (optional):

cd frontend
cp .env.example .env

Set VITE_API_URL to your production API endpoint when deploying to a CDN or different domain. Leave empty for development (Vite proxy handles /api requests to localhost:3001).

4. Start development servers:

npm run dev

Backend runs on http://localhost:3001 Frontend runs on http://localhost:3000

Docker (recommended for local development)

Docker Compose spins up the full stack — PostgreSQL, Redis, backend, and frontend — with a single command. No local database installation required.

Start

docker compose up --build

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• PostgreSQL: localhost:5432 (user future_admin, db future_remittance, password dev_password)
• Redis: localhost:6379

Prisma migrations run automatically on backend startup. Source directories are bind-mounted so the backend (node --watch) and frontend (Vite HMR) both hot-reload on file changes.

Stop

docker compose down          # stop containers, keep the db volume
docker compose down -v       # stop and delete the db volume

Local overrides

To customise ports, credentials, or log levels without editing the shared file:

cp docker-compose.override.yml.example docker-compose.override.yml
# edit docker-compose.override.yml — it is git-ignored
docker compose up --build

Service communication

From	To	Address
backend	postgres	postgres:5432
backend	redis	redis:6379
frontend (Vite proxy)	backend	http://backend:3001
browser	frontend	http://localhost:3000
browser	backend	http://localhost:3001

Dev Container / GitHub Codespaces

The repository includes a ready-to-use .devcontainer/ configuration — no local Node, PostgreSQL, or Redis install required. Open the repo in a GitHub Codespace, or locally in VS Code with the Dev Containers extension and choose Reopen in Container.

This is a separate setup from the root docker-compose.yml described above: .devcontainer/docker-compose.yml builds the environment you develop inside (your editor runs in the devcontainer service, with the repo mounted as its workspace), whereas the root docker-compose.yml runs the app's own services (backend, frontend, postgres, redis) as containers you'd otherwise start from a normal host. Use the dev container when you want a fully provisioned environment with zero local installs; use the root docker-compose.yml if you already have Node installed locally and just want the app's dependent services.

What happens automatically:

• On container creation (postCreateCommand, see .devcontainer/post-create.sh): installs dependencies for the root workspace, backend/, and frontend/, then copies backend/.env.example → backend/.env and frontend/.env.example → frontend/.env if they don't already exist.
• On container start (postStartCommand): runs npx prisma migrate deploy against the containerized Postgres.

Forwarded ports:

Port	Service
3000	Frontend (Vite)
3001	Backend (Express)
6006	Storybook
5432	PostgreSQL
6379	Redis

The container also comes with ESLint, Prettier, TypeScript, Prisma, and GitLens extensions pre-installed (see customizations.vscode.extensions in devcontainer.json for the full list). Once it's running, start the dev servers the same way as any other setup: npm run dev.

Usage

1. Click "Create Account" to generate a new Stellar keypair
2. Account is automatically funded on testnet via Friendbot
3. Check balance to see your XLM
4. Send payments to other Stellar addresses

Testnet Setup

Friendbot

Friendbot is Stellar's automated account-funding service for the testnet. It credits any new (or unfunded) Stellar public key with 10,000 test XLM at no cost, letting you start testing payments immediately without real funds.

Fund an account via the API directly:

curl "https://friendbot.stellar.org/?addr=YOUR_PUBLIC_KEY"

Or use the bundled helper script (see scripts/fund-testnet-account.sh):

bash scripts/fund-testnet-account.sh GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGZWM9CQJHD9QDNHXHXN

The app calls Friendbot automatically when you click Create Account in the UI.

Testnet Limitations

• Quarterly resets — the Stellar testnet is wiped roughly every three months. All accounts, balances, and transaction history are deleted. You must re-fund accounts after each reset.
• Test XLM has no monetary value and cannot be transferred to mainnet.
• Friendbot is only available on testnet; it does not exist on mainnet.

Testnet vs. Mainnet Configuration

Setting	Testnet	Mainnet
STELLAR_NETWORK	testnet	mainnet
HORIZON_URL	https://horizon-testnet.stellar.org	https://horizon.stellar.org
Network passphrase	Test SDF Network ; September 2015	Public Global Stellar Network ; September 2015
Friendbot available	✅ Yes	❌ No
Real funds	❌ No	✅ Yes

Set STELLAR_NETWORK=testnet (the default) in backend/.env for local development. Change to mainnet only for production deployments.

Hitting a Horizon error while testing payments (tx_bad_seq, op_underfunded, op_no_trust, etc.)? See docs/guides/stellar-errors.md for what each one means and how to fix it.

Next Steps

• Add stablecoin support (USDC)
• Integrate fiat on/off ramps
• Add exchange rate conversion
• Implement KYC/AML compliance
• Add transaction history
• Mobile app development

Architecture

See docs/architecture.md for the full system diagram, component descriptions, payment flow walkthrough, and deployment topology.

Guides

• Documentation index — full map of every guide, ADR, and reference doc in this repo — start here
• Troubleshooting — fixes for common local dev failures: port conflicts, Prisma migration/drift errors, Friendbot rate-limiting, npm workspace resets, env misconfiguration
• Security best practices for integrators — API key storage, webhook verification, private key management, CSP, replay attacks, front-running
• Stellar / Horizon error reference — common error codes (sequence numbers, minimum reserve, trustlines) and how to fix them
• Dependency upgrade guide — checklists for upgrading @stellar/stellar-sdk, Prisma, and React/Vite
• Operational Runbook — Server restart, DB migration rollback, stream cancellation, IP unblock, incident response
• Incident Runbooks — Horizon outage, DB failover, JWT secret rotation, stuck transaction recovery
• scripts/README.md — what each script in scripts/ does and when to run it

Contributing

See CONTRIBUTING.md for local setup, running tests, branch naming, PR process, code style, and commit message conventions.

Found a security vulnerability? See SECURITY.md for how to report it privately.

Architecture Decision Records

Key technology choices are documented as ADRs in docs/adr/:

ADR	Decision
ADR-0001	Stellar as the blockchain layer
ADR-0002	Prisma as the ORM
ADR-0003	Multi-level caching (in-memory L1 + Redis L2)
ADR-0004	JWT auth with refresh token rotation
ADR-0005	npm workspaces monorepo structure

Resources

• Glossary — Stellar and remittance/compliance terms used in this codebase
• Stellar Documentation
• Stellar SDK