Technology

Repository Structure

Integrated System (4 repos, tightly coupled)

These repos share a common Supabase backend and must be considered together:

~/code/sv-portal     # Customer-facing React app
~/code/sv-edge       # Supabase Edge Functions (Deno/TypeScript)
~/code/sv-db         # Database migrations (SQL)
~/code/sv-docs       # System documentation

Standalone Projects

These repos have NO Supabase integration, NO shared code with the portal.

sv-portal (Customer Portal)

Overview

• Tech: Vite + React + TypeScript + Tailwind CSS
• Auth: Supabase magic links (email-based, no passwords)
• State: React Query for server state
• Customer routing: React Router (4 routes only)

Customer Routes (Non-Negotiable)

Staff/Admin Routes (Not Customer-Facing)

Key Components

src/
├── components/
│   ├── ProtectedRoute.tsx  # Auth guard (all protected routes)
│   ├── ItemCard.tsx        # Individual item display
│   ├── BookingsList.tsx    # Booking management
│   ├── AddItemModal.tsx    # Item creation
│   └── EditItemModal.tsx   # Item editing
├── pages/
│   ├── Login.tsx           # Auth page
│   ├── Dashboard.tsx       # Main inventory view
│   ├── Schedule.tsx        # Booking flow
│   └── Account.tsx         # User settings
└── lib/
    └── supabase.ts         # Supabase client

Commands

cd ~/code/sv-portal
npm run dev          # Start development server (localhost:5173)
npm run build        # Build for production (tsc + vite build)
npm run typecheck    # TypeScript validation (canonical command)
npm run lint         # Alias for typecheck (until ESLint is added)
vercel               # Preview deploy (Zach promotes to production)

sv-edge (Edge Functions)

Overview

• Runtime: Deno (Supabase Edge Functions)
• Auth: JWT verification + RLS
• Deployment: supabase functions deploy

Functions (16 deployed)

Stripe Integration

Calendly Integration

Booking Operations

Customer & Email

Data Export

Utility

Deployment (CRITICAL)

cd ~/code/sv-edge

# Individual function
supabase functions deploy stripe-webhook --no-verify-jwt
supabase functions deploy calendly-webhook --no-verify-jwt

# Or use the deploy script (recommended)
./deploy-and-test.sh

Webhook URLs

Incident Log

Promo Page Architecture

How Routing Works

A Vercel rewrite rule in sv-website/vercel.json maps all promo slugs to a single file:

{ "source": "/promo/:code", "destination": "/promo" }

Vercel's cleanUrls: true setting automatically serves promo/index.html at the /promo path. When the page loads, client-side JavaScript:

1. Reads the URL slug (e.g., beacon from /promo/beacon)
2. Looks it up in a PROPERTIES object embedded in the HTML (70 entries)
3. If found: populates the page with the property name, promo code, share links, and QR code
4. If not found: hides the promo content and shows a “Page Not Found” message with a link back to the main site

File Structure

Design Characteristics

• Brand-consistent: Uses the same color palette (Charcoal Blue, Berry, Parchment, Stormy Teal), fonts (DM Serif Display + Inter), and design language as the main website and partnerships page
• Mobile-first responsive: Tested at 390px (iPhone), 600px (tablet), and desktop widths. Two-column layouts collapse to single-column on mobile.
• Performance: All styles inline (no external CSS). GPU-accelerated scroll animations (translate3d, will-change lifecycle management). SVG noise texture instead of heavy images.
• Accessibility: prefers-reduced-motion support, focus-visible outlines, semantic HTML, sufficient color contrast
• Animation: translate3d(0, 28px, 0), 0.8s ease-out, IntersectionObserver with threshold: 0.1 and rootMargin: '0px 0px -40px 0px' — matches main site patterns

Analytics Events

Promo pages fire events to both Vercel Web Analytics and GA4:

Events use the window.va?.('event', ...) script-tag API pattern (not .track()). GA4 captures page views and scroll depth automatically via Enhanced Measurement.

QR Code Generation

