Contributing Guidelines

How to contribute to Sovran - code standards, architecture, and workflow

Before You Code

Read .cursor/rules/ docs before touching their domains. The index is .cursor/rules/rules-index-authoring-guide.mdc.

Domain	Read First
Popups, toasts, sheets	.cursor/rules/popup-toast-sheet-guidelines.mdc
Mnemonic, keys, secure storage	.cursor/rules/secure-storage-key-derivation.mdc
Text component, fonts, skeletons	.cursor/rules/text-typography-skeleton-guidelines.mdc
Theme, colors, tokens	.cursor/rules/theme-system-architecture.mdc
Zustand stores, profile scope	.cursor/rules/zustand-store-scoping.mdc
Git, commits, PRs, issues	.cursor/rules/git-github-workflow.mdc

If the domain you need isn’t documented, check if an existing rule doc covers it partially before creating a new one.

Execution Sequence

1. Search First

   Find existing patterns in components/, hooks/, helper/ before creating anything new. Investigate deeply. Be 100% sure before implementing.

2. Reuse First

   Extend existing functions, hooks, components. Make the smallest possible change.

3. No Assumptions

   Only use: files you’ve read, user messages, tool results. Missing info? Search, then ask.

4. Challenge Ideas

   If you see flaws, risks, or better approaches, say so directly. Do not auto-agree.

5. Read .cursor/rules/

   If you’re touching a documented domain (theme, popup, keys, stores, text), read the relevant rule doc BEFORE writing code.

Architecture Boundaries

Sovran follows a strict layered architecture:

app/

Routes + orchestration only. Screens stay thin.

components/ui/

Primitives. components/blocks/ for composed product UI.

hooks/coco/

Compose coco-cashu-react hooks for UX needs. Never reimplement coco internals.

helper/coco/

Non-React coco integration glue.

stores/

Zustand state management. Check .cursor/rules/zustand-store-scoping.mdc before adding or modifying stores.

coco-cashu-core

Source of truth for Cashu types. Import from coco, not @cashu/cashu-ts.

Directory Structure

app/              # Routes + orchestration (thin screens)
components/
  ui/             # Primitives
  blocks/         # Composed product UI
hooks/            # Reusable hooks
  coco/           # Cashu hook composition
helper/           # Stateless utils
  coco/           # Cashu integration glue
stores/           # Zustand (global, profile-scoped, or runtime-only)
.cursor/rules/    # Agent-facing rule docs (self-improving)

coco-cashu-core is the source of truth for Cashu types and logic. Never redefine coco types. Compose coco hooks, don’t reimplement them. Import from coco, not @cashu/cashu-ts.

Naming Conventions

Type	Convention	Example
Route groups	(thing-flow) kebab-case	(mint-flow), (send-flow)
Screens	index.tsx, descriptive names	detail.tsx, add.tsx
Components	PascalCase.tsx	WalletHeader.tsx
Hooks	useThing.ts	useNostrProfile.ts
Helpers	camelCase.ts	keyDerivation.ts
Handlers	handleX	handleSubmit
Callbacks	onX	onPress
Booleans	isX/hasX/shouldX	isLoading, hasBalance
Constants	SCREAMING_SNAKE	MAX_RETRIES

Import Order (Strict)

Maintain this exact import order:

// 1. React / React Native
import React from 'react';
import { View, Text } from 'react-native';

// 2. Expo / Expo Router
import { useRouter } from 'expo-router';
import * as SecureStore from 'expo-secure-store';

// 3. Third-party (alphabetized)
import { useQuery } from '@tanstack/react-query';
import { create } from 'zustand';

// 4. Internal absolute (coco-cashu-core → coco-cashu-react → @/helper/coco → @/hooks/coco → rest)
import { Proof } from 'coco-cashu-core';
import { useMint } from 'coco-cashu-react';
import { deriveKeys } from '@/helper/coco/keyDerivation';
import { useProcessPayment } from '@/hooks/coco/useProcessPayment';
import { useSettingsStore } from '@/stores/settingsStore';

// 5. Relative (./ then ../, alphabetized)
import { Button } from './Button';
import { Header } from '../Header';

Remove unused imports. This is checked by the linter.

Security — Absolute Rules

These are non-negotiable security requirements:

• Never store secrets in Zustand. Use expo-secure-store.
• Never change key derivation outputs, parameters, or serialization without reading .cursor/rules/secure-storage-key-derivation.mdc.
• Never commit mnemonics, nsec, private keys, API tokens, .env contents.

Never Commit

Scan diffs before staging. Refuse to commit if found:

• Passwords, API keys, tokens, session cookies
• Mnemonics (12–24 words), xprv, WIF, raw private keys
• Nostr secrets (nsec1...), hex private keys
• .env contents, credential files

Rule Documentation Improvement Protocol

When you encounter any of these situations, update .cursor/rules/ in the same PR:

1. Gap

   You needed info that wasn’t documented → add it to the relevant doc, or create a new one following .cursor/rules/rules-index-authoring-guide.mdc.

2. Stale

   A doc contradicts what the code actually does → fix the doc to match reality.

3. Missing Pattern

   You discovered a convention by reading code that future agents would benefit from → append it to the appropriate doc.

4. Post-mortem

   A bug was caused by violating an undocumented rule → document the rule so it isn’t repeated.

Format for new rule docs: see the authoring template in .cursor/rules/rules-index-authoring-guide.mdc.

Self-Check Before Submitting

Before submitting a PR, verify:

• ✅ Does the diff only contain changes required by the task?
• ✅ Are loading states layout-shift free?
• ✅ Are coco types imported from coco, not redefined?
• ✅ Are new stores registered in profile-switch and reset contracts (if profile-scoped)?
• ✅ Would a future agent understand why this code exists?
• ✅ All quality checks pass? (See Code Quality)

Support

GitHub Issues

Bug reports and feature requests

Nostr

Direct messaging via Nostr protocol

Twitter

@KevinKelbie