thunderbolt AGENTS.md

Core Principles

• Bias towards tasteful simplicity - favor elegant, readable, maintainable solutions that add minimal complexity. Avoid over-engineering, premature optimization, and defensive coding patterns that obscure intent.
• Always implement proper, architectural solutions - no shortcuts, hacky fixes, or temporary workarounds. Research best practices when needed.
• Prefer optimistic code over defensive code - let errors surface loudly during development rather than wrapping everything in if-checks and try/catch blocks. Handle errors architecturally at higher levels (e.g., error handling middleware).
• Deletes (soft vs hard)
  • Frontend: Never hard delete. Always soft delete data (set deletedAt; call APIs that update rather than permanently remove). The only exception is flows that explicitly perform account or device removal (e.g. “Delete account”), which call backend endpoints that hard delete by design.
  • Backend: Prefer soft deletes—set deletedAt and filter out soft-deleted records in queries. Use hard delete only when required: e.g. account deletion (user and related data), PowerSync delete operations, or other cases where permanent removal is by design.
• Question and recommend alternatives - your goal is better outcomes, not blind execution. Stop and ask for input when appropriate.

TypeScript & Code Style

• Never use any in TypeScript
• Prefer type over interface
• Prefer arrow functions over function keyword
• Prefer const over let - create helper functions with early return instead of setting let variables inside conditionals
• Use camelCase for const and variable names
• Prefer early return over long if statements and nested code
• Use direct imports: useEffect not React.useEffect
• Prefer top-level imports over inline/dynamic imports (await import(...)) when no circular dependency exists
• Prefer async/await over .then/.catch
• Add JSDoc comments to new utility functions
• Only comment non-obvious code - avoid useless comments like "// Save data collection mutation" before saveDataCollection()
• Loosely prefer one React component per file