CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Anchored (formerly URL Notes) is a browser extension and web app for domain/URL-specific note-taking with zero-knowledge encryption. The project features a glassmorphism ocean-themed UI, local-first architecture with cloud sync, and a $2.50/month premium tier.

Development Commands

Supabase Backend

supabase start                                      # Start local Supabase
supabase db push                                    # Deploy schema changes
supabase db reset                                   # Reset local database
supabase gen types typescript --local > types/database.ts
supabase functions deploy                           # Deploy all Edge Functions
supabase functions serve                            # Local development
supabase functions logs <name>                      # View production logs

Extension Development

# Load /extension/ folder in chrome://extensions/ → "Load unpacked"
# No build system - code runs directly in browser

Cache Management

npm run cache:bust                                  # Update cache version
npm run cache:deploy                                # Deploy with cache bust
npm run cache:deploy:commit                         # Deploy and commit

Critical Architecture Constraints

MANDATORY Rules - Never Violate

Local-First Data Flow

Browser Extension Requirements

Security Requirements

Note Storage Model

Code Organization

Mandatory Data Flow Pattern

User Action → popup.js → Module → storage.js → IndexedDB
                    ↓
Background: sync.js → api.js → Supabase (encrypted)

Module Responsibilities (Strict Separation)

Library Layer (/extension/lib/)

File Modification Policy

UI/UX Standards

Glassmorphism Design System

All UI components must use ocean-themed glassmorphism:

backdrop-filter: blur(10px);
background: rgba(255,255,255,0.1);
box-shadow: 0 8px 32px rgba(0,0,0,0.1);
border: 1px solid rgba(255,255,255,0.2);

Color Palette

Performance Targets

Feature Tiers

Free Tier

Premium Tier ($2.50/month)

Data Management

Version Control Rules

Error Handling

Premium Features Implementation

Current Premium Features in Development

Located in .kiro/specs/premium-features/:

  1. Global Search Engine - Cross-domain search with filters
  2. Note Linking System - Bidirectional [[Note Title]] links
  3. Citation Manager - Academic citations (APA, MLA, Chicago, Harvard, IEEE)
  4. Smart Collections - Rule-based automatic categorization
  5. Unlimited Version History - Full revision tracking
  6. Advanced Export - Multiple formats with metadata preservation
  7. Note Sharing - Secure share links with read-only access
  8. File Attachments - Encrypted file storage (10MB limit per file)
  9. Voice Notes - Recording and transcription
  10. Unlimited Tags - No tag limits for premium users

Premium Feature Requirements

All premium features must:

Browser Compatibility

Cross-Browser API Usage

Use browser.* APIs instead of chrome.* where possible for cross-browser compatibility:

// Good
const tabs = await browser.tabs.query({ active: true });

// Avoid (Chrome-specific)
const tabs = await chrome.tabs.query({ active: true });

Security Best Practices

XSS Protection Strategy

  1. Input Sanitization: All user input sanitized using DOMPurify
  2. Content Security Policy: Strict CSP headers in manifest.json
  3. Safe DOM Manipulation: Use safe DOM utilities for HTML insertion
  4. Link Validation: All note links validated before rendering
  5. Metadata Validation: Citation metadata sanitized before storage

Encryption Flow

// Encrypt before cloud storage
const encrypted = await window.noteEncryption.encryptData(data, userKey);

// Decrypt after retrieval
const decrypted = await window.noteEncryption.decryptData(encrypted, userKey);

Common Pitfalls to Avoid

  1. Don’t add build systems: Code runs directly in browser
  2. Don’t use ES6 modules: Use global window.ModuleName pattern
  3. Don’t block UI on network: Always show cached data immediately
  4. Don’t store unencrypted data in cloud: Encrypt first
  5. Don’t modify existing migrations: Add new migrations only
  6. Don’t change popup dimensions: Fixed at 400x600px
  7. Don’t skip XSS sanitization: Always sanitize user input
  8. Don’t use Chrome-specific APIs: Use browser.* for cross-browser compatibility
  9. Don’t break local-first flow: IndexedDB is always source of truth
  10. Don’t add frameworks: Vanilla JS only

Development Workflow

  1. Make changes in /extension/: All extension code goes here
  2. Test locally: Load unpacked extension in chrome://extensions/
  3. Database changes: Add new migration in /supabase/migrations/
  4. Edge Functions: TypeScript code in /supabase/functions/
  5. Deploy database: supabase db push
  6. Deploy functions: supabase functions deploy

Project Structure

/extension/              # Browser extension (Manifest V3)
  /popup/               # Popup UI and modules
    popup.js            # Main orchestrator
    /modules/           # Feature modules (notes, editor, settings)
    /css/              # Glassmorphism styles
  /lib/                # Pure functions, no DOM dependencies
    storage.js         # IndexedDB wrapper
    sync.js            # Supabase sync
    encryption.js      # AES-256-GCM encryption
    api.js             # Supabase client
  manifest.json        # Extension configuration
/supabase/             # Backend infrastructure
  /migrations/         # Database schema (add new only)
  /functions/          # TypeScript Edge Functions
/docs/                 # Documentation
/.kiro/                # Amazon Kiro steering files
  /steering/           # Product, structure, tech guidelines
  /specs/             # Feature requirements and design

Testing Premium Features

Premium Feature Checklist

Additional Context