agicash-wallet-architecture
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.
Installation
Follow the repository instructions for this skill and your agent. Review the files and dependencies before adding it to your workflow.
View source ↗GuidesSkill instructions
Agicash Wallet Architecture
Read docs/architecture.md for the full architecture overview with diagrams.
Component Summary
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 |
When to Consult the Architecture Doc
- 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
Examples
Read the usage examples in the source repository.
View source ↗Source history
- Indexed on
- 2026-03-11
- Index updated
- 2026-03-11
- Branch
- main
Index and sync dates describe this directory. View the source repository for code history.
GitHub ↗chat Comments (0)
Sign in to join the discussion and leave a comment.
No comments yet. Be the first to share your thoughts!