name: agicash-wallet-architecture description: Agicash wallet system architecture — components, their responsibilities, and interactions. Use when working on cross-component concerns like server routes, client-server communication, Open Secret integration, encryption/decryption flows, Supabase Realtime subscriptions, or when deciding where new functionality should live (server vs client). Also use when modifying Lightning Address routes, SSR behavior, or database access patterns.

Agicash Wallet Architecture

Read docs/architecture.md for the full architecture overview with diagrams.

Four components — understand their boundaries before making changes:

Component	Responsibility	Key constraint
Server (Vercel)	Serves client code, handles offline requests (Lightning Address, Sentry tunnel, PWA manifest)	Cannot access Open Secret — no seeds, no encryption keys
Client (Browser)	Runs the wallet — auth, wallet init, encrypt/decrypt, read/write DB	All sensitive operations happen here
Open Secret (AWS Nitro Enclave)	Stores auth, seeds, mnemonics, encryption keys	Data only accessible after user authentication
Postgres DB (Supabase)	Stores wallet data with RLS	Sensitive data stored encrypted, each user reads only their own

Adding a new server route or API endpoint — check what the server can and cannot access (no Open Secret, only non-sensitive DB data via service role key)
Working with encryption/decryption — understand the client-side-only encryption model and why the server cannot decrypt
Modifying auth or key derivation — understand the Open Secret → Supabase JWT flow
Adding or changing Realtime subscriptions — understand the client ↔ DB realtime pattern
Deciding server vs client for new functionality — the architecture doc clarifies the boundary: if it needs seeds, keys, or decrypted data, it must be client-side