AlpacApps Infra

Architecture & Cost Calculator

Key principle: No backend server. All application logic runs client-side in the browser. Supabase provides the database, authentication, and serverless functions. For file storage, you can use Supabase Storage (1 GB free) or Cloudflare R2 (10 GB free, zero egress fees). GitHub Pages serves static files for free.

CSS: Tailwind CSS v4 is available alongside existing CSS custom properties. The Tailwind source (styles/tailwind.css) defines AAP design tokens (colors, fonts, shadows, radii) and is compiled to styles/tailwind.out.css by GitHub Actions CI on every push. Use npm run css:build locally or npm run css:watch for development. All pages load both site.css (custom properties) and tailwind.out.css (utility classes).

Select what you need

Core services are pre-selected. Toggle optional ones on or off.

How much will you build?

This mainly affects your Claude Code plan and usage-based services.

1. GitHub + Starter Template Free

First, get a GitHub account and create your project from the starter template. Everything here is done in your browser — no terminal needed.

Create a GitHub account

You'll need a free GitHub account to host your site and store your code. If you already have one, skip to the next step.

1. Go to github.com/signup and sign up with your email
2. Verify your email address (GitHub will send you a confirmation link)
3. That's it — a free account is all you need. GitHub Pages hosting is free for public repositories.

Create your project from the template

Choose a name for your project. This will become your repository name on GitHub (lowercase with hyphens, no spaces, e.g., my-salon-app).

1. Go to the template repository: github.com/rsonnad/alpacapps-infra
2. Click the green "Use this template" button → "Create a new repository"
3. Enter your project name as the Repository name (e.g., my-salon-app)
4. Make sure Public is selected (required for free GitHub Pages hosting)
5. Click "Create repository" — GitHub copies all the template files into your own repo

Turn on GitHub Pages

1. In your new repo, go to Settings (gear icon near the top)
2. Click Pages in the left sidebar
3. Under "Source," select Deploy from a branch → main → / (root) → Save
4. Wait 1–2 minutes. Your site is live at https://<username>.github.io/<project-name>/

Download the project to your computer

You need a copy of your project on your computer. This takes two steps:

a) Open a terminal

b) Paste this command into your terminal

Click Copy below, then paste into your terminal (Ctrl+V on Windows, Cmd+V on Mac) and press Enter:

git clone https://github.com/USERNAME/my-salon-app.git
cd my-salon-appCopy

This downloads your project files into a folder on your computer. You'll point Claude Code at this folder in the next step.

Connect Git to your GitHub account

Before Claude Code can push code to your repository, Git needs to know your GitHub credentials. The easiest way is GitHub CLI, which handles this through your browser — no passwords or tokens to manage.

a) Install GitHub CLI

b) Log in to GitHub through your browser

Paste this into your terminal and press Enter:

gh auth loginCopy

It will ask a few questions — pick these answers:

1. Where do you use GitHub? → GitHub.com
2. Preferred protocol? → HTTPS
3. Authenticate Git with GitHub credentials? → Yes
4. How would you like to authenticate? → Login with a web browser

It will show a one-time code and open your browser. Paste the code, click Authorize, and you’re done.

Project structure included in the template:

your-repo/
├── index.html              # Landing page
├── styles.css              # Global styles
├── shared/                 # Shared JavaScript modules
│   ├── supabase.js         # Supabase client singleton
│   ├── auth.js             # Authentication
│   └── ...                 # Other services
├── spaces/                 # Public-facing pages
│   ├── index.html
│   ├── app.js
│   └── admin/              # Admin dashboard
│       ├── index.html
│       ├── app.js
│       └── manage.html
└── supabase/               # Edge functions (deployed via CLI)
    └── functions/

2. Install Claude Code

Claude Code is your AI developer. Once it's set up, you won't need to use the terminal again — but if Claude asks you to do something in the terminal or bash something, just ask it to do it by itself. Claude can handle everything from here, but sometimes forgets.

You do (one time)

1. Sign up for Claude Pro ($20/month recommended)
2. Download the Claude desktop app — Claude Code is built in
3. Open the app and click the Code tab in the top right to open Claude Code
4. Point it at the project folder you cloned in Step 1

Run the setup wizard

Once Claude Code is open in your project folder, type:

/setup-alpacapps-infra

Claude will ask you what you're building, which services you need, then walk you through the entire setup — creating your database, deploying edge functions, configuring webhooks, and building your CLAUDE.md (checked into repo) and CLAUDE.local.md (gitignored credentials). You don't need to read the rest of this guide unless you want to understand what's happening under the hood.