QR codes are generated dynamically via api.qrserver.com (external API). Each encodes the full promo URL (e.g., https://mystoragevalet.com/promo/beacon). The QR image uses Charcoal Blue (#213C47) for brand consistency. Suitable for lobby flyers, elevator screens, move-in packets, and digital signage.

Dual-View: Resident vs Property Manager

Promo pages support two view modes controlled by a URL parameter:

When PM mode activates, the ?pm=true parameter is stripped from the URL bar via history.replaceState so the clean URL can be shared. PM-originated share links include ?src=pm for analytics attribution. The toggle is implemented client-side — the .share-section element is hidden by default and displayed only when isPM is true.

Slug Convention

• Lowercase only, no spaces, no hyphens, no special characters
• Must be unique across all entries in the PROPERTIES object
• Should be recognizable (e.g., beacon, greyson, sable)

Adding a New Property (Technical Steps)

1. Create a Stripe promotion code on coupon W8K6JWCH (LIVE mode — confirm with Zach):

   stripe promotion_codes create \
     -d coupon=W8K6JWCH \
     -d code=NEWPROPERTY \
     -d metadata[property_slug]=newproperty \
     -d metadata[property_name]="New Property Name"

2. Add to the PROPERTIES object in sv-website/promo/index.html (alphabetical by slug):

   "newproperty": { name: "New Property Name", code: "NEWPROPERTY" },

3. Commit and push to main. Vercel auto-deploys within ~60 seconds.
4. Verify: Visit mystoragevalet.com/promo/newproperty and confirm property name, promo code, QR code, and share tools render correctly.

Removing a Property

1. Remove the entry from the PROPERTIES object in promo/index.html
2. Deactivate the corresponding Stripe promotion code
3. Commit and push — the URL will then show the “Page Not Found” fallback

Planned Enhancements

Future phases (documented in sv-docs/specs/promo-landing-pages.md) will add:

• Embedded signup form with address fields pre-filled from property data
• Promo code auto-application at Stripe Checkout (no manual entry)
• Database attribution (promo_code column on pre_customers table)
• Additional analytics events: promo_signup_submit, promo_checkout_redirect, promo_signup_waitlist

Integrations

Stripe

Calendly

Supabase Storage

Vercel Web Analytics

Custom Events Tracked

Script-Tag API Pattern (Important)

// CORRECT — script-tag API
window.va?.('event', { name: 'signup_submit' });
window.va?.('event', { name: 'cta_click', data: { text: 'Get Started', location: 'hero' } });

// WRONG — npm package API (will throw TypeError)
window.va?.track('signup_submit');
window.va?.track('cta_click', { text: 'Get Started' });

Google Analytics (GA4)

Added Feb 28, 2026. Provides deeper behavioral analytics beyond what Vercel Web Analytics captures — user flows, engagement time, acquisition channels, and conversion events.

Enhanced Measurement (Auto-Tracked)

These events are captured automatically by GA4 with no additional code:

Vercel Analytics vs GA4 — When to Use Which

Still To Build Out

• GA4 conversion events: Mark key actions (e.g., signup form submission, Stripe checkout redirect) as conversions in GA4 for funnel tracking
• Google Ads linkage: When Google Ads is set up, link to this GA4 property for ad performance tracking
• Google Business Profile: Not yet created — needed for local search visibility, Google Maps listing, and review collection
• Meta (Facebook) Pixel: Not yet installed — needed if running Facebook/Instagram ads

HubSpot CRM

Added Mar 2026. Partnership sales pipeline management — tracks prospective property partners from research through signed partnership. Separate from product infrastructure (Supabase, Stripe, Calendly handle customer-facing operations).

Pipeline Stages

Custom Deal Properties

property_address, unit_count, property_type, city, outreach_status, data_source, date_sent, followup_date, response_date, promo_code, promo_url, activity_log

Scope & Boundaries

• HubSpot is sales pipeline ONLY — tracks B2B partnership outreach to property management companies
• Not connected to product infrastructure — Stripe handles billing, Supabase handles customer data, Calendly handles scheduling
• Promo tracking: 69 deals have promo_code + promo_url linking to property-specific promo landing pages
• Company associations: 81 deals linked to 18 management companies; 144 deals pending association

SEO & Performance (Feb 2026)

Security

Authentication

• Method: Magic links (email-based, no passwords)
• Provider: Supabase Auth
• Token: JWT with user ID
• Session: Persisted to localStorage; survives new tabs, refresh, and browser restart. Auth guard (ProtectedRoute) gates on Supabase INITIAL_SESSION event before rendering redirects.

Row Level Security (RLS)

All customer tables are protected by RLS:

• Users can only see/modify their own data
• auth.uid() used in all policies
• Service role bypasses RLS (edge functions only)

Billing Protection

Billing fields on customer_profile are protected:

• Users CANNOT update subscription_status, stripe_customer_id, subscription_id
• Updates only via SECURITY DEFINER functions from webhooks

Secrets Management

Secret Inventory

Approved Patterns

# Fetch a secret (never prints to terminal)
OP_BIOMETRIC_UNLOCK_ENABLED=true op read 'op://Storage Valet/Stripe Live/secret_key'

# Push to Supabase without exposing the value
OP_BIOMETRIC_UNLOCK_ENABLED=true op read 'op://Storage Valet/Stripe Live/secret_key' \
  | xargs -I {} supabase secrets set STRIPE_SECRET_KEY="{}" --project-ref gmjucacmbrumncfnnhua

# Shell env vars — lazy-loaded via sv-env function (run once per session)
# Secrets are NOT resolved at shell startup to avoid macOS permission popups
sv-env         # loads SUPABASE_ACCESS_TOKEN, STRIPE_SECRET_KEY, RESEND_API_KEY
               # also caches to ~/.sv-session (chmod 600) for sub-agent inheritance
               # session file auto-deletes on shell exit; run sv-env-clear to wipe manually

Rotation Procedures

1. Generate/rotate the credential in the service's dashboard
2. Update the value in 1Password (Storage Valet vault)
3. If the secret is in Supabase secrets, push via: op read '...' | xargs -I {} supabase secrets set KEY="{}"
4. Verify the dependent service still works (e.g., test checkout, test email)

Deferred: Supabase service role key rotation. High blast radius (breaks all 16 edge functions). Requires planned maintenance window. See DEC-011.

Tripwire (Automated Detection)

sv-final-audit.sh includes a secrets tripwire that scans ~/.zshrc, ~/.claude/settings.json, and ~/.claude/settings.local.json for plaintext credential patterns at the end of every session. It also flags any .env files in ~/code/ repos. Additionally, the audit script includes a GitHub hygiene layer that detects stale PRs (open >7 days) and orphan remote branches (>30 days with no associated PR) across all 6 repositories.

Deployment

Portal (Vercel)

cd ~/code/sv-portal
npm run build        # Verify build passes
vercel               # Preview deploy (NOT --prod)

Auto-deploys from GitHub main branch. Use preview deploys for testing; Zach promotes to production manually. Do not run vercel --prod directly.

PR validation: GitHub Actions workflow (.github/workflows/pr-validation.yml) runs npm run typecheck and npm run build on all PRs to main. Both must pass before merge.

Edge Functions

cd ~/code/sv-edge
./scripts/deploy-customer-facing.sh   # Deploy all 14 customer-facing functions
./scripts/smoke-edge.sh               # Post-deploy smoke test
# OR manually:
supabase functions deploy <function-name> --no-verify-jwt

Always run ./scripts/check-deps.sh before deploying. Deploy ALL customer-facing functions together to avoid version drift.

Database Migrations

cd ~/code/sv-db
supabase db push --linked

Requires: Docker Desktop running

Git Configuration

Use only real, verified email addresses. Fabricated emails cause Vercel permission failures.

Architecture Constraints (Non-Negotiable)

1. 4 customer routes only: /login, /dashboard, /schedule, /account
2. Staff routes permitted under /ops and /admin/* but must remain staff-gated (sv.is_staff())
3. Supabase backend only — no custom API servers
4. Stripe Hosted flows only — no custom card UI
5. Single pricing tier: $299/month
6. Magic links only — no password auth
7. Portal is authentication-only — account creation happens exclusively through the website registration flow (Stripe Checkout). The portal login does not create new users.
8. RLS on all tables — zero cross-tenant access
9. Private storage bucket — signed URLs, 1h expiry

Architecture Notes

Common Issues & Solutions

Platform Operations Toolkit

A tiered toolkit for session integrity, repository hygiene, and infrastructure observability. Introduced March 2026 after an orphaned PR went undetected for 35 days. See DEC-017 for rationale.

Commands

All Shell Shortcuts

Defined in ~/.zshrc. Run sv-help to see this list in the terminal.

iTerm2 Tab Auto-Naming

Tabs automatically show the current directory name via a precmd hook in ~/.zshrc. Use title "My Topic" to set a custom title, or title (no args) to reset to auto. Claude Code also sets the tab title to the chat name when running.

Setup (one-time per machine): Disable custom tab titles in iTerm2’s plist (quit iTerm2 first, run via Terminal.app), then add the _update_tab_title precmd function and title() helper to ~/.zshrc. Both machines were configured March 2026.

1Password SSH Agent

Both machines use 1Password’s SSH agent for Git authentication and commit signing. Three configuration files work together:

SSH_AUTH_SOCK (in ~/.zshrc):

export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

agent.toml (in ~/.config/1Password/ssh/):

[[ssh-keys]]
item = "Github SSH Key (SV)"
vault = "Storage Valet"

Key details: The SSH key is a single ed25519 key named “Github SSH Key (SV)” stored in the Storage Valet vault. Both machines share the same key via 1Password vault sync. The key is registered on GitHub for both authentication and commit signing.

Git signing config (set via git config --global on both machines):

gpg.format = ssh
commit.gpgsign = true
tag.gpgsign = true
gpg.ssh.allowedSignersFile = ~/.ssh/allowed_signers

Script Locations

All scripts are canonical in ~/code/sv-docs/scripts/ (git-tracked). A convenience symlink at ~/code/sv-final-audit.sh points to the canonical audit script for manual use, but no script depends on this symlink.

Design Principles

• Non-destructive audits: sv-audit reads only (except 1Password socket cleanup). It never modifies git state, GitHub, or infrastructure.
• Explicit cleanup: sv-hygiene is a separate, opt-in command. It only deletes branches confirmed merged into main.
• Canonical paths: Scripts reference ~/code/sv-docs/scripts/ directly. Symlinks exist for convenience but are not dependencies.
• Dual observability: Stale PRs are detected at session start (bootstrap snippet) and session end (audit script).

Developer Setup

Code Repositories

~/code/
├── sv-portal/   # Customer-facing React app (Vite + React + TypeScript + Tailwind)
├── sv-edge/     # Supabase Edge Functions (Deno/TypeScript)
├── sv-db/       # Database migrations (SQL)
├── sv-docs/     # Operational scripts, runbooks, and archive
├── sv-website/  # Landing page (www.mystoragevalet.com)
└── sv-wiki/     # Internal wiki (wiki.mystoragevalet.com)

New Machine Setup

When setting up Claude Code on a new machine:

1. Ensure iCloud Desktop & Documents sync is enabled (System Settings → Apple ID → iCloud → iCloud Drive)
2. Create symlinks:

   ln -sf ~/Documents/storagevalet/Technology/Reference/CLAUDE.md ~/.claude/CLAUDE.md
   ln -sf ~/Documents/storagevalet/Technology/Reference/code-CLAUDE.md ~/code/CLAUDE.md

3. Clone repos to ~/code/: sv-portal, sv-edge, sv-db, sv-docs, sv-website, sv-wiki
4. Install Node.js via Homebrew: brew install node@24 (do NOT use .pkg installer)
5. Install CLI tools: brew install supabase gh stripe deno pipx
6. Install Homebrew-managed casks: brew install --cask 1password-cli appcleaner bettermouse claude-code cleanshot codex cursor font-jetbrains-mono font-source-code-pro framer gcloud-cli github hazel loom miro notion obsidian rectangle-pro spotify superwhisper textexpander typora visual-studio-code whimsical wispr-flow
   Note: claude-code cask is used on Mac Studio. On MacBook Air, Claude Code is installed via the native installer (claude install, installs to ~/.local/bin/claude). Do NOT install via npm — the npm package @anthropic-ai/claude-code is deprecated in favor of native installers.
7. Install remaining apps directly: Docker Desktop (required for Supabase CLI), 1Password (biometric agent for op CLI), iTerm2 (custom Dock icon; has reliable built-in updater), Google Chrome, Google Drive — these must NOT be installed via Homebrew as replacement can break system integrations
8. Run op signin to authenticate 1Password

Session Startup Checklist

Run these steps at the beginning of each Claude Code session (human or agent):

1. Check for CLAUDE.md sync conflicts:

   CLAUDE_DIR="$(cd "$(dirname "$(readlink ~/.claude/CLAUDE.md || echo ~/.claude/CLAUDE.md)")" && pwd)"
   ls "$CLAUDE_DIR" 2>/dev/null | grep -i conflict && echo "CLAUDE.md CONFLICT — resolve before continuing"

2. Pull latest for all repos:

   for repo in sv-portal sv-edge sv-db sv-docs sv-website sv-wiki; do (cd ~/code/$repo && git pull); done

3. Verify migrations: supabase migration list --linked
4. Read context: ~/.claude/CLAUDE.md and ~/code/CLAUDE.md
5. Docker Desktop must be running for Supabase CLI

Session End Protocol

1. Run sv-audit (or sv-check for full platform verification) — do not declare clean until Audit: CLEAN
2. If the audit flags GitHub hygiene issues (stale PRs, orphan branches): review and resolve
3. If session was significant (deploy, E2E verification, architecture decision): update relevant SV-Wiki pages and commit to sv-wiki repo

See Platform Operations Toolkit for the full command reference.