Boytel

Your inbox. Your rules. Proof for every delivery.

Boytel is the web client for a private, programmable mail protocol built on Stellar. You decide who can reach you, what unknown senders must pay, and which delivery claims deserve trust.

This repository contains the frontend only. The API, relay, and protocol services live in Stellar-Mail/boytel-backend. Both repositories share the complete history of the original project.

Features

• Access is earned. Allow, block, or price unknown senders before they enter your inbox.
• Identity is verifiable. Stellar accounts and federation addresses give senders cryptographic identities instead of display-name trust.
• Spam has a cost. Optional micro-postage turns bulk abuse from free into economically measurable.
• Delivery has proof. Message hashes, postage proofs, and receipts create an auditable delivery trail without putting private message bodies on-chain.
• Messages stay private. Encrypted payloads remain off-chain; Stellar anchors identity, policy, payment references, and proof.

Stack

• React 19 + TanStack Start + TanStack Router on Vite
• Tailwind CSS 4, Radix UI, and Framer Motion for the design system
• Client-side cryptography for sealed messages (see src/services/crypto)
• Playwright for end-to-end and visual testing; Vitest for unit tests

Getting Started

Requirements: Node 24+, Bun 1.3.14.

bun install
bun run dev

The dev server starts on http://localhost:5173 with a built-in mock API (scripts/dev/mock-api.mjs), so the full UI — sign-in, onboarding, mailbox, settings — runs standalone with demo data. No backend required.

To run against a real API instead, start the boytel-backend dev server and point the client at it:

# .env.local
VITE_API_BASE_URL=http://localhost:5174

With VITE_API_BASE_URL set, the dev server proxies /api and /relays to that origin. In production, route /api and /relays to the backend with your reverse proxy or CDN.

Development

bun run dev             # dev server with mock API
bun run build           # production build
bun run preview         # preview the production build
bun run lint            # ESLint
bun run format:check    # Prettier
bun x tsc --noEmit      # typecheck
bun run test            # unit tests (Vitest)
bun run test:e2e        # end-to-end tests (Playwright)
bun run test:visual     # visual regression tests
bun run generate:route-tree  # regenerate src/routeTree.gen.ts

Project Layout

src/
  components/     # UI components (mail, compose, landing, design system)
  features/       # Feature modules (compose, identity, mailbox, settings, …)
  routes/         # TanStack file routes (pages)
  hooks/          # Shared React hooks
  lib/            # API client, DTOs, and utilities
  services/       # Client-side services (crypto, attachments, Stellar wallet)
scripts/
  dev/            # Dev-server tooling (mock API)
tests/
  unit/           # Vitest suites
  e2e/            # Playwright end-to-end and visual suites

Contributing

See CONTRIBUTING.md for pull request and review requirements.

Security

Report vulnerabilities through GitHub private vulnerability reporting. Never open a public issue with exploit details, credentials, wallet seeds, or message content.

License

Private. All rights reserved.