Read .claude/skills/setup-alpacapps-infra/SKILL.md and follow those instructions to set up my project

What the rest of this guide is for

The sections below explain each service in detail. For each one, you:

1. You create the account and copy credentials (in your browser)
2. You give Claude the credentials (just paste them into the chat)
3. Claude handles everything else — updates your config files, installs CLIs, creates tables, writes edge functions, deploys, and pushes code

You never need to edit files yourself. Just tell Claude what you want in plain English.

3. Supabase Free

Database, storage, auth, and serverless edge functions — all in one.

You do (in your browser)

1. Sign up at supabase.com/dashboard (GitHub login works)
2. Go to supabase.com/dashboard/projects and click New Project
3. If prompted to create an organization first, give it any name (e.g. “Personal”) and select the Free plan
4. Set a database password — save this securely (you’ll paste it to Claude)
5. Choose a region close to your users, click Create new project, and wait 1-2 minutes

Paste your project ref here — the links below will update so you can click straight to the right pages:

5. Go to API settings: supabase.com/dashboard/project/___/settings/api and copy:
   • Project URL (e.g., https://abcdefghijk.supabase.co)
   • Anon public key (safe to embed in frontend — RLS protects your data)
   • Project ref (the abcdefghijk part of the URL)
6. Go to Database settings: supabase.com/dashboard/project/___/settings/database → Connection string → Session pooler tab and copy it

Give Claude these credentials

## Supabase Details
- Project ID: `YOUR_PROJECT_REF`
- URL: `https://YOUR_PROJECT_REF.supabase.co`
- Anon key: `your-anon-key-here`
- Database password: `your-db-password`

### Direct Database Access (for Claude)
Session pooler connection string (paste yours from Database settings):
psql "postgres://postgres.YOUR_PROJECT_REF:YOUR_URL_ENCODED_PASSWORD@aws-0-REGION.pooler.supabase.com:5432/postgres" -c "SQL HERE"

URL-encode special characters in password (! = %21, @ = %40).

### Supabase CLI Access (for Claude)
If CLI not installed: npm install -g supabase && supabase login && supabase link --project-ref YOUR_PROJECT_REF
supabase functions deploy <function-name>
supabase secrets set KEY=value

For Claude: Run these directly. Don't ask the user.

Then tell Claude

4. Google Sign-In (Optional) Free

If your app needs user login (admin dashboard, customer accounts, etc.), the easiest option is “Sign in with Google.” Supabase has built-in support — you just need to create a Google Cloud project and get OAuth credentials.

1. Create a Google Cloud project

1. Go to console.cloud.google.com → New Project
2. Name it anything (e.g., “My Salon App”) and click Create
3. Make sure the new project is selected in the top-left dropdown

2. Set up the OAuth consent screen

This is the screen users see when they click “Sign in with Google.”

1. Go to APIs & Services → OAuth consent screen
2. Choose External (unless you’re on Google Workspace and only want internal users) → click Create
3. Fill in the required fields:
   • App name: your app’s name (what users see)
   • User support email: your email
   • Developer contact email: your email
4. Click Save and Continue through the Scopes, Test Users, and Summary steps (defaults are fine)

3. Create OAuth credentials

1. Go to APIs & Services → Credentials
2. Click + Create Credentials → OAuth client ID
3. Application type: Web application
4. Name: anything (e.g., “Supabase Auth”)
5. Under Authorized redirect URIs, add:

   https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback

6. Click Create and copy the Client ID and Client Secret

4. Connect to Supabase

1. Go to your Supabase dashboard → Authentication → Providers
2. Find Google in the list and toggle it on
3. Paste your Client ID and Client Secret
4. Click Save

Give Claude these credentials

### Authentication (Google OAuth via Supabase)
- Google Client ID: `your-client-id.apps.googleusercontent.com`
- Auth is handled by Supabase Auth (no edge function needed)
- Redirect URI: `https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback`
- Sign-in method: supabase.auth.signInWithOAuth({ provider: 'google' })

Then tell Claude

5. Resend (Email) Free

You do (in your browser)

1. Sign up at resend.com/signup (free: 3,000 emails/month)
2. Recommended: Add your domain at resend.com/domains and set up DNS records. Without this, you can only send from onboarding@resend.dev.
3. Create an API key at resend.com/api-keys and copy it

Give Claude these credentials

### Email (Resend)
- API key: `re_your_key_here` (store as Supabase secret: RESEND_API_KEY)
- From address: notifications@yourdomain.com (or onboarding@resend.dev)

Then tell Claude

6. Telnyx (SMS) Pay-as-you-go

You do (in your browser)

1. Sign up at telnyx.com/sign-up and add a payment method
2. Buy an SMS-capable number at portal.telnyx.com → Numbers (~$1/month)
3. Note the phone number in E.164 format (e.g., +12125551234)
4. Create a Messaging Profile at portal.telnyx.com → Messaging
5. Set inbound webhook URL:

   https://YOUR_PROJECT_REF.supabase.co/functions/v1/telnyx-webhook

6. Assign your phone number to this profile, note the Messaging Profile ID
7. Get your API key at portal.telnyx.com → API Keys and copy it

Give Claude these credentials

### SMS (Telnyx)
- API key: `KEY_your_key_here`
- Messaging Profile ID: `your-profile-id`
- Phone number: `+12125551234`
- Config stored in `telnyx_config` table
- Edge functions: `send-sms` (outbound), `telnyx-webhook` (inbound)
- Deploy webhook with `--no-verify-jwt`
- Auth: Bearer token (NOT Basic auth like Twilio)
- API: https://api.telnyx.com/v2/messages

Then tell Claude

7. Square (Payments) Pay-as-you-go

You do (in your browser)

1. Sign up at squareup.com/signup
2. Create an app at developer.squareup.com/console → Apps
3. Copy from the Developer Dashboard:
   • Application ID (starts with sq0idp-)
   • Access Token — Sandbox for testing, Production for real charges
   • Location ID — Square Dashboard → Locations

Give Claude these credentials

### Payments (Square)
- Application ID: `sq0idp-your-app-id`
- Sandbox Access Token: `your-sandbox-token`
- Location ID: `your-location-id`
- Environment: sandbox (switch to production when ready)
- Config stored in `square_config` table
- Edge function: `process-square-payment`
- Sandbox SDK: https://sandbox.web.squarecdn.com/v1/square.js
- Production SDK: https://web.squarecdn.com/v1/square.js

Then tell Claude

8. Stripe (Payments) Pay-as-you-go

Stripe handles ACH bank transfers (0.8% capped at $5), card payments (2.9% + 30¢), and outbound payouts to associates via Stripe Connect ($0.25/payout).

You do (in your browser)

1. Sign up at dashboard.stripe.com/register
2. Get your API keys at dashboard.stripe.com/apikeys:
   • Publishable key (starts with pk_test_ or pk_live_)
   • Secret key (starts with sk_test_ or sk_live_)
3. Set up a webhook at dashboard.stripe.com/webhooks:

   https://YOUR_PROJECT_REF.supabase.co/functions/v1/stripe-webhook

4. Subscribe to events: payment_intent.succeeded, payment_intent.payment_failed, transfer.paid, transfer.failed, account.updated
5. Copy the Webhook Signing Secret (starts with whsec_)
6. (Optional) Enable Stripe Connect for outbound associate payouts

Give Claude these credentials

### Payments (Stripe)
- Publishable key (test): `pk_test_...`
- Secret key (test): `sk_test_...`
- Publishable key (live): `pk_live_...`
- Secret key (live): `sk_live_...`
- Webhook signing secret: `whsec_...`
- Config stored in `stripe_config` table
- Edge functions: `process-stripe-payment`, `stripe-webhook`
- Deploy webhook with `--no-verify-jwt`
- Stripe.js v3: https://js.stripe.com/v3/

Then tell Claude

9. SignWell (E-Signatures) Free

You do (in your browser)

1. Sign up at signwell.com/sign_up (free: 3 docs/month, 25 with credit card)
2. Copy your API key at signwell.com → Settings → API
3. Add a webhook at signwell.com → Settings → Webhooks:

   https://YOUR_PROJECT_REF.supabase.co/functions/v1/signwell-webhook

4. Subscribe to the document_completed event

Give Claude these credentials

### E-Signatures (SignWell)
- API key: `your-signwell-api-key`
- API base: https://www.signwell.com/api/v1
- Auth: X-Api-Key header
- Config stored in `signwell_config` table
- Deploy webhook with `--no-verify-jwt`

Then tell Claude

10. Google Gemini (AI Matching) Free

Optional. Useful for fuzzy matching (e.g., matching bank transaction sender names to tenants).

You do (in your browser)

1. Get a free API key at aistudio.google.com/apikey

Give Claude these credentials

### AI Matching (Google Gemini)
- API key: `your-gemini-key` (store as Supabase secret: GEMINI_API_KEY)

Then tell Claude

11. Cloudflare R2 (Object Storage) Free

Optional. S3-compatible object storage with 10 GB free and zero egress fees. Great for documents, manuals, PDFs, and media that don’t need Supabase Storage’s RLS.

You do (in your browser)

1. Sign up at dash.cloudflare.com/sign-up (free, no credit card)
2. Go to R2 Object Storage in the left sidebar → Create bucket
3. Name your bucket (e.g., your project name), choose a region, click Create bucket
4. In bucket Settings, enable Public Development URL (allows public read access via a pub-*.r2.dev URL)
5. Go to R2 Object Storage → Manage R2 API Tokens → Create API token
6. Give it Object Read & Write permission, apply to your bucket, create the token
7. Copy the Access Key ID and Secret Access Key (shown only once!)

Give Claude these credentials

### Cloudflare R2
- Account ID: `your-cloudflare-account-id` (from the R2 dashboard URL or Overview page)
- Bucket name: `your-bucket-name`
- Public URL: `https://pub-xxxx.r2.dev` (from bucket Settings → Public Development URL)
- Access Key ID: `your-access-key`
- Secret Access Key: `your-secret-key`

Then tell Claude

12. Background Workers (Optional)

Some features need always-on processes that can’t run in the browser or in Supabase Edge Functions. These run on a cloud VM (any provider: DigitalOcean, Google Cloud, Hetzner, etc.).

What runs here

• Automated bug fixer — polls for bug reports, runs Claude Code to fix them, commits, merges
• Feature builder — picks up feature requests, implements them autonomously
• Device pollers — Tesla vehicles (every 5 min), LG washer/dryer (every 30s)
• AI image generation — polls job queue, calls Gemini API, uploads results
• Camera PTZ proxy — relays pan/tilt/zoom commands to cameras via home server
• Reverse proxy — Caddy for camera HLS streams, nginx for Sonos API relay

Typical sizing

You do

1. Spin up an Ubuntu VM on any cloud provider
2. Install Node.js 18+, Tailscale (if you have a home server), and Caddy/nginx as needed
3. Clone your repo and set up each worker as a systemd service
4. Workers query Supabase directly using the REST API or service role key

Then tell Claude

“Set up the background workers on my server at [IP]. Create systemd services for the bug fixer, device pollers, and image gen worker. Add SSH access details to CLAUDE.local.md.”

13. Custom Domain (Optional)

1. Buy a domain

If you don’t already own one, buy a domain from any registrar. Here are popular options:

• Namecheap — ~$9/year for a .com
• Cloudflare Registrar — at-cost pricing, no markup
• Squarespace Domains (formerly Google Domains) — ~$12/year

2. Tell GitHub about your domain

1. Go to your repo on GitHub
2. Click Settings → Pages (left sidebar)
3. Under Custom domain, type your domain (e.g., myapp.com) and click Save
4. GitHub will show a message that a DNS check is pending — that’s normal until you complete step 3

3. Point your domain to GitHub Pages (DNS settings)

This is the key step: you need to tell your domain registrar to send traffic to GitHub’s servers. The exact screens look a little different at each registrar, but you’re doing the same thing everywhere.

Find your DNS settings:

• Namecheap: Dashboard → click Manage next to your domain → Advanced DNS tab
• Cloudflare: Select your domain → DNS → Records
• Squarespace Domains: Domains panel → click your domain → DNS → DNS Settings

Add these records:

If your registrar already has default records (like parking page records), delete those first, then add the ones above.

4. Turn on HTTPS

1. Wait 5–30 minutes for DNS changes to propagate (sometimes up to 24 hours)
2. Go back to your repo’s Settings → Pages
3. The DNS check should now show a green checkmark
4. Check the box for Enforce HTTPS — GitHub provides a free SSL certificate automatically

How do I know it’s working?

Visit your domain in a browser. If you see your site, you’re done. If not:

• Double-check that you entered the A record IPs exactly as shown above
• Make sure you deleted any old/default DNS records that might conflict
• DNS changes can take up to 24 hours to fully propagate — wait and try again
• Use dnschecker.org to verify your records are visible worldwide

14. CLAUDE.md Templates

Claude Code uses two files for project context: CLAUDE.md (checked into the repo) for shareable project context, and CLAUDE.local.md (gitignored) for credentials and operator directives. Enter your project name and download both.

CLAUDE.md (checked in) includes:

• Project overview and tech stack
• Architecture and key files
• Database schema and common patterns
• Deployment workflow (push to main = live)
• External systems overview (no credentials)
• Coding conventions

CLAUDE.local.md (gitignored) includes:

• Operator directives (push immediately, direct DB access, version bumping)
• Supabase project ref, URL, psql connection string
• Live URLs (GitHub Pages)
• External service credentials: Resend, Telnyx, Square, SignWell
• Server access (cloud VM SSH, worker configuration)

15. Day-One Checklist

You do (in your browser)

Core Stack — Free:

• Create GitHub account and repository
• Enable GitHub Pages on the repo
• Create Supabase account and project
• Copy: project ref, anon key, DB password, and session pooler connection string

User Login — Free (Google OAuth):

• Create Google Cloud project
• Set up OAuth consent screen (publish when ready)
• Create OAuth client ID (Web application)
• Add Supabase callback URL as authorized redirect URI
• Enable Google provider in Supabase Auth settings
• Copy: Client ID, Client Secret

Email — Free (Resend):

• Create Resend account
• Verify your domain (or use onboarding@resend.dev)
• Copy: API key

SMS — Pay-as-you-go (Telnyx):

• Create Telnyx account, add payment method
• Buy a phone number (~$1/month)
• Create Messaging Profile, assign number, set webhook URL
• Register for 10DLC (mandatory for US — do early, approval takes time)
• Copy: API key, Messaging Profile ID, phone number

Payments — Free until you process (Square):

• Create Square developer account and application
• Copy: Application ID, sandbox access token, location ID

Payments — Free until you process (Stripe):

• Create Stripe account at stripe.com
• Set up webhook endpoint, subscribe to payment + transfer events
• Copy: publishable key, secret key, webhook signing secret

E-Signatures — Free tier (SignWell):

• Create SignWell account
• Set up webhook URL in Settings
• Copy: API key

Optional:

• Custom domain for GitHub Pages
• Google Gemini API key (aistudio.google.com)
• Discord developer application + bot token

Then tell Claude

Once you've given Claude your credentials, tell it to set everything up. You can either use the setup skill or paste this prompt:

Or just type /setup-alpacapps-infra in Claude Code — the skill walks through the same setup interactively, asking what services you need as it goes.

Claude handles everything from there — creating tables, writing edge functions, deploying, setting secrets, committing, and pushing. You never need to touch the terminal yourself.

16. Mobile App (iOS & Android) Free to develop

The mobile app wraps the same web codebase in a native shell using Capacitor 8. Residents get a native app experience (home screen icon, push notifications, no browser chrome) while you maintain a single codebase.

How It Works

Capacitor takes your existing web code, loads it inside a native WebView, and gives you access to native device APIs (push notifications, camera, status bar) through JavaScript plugins. There's no need to learn Swift or Kotlin — your web skills are all you need.

Tech Stack

Development Tools

On the Phone

On iOS, the app runs inside Apple's WKWebView (same engine as Safari). On Android, it uses the system WebView powered by Chromium. Both provide near-native performance for web content.

Build & Deploy

Claude Code handles the build process. The workflow is:

1. Build web assets — A script (copy-web.js) copies your web files into the mobile project, injects capacitor.js, and patches any redirect-based navigation
2. Sync to native — npm run sync from the mobile/ directory copies web assets into the iOS and Android native projects
3. Run on device — Open Xcode (iOS) or Android Studio (Android) and press Play

# From the mobile/ directory:
npm run sync          # Build + sync to both platforms
npm run open:ios      # Open Xcode — press Play to run
npm run open:android  # Open Android Studio — press Run

Key Design Decisions

• Single codebase — Web and mobile share the same data services (shared/services/). Write once, runs on web + iOS + Android
• No framework required — Vanilla JS with CSS-based tab switching. No React Native, no Flutter, no Swift/Kotlin to learn
• Lazy-loaded tabs — Each tab module loads on first visit via dynamic import(), keeping startup fast
• OTA updates — After the initial App Store submission, code changes (HTML/CSS/JS) can be pushed live instantly via Capgo — no App Store review wait
• Inline login — Capacitor WebView can't handle multi-page redirects, so the mobile app uses an inline login form instead of a separate login page