Technology

Repository Structure

Integrated System (two portals + shared backend)

These repos share the common Supabase backend (project gmjucacmbrumncfnnhua) and must be considered together:

~/code/sv-portal-2026  # LIVE customer portal (Vite 8 / React 19) — native Google Calendar; cut over Jun 10, 2026
~/code/sv-portal       # v1 portal (Vite 5 / React 18) — DECOMMISSIONED Jun 29, 2026 (frontend retired, repo archived)
~/code/sv-edge         # Supabase Edge Functions (Deno/TypeScript) — shared by both portals
~/code/sv-db           # Database migrations (SQL) — shared by both portals
~/code/sv-docs         # Ops scripts, runbooks, archives (orchestrates all 7 repos)

Cutover executed Jun 10, 2026 (~20:33 ET): portal.mystoragevalet.com now serves the sv-portal-2026 codebase — the Vercel domain was re-pointed per DEC-020, with the founder waiving the remaining checklist items (signup E2E, Manage-Billing verify, $2,000-cap verify; now post-flip tasks). The first live-domain booking was verified end-to-end the same evening: DB custody + audit trail + Google Calendar event. v1 (sv-portal) was decommissioned Jun 29, 2026 (DEC-021): frontend retired, v1-only edge functions + RPCs + views removed, repo archived. Ops now lives in the v2 portal’s staff /ops surface (W1.4).

Both portals run against the same Supabase project. The v2 backend (additive) was merged and applied to prod on Jun 9, 2026; native Google Calendar scheduling is the live booking layer on the customer domain (DEC-0001 executed): service account sv-calendar@sv-scheduling.iam.gserviceaccount.com writes to the founder-owned “SV Bookings” calendar (secrets GOOGLE_SERVICE_ACCOUNT_JSON + GOOGLE_CALENDAR_ID set in Supabase). Availability comes from get-available-slots (plan service windows ∩ 48-hour lead ∩ calendar FreeBusy), with bookings available up to 365 days out via the month-paged slot picker. Calendly remains only as v1’s legacy read-only webhook path.

Marketing & Docs Sites

sv-website is not standalone — its signup/partnership forms call three sv-edge functions (signup-webhook, create-checkout-trial, partnership-inquiry) on the shared Supabase project, so changing those contracts breaks the site. Only sv-wiki is fully standalone (no integrations).

Customer Portal (sv-portal-2026 — LIVE)

Overview

• Live since: Jun 10, 2026 — portal.mystoragevalet.com serves the sv-portal-2026 codebase (DEC-020 domain re-point)
• Tech: Vite 8 + React 19 + TypeScript (strict) + Tailwind 4 — v6 Operation Midnight Teal tokens
• Auth: Supabase magic links (email-based, no passwords)
• Write path: fn_v2_* SECURITY DEFINER RPCs only (sole exception: two-step photo upload)
• Scheduling: native Google Calendar — availability via get-available-slots; bookings up to 365 days out (month-paged picker)
• State: TanStack Query for server state; React Router 7

Customer Surfaces (6)

Staff operations live in the v2 portal’s /ops surface (shipped W1.4) — staff-gated (is_staff()) and AAL2-stepped-up, reading fn_v2_ops_queue / fn_v2_ops_booking_detail and acting through the staff edge wrappers (complete-service, staff-booking-cancel, staff-booking-reschedule, staff-item-revert).

v1 (sv-portal) — Decommissioned

v1 was decommissioned Jun 29, 2026 (DEC-021): frontend retired (static placeholder at sv-portal-gamma.vercel.app, git disconnected), its v1-only edge functions + RPCs + views removed from prod, repo archived. Its former staff routes (/ops, /admin/waitlist, /admin/customers) and the get_ops_actions RPC behind them no longer exist — ops moved to the v2 /ops surface above.

Commands

cd ~/code/sv-portal-2026
npm run dev          # Vite dev server (mock mode by default — every surface browsable)
npm run build        # tsc -b && vite build (must pass before any push)
npm run typecheck    # tsc -b
npm run test         # vitest run

cd ~/code/sv-portal  # v1 — DECOMMISSIONED Jun 29, 2026 (archived; reference only, not deployed)

sv-edge (Edge Functions)

Overview

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

Functions (20)

Scheduling & v2 Booking (Google Calendar)

Stripe Integration

Calendly (Legacy v1 Path)

Booking Operations

Customer & Email

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 Operation Midnight Teal palette and the same DM Serif Display + Outfit typography as the rest of the Storage Valet brand system. Dark-first surfaces with Electric Teal accents. Text-only logo (no box icon). See Brand Identity for the full system.
• 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 Midnight (#0A1628) for brand consistency with the Operation Midnight Teal palette. 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

Google Calendar (Native Scheduling — LIVE)

The live booking layer on the customer domain since Jun 10, 2026 (DEC-0001 executed). Booking confirm creates the calendar event; cancel/revert deletes it. Custody never mutates without a calendar event (block-on-outage).

Calendly (Legacy — v1 read-only path)

Calendly is no longer the live booking layer. The calendly-webhook function remains deployed as a legacy webhook path (kept past the v1 decommission, pending a separate Calendly-retirement decision) with HMAC verification ENABLED (fails closed — keep CALENDLY_WEBHOOK_SIGNING_KEY set in Supabase secrets). Events: invitee.created, invitee.canceled. Webhook only, no outbound API calls.

Supabase Storage

Transactional Email (Resend)

All transactional mail renders via the send-email edge function (Resend). Customer-facing types, plus the internal ops_alert:

Deliverability (Jun 15, 2026): every customer email send is wrapped in EdgeRuntime.waitUntil across all 7 sending functions, so the Supabase isolate cannot freeze before the Resend POST completes (previously these fire-and-forget sends could silently never deliver). send-email also fires an ops_alert when a customer send returns non-200. Booking emails + their ICS now include the service address (LOCATION).

Website Analytics

GA4 (G-9SBYJ8QEC1) and Vercel Web Analytics Plus ($10/month) run on all sv-website pages. GA4 handles behavioral analytics, acquisition channels, and UTM attribution. Vercel handles custom event tracking and privacy-friendly visitor counts. Vercel Speed Insights tracks Core Web Vitals.

Full analytics documentation → — configuration, internal traffic filtering, custom events, UTM attribution, and GA4 MCP tools.

HubSpot CRM

Added Mar 2026. Partnership sales pipeline management — tracks prospective property partners from research through signed partnership. Separate from product infrastructure (Supabase, Stripe, Google Calendar 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, Google Calendar handles scheduling
• Promo tracking: 69 deals have promo_code + promo_url linking to property-specific promo landing pages
• Company associations: deals are progressively linked to their management companies (counts drift with enrichment) — see HubSpot for live association status

E-Signature & Contracts (Jun 2026)

Go-to stack for generating and sending Storage Valet agreements (partners, customers, vendors). Decided Jun 12, 2026: Google Workspace eSignature is primary; PandaDoc Free eSign is the backup for recipient preference or outages. No additional paid tool. Full step-by-step workflow → Legal § Contracts & E-Signature.

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 PERSISTS across shells; 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 7 repositories.

Deployment

Portal (Vercel)

cd ~/code/sv-portal-2026
npm run build        # tsc -b && vite build — must pass before any push
vercel               # Preview deploy (NOT --prod)

Both portal projects auto-deploy from their GitHub main branches; the customer domain has pointed at sv-portal-2026 since Jun 10, 2026. AI commits, pushes, and merges PRs to main directly to ship — no manual promotion step. Do not run vercel --prod directly. Rollback = re-point the domain back to sv-portal (seconds).

PR validation (sv-portal): 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. 6 customer surfaces only: Login, Dashboard, Items + Add Item, Item Detail, Booking, Account
2. Staff routes live in the v2 portal’s /ops surface (portal.mystoragevalet.com/ops), staff-gated (is_staff()) and AAL2-stepped-up
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.

Ghostty Config Sync

Ghostty configuration lives in iCloud at ~/Documents/storagevalet/Technology/Ghostty/config and is symlinked to ~/.config/ghostty/config on each machine.

1Password SSH Agent

The 1Password SSH agent is configured on both machines for any SSH-based operations (ssh to other hosts, SSH-backed git clones, etc.). Git commit signing is intentionally disabled — 1Password’s signing-authorization prompts appear on the Mac Studio screen and cannot be answered when working remotely via the Claude app’s code tab. Sole-developer context plus private repos means signing has no practical benefit to offset that friction.

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 authentication on any SSH-based git remotes.

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-2026/  # LIVE customer portal (Vite 8 / React 19 / Tailwind 4) — cut over Jun 10, 2026
├── sv-portal/       # v1 portal (Vite 5 / React 18 / Tailwind 3) — DECOMMISSIONED + archived Jun 29, 2026
├── 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-portal-2026, 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@latest cleanshot codex cursor font-jetbrains-mono framer gcloud-cli ghostty hazel loom miro 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.