AlpacApps Infra

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 all prerequisites (Mac — one command)

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/

Claude Code is the AI developer that powers everything. You need it installed before setting up Conductor (Step 4), which is where you’ll do all your actual work.

You do (one time)

1. Sign up for Claude Pro ($20/month recommended — free week here)
2. Download the Claude desktop app — Claude Code is built in
3. Open the app and verify Claude Code is accessible (click the Code tab in the top right)

That’s it for now — you’ll use Claude Code through Conductor (Step 4), which gives you a much better workflow with parallel agents and workspace management.

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

Tell Claude Code your two credentials

These are the only two things Claude can’t get on its own. Enter them here and hit Copy — Claude Code will log into Supabase, link your project, and fetch everything else (API keys, URLs, connection strings) automatically.

Copy this into Claude Code

This auto-fills as you type above. Click Copy, paste into Claude Code, and it handles the rest.

Set up Supabase for my project.

My project ref is: ___
My database password is: ___

Log into the Supabase CLI (supabase login), link my project (supabase link --project-ref), then fetch the project URL and anon key from the API settings automatically. Install the CLI if it's not already installed. Create the core database tables for [describe your app here], enable RLS on all tables, create storage buckets for photos and documents, commit, and push.

Don't ask me for permission at each step — just do the work end to end and show me the results when you're done.

Conductor is where you’ll do all your work. It’s a Mac app that runs multiple Claude Code agents in parallel — each in its own workspace with its own branch. Instead of working in a single Claude Code session, you manage everything from Conductor.

1. Install Conductor

1. Download from conductor.build
2. Open Conductor and point it at the project folder you cloned in Step 1

2. Create your first workspace and run the setup wizard

1. Create a new workspace in Conductor (name it something like “setup”)
2. In that workspace, type:

   /setup-alpacapps-infra

3. The wizard will configure your project based on the profile you picked above — pruning unused modules, creating database tables, and pushing everything

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

3. How to work with Conductor going forward

After the setup wizard finishes, this is how you build with Conductor:

1. One task per workspace. Want to add a payments page and fix a bug? Create two workspaces and run them in parallel.
2. Each workspace gets its own git branch so agents never conflict with each other.
3. Just tell it what you want in plain English. Paste credentials, describe features, ask questions — the agent handles the code.

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 paste the credentials into a Conductor workspace
3. Claude handles everything else — updates 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.

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

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

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

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

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

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

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

S3-compatible object storage with 10 GB free and zero egress fees. The setup wizard creates two R2 buckets automatically using your Cloudflare Global API Key:

• <project>-media — Images, documents, uploads
• <project>-backups — Database exports, config snapshots

If you prefer manual setup:

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. Create two buckets: <project>-media and <project>-backups
4. In the media 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 both buckets, 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

The setup wizard creates two D1 databases automatically using your Cloudflare Global API Key:

• <project>-sessions — Claude session transcripts with search/filtering (browsable in DevControl Sessions tab)
• <project>-devcontrol — Task tracking, build logs, deployment history

Both use free tier (5M reads/day, 100K writes/day, 5 GB storage). If you prefer manual setup:

You do (in your terminal)

1. Wrangler is installed by the prerequisite script. If missing: npm install -g wrangler
2. Authenticate: wrangler login
3. Create both D1 databases:

   npx wrangler d1 create <project>-sessions
   npx wrangler d1 create <project>-devcontrol

   Copy both database_id values from the output.
4. Edit cloudflare/claude-sessions/wrangler.jsonc — replace YOUR_DATABASE_ID_HERE with your database ID
5. Run the schema:

   cd cloudflare/claude-sessions
   npx wrangler d1 execute claude-sessions --file=schema.sql --remote

6. Choose an auth token (any secret string) and edit src/index.js — set AUTH_TOKEN
7. Deploy the Worker:

   npx wrangler deploy

   Note the Worker URL from the output.

Give Claude these credentials

### Cloudflare D1 Session Archive
- Worker URL: `https://claude-sessions.YOUR-SUBDOMAIN.workers.dev`
- Auth token: `your-chosen-token`

Then tell Claude

Optional. Open-source CLI that supercharges Claude Code with powerful skills: headless browser for QA testing (~100ms per command), code review, ship workflow, engineering retrospectives, and more. By Garry Tan, MIT licensed.

Skills included

• /browse — Headless browser for QA testing and site dogfooding
• /review — Pre-landing code review with production risk detection
• /ship — Ship workflow: sync base, test, review diff, bump version, push, create PR
• /qa — Systematic QA testing with auto-fix (Quick / Standard / Exhaustive)
• /qa-only — QA report without fixes
• /retro — Engineering retrospectives with per-person commit analysis
• /plan-ceo-review — CEO/founder-mode plan review
• /plan-eng-review — Engineering manager plan review
• /document-release — Post-ship documentation updates

You do (in your terminal)

1. Install gstack:

   curl -fsSL https://raw.githubusercontent.com/garrytan/gstack/main/install.sh | bash

2. Verify:

   ls ~/.claude/skills/gstack/SKILL.md

   If the file exists, you’re set. Claude Code auto-detects the skills.

Then tell Claude

Updating: Run /gstack-upgrade inside Claude Code, or re-run the install script.

Source: github.com/garrytan/gstack

Some features need always-on processes that can’t run in the browser or in Supabase Edge Functions. These run on a cloud VM (recommended: Hostinger VPS $5–12/mo, or any provider).

What runs here (11 workers)

• 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), Blink cameras (snapshots)
• Camera event poller — UniFi Protect smart detection events → SMS alerts
• AI image generation — polls job queue, calls Gemini API, uploads results
• Spirit whisper worker — PAI daily whisper scheduler & delivery
• Live subtitles — real-time speech-to-text + translation server
• PAI Discord bot — bridges Discord community server to PAI AI assistant
• Project inquiry worker — Gemini Vision + Brave Search for research tasks
• Instruction runner — watches for instruction files from mobile Claude Code
• Reverse proxy — Caddy for camera HLS streams, OpenClaw chatbot gateway

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.”

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

Claude Code reads CLAUDE.md at the start of every conversation. To keep this fast and efficient, we use an on-demand context loading pattern: CLAUDE.md stays slim (~30 lines) and indexes separate docs/*.md files that Claude only loads when the task requires them.

Why this matters

A monolithic CLAUDE.md with credentials, schema, patterns, and integrations can easily reach 200+ lines — thousands of tokens loaded into every conversation whether needed or not. With on-demand loading, a conversation about Tailwind styling only loads docs/PATTERNS.md, while a database migration only loads docs/SCHEMA.md and docs/CREDENTIALS.md.

File structure

How the index works

The top of CLAUDE.md contains trigger hints that tell Claude which doc to load for which task:

> **On-demand docs — load when the task matches:**
> - `docs/CREDENTIALS.md` — **load for:** SQL queries, deploying functions, SSH, API calls
> - `docs/SCHEMA.md` — **load for:** writing queries, modifying tables, debugging data
> - `docs/PATTERNS.md` — **load for:** writing UI code, Tailwind styling, code review
> - `docs/KEY-FILES.md` — **load for:** finding files, understanding project structure
> - `docs/DEPLOY.md` — **load for:** pushing, deploying, version questions
> - `docs/INTEGRATIONS.md` — **load for:** external APIs, vendor setup, pricing
> - `docs/CHANGELOG.md` — **load for:** understanding recent changes

Profile-aware context

The wizard generates different context files based on your profile:

• General AI Enablement: CLAUDE.md with 4 doc references and 3 code guards (~20 lines). Only core docs are generated. A .claudeignore file excludes property-management code from Claude’s search scope, saving thousands of tokens per conversation.
• Property Management: CLAUDE.md with all 7 doc references and full code guards (~35 lines). All docs are generated including KEY-FILES, INTEGRATIONS, and CHANGELOG.

See docs/CLAUDE-TEMPLATE.md for the exact templates and feature-manifest.json for the file-to-feature mapping that drives pruning.

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
• Download and install Conductor from conductor.build

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.

Fully native mobile apps for iOS and Android. Each platform uses its native UI toolkit for the best possible experience — SwiftUI on iOS, Jetpack Compose on Android.

How It Works

Both apps connect to the same Supabase backend and Home Assistant APIs as the web app. Each is built with platform-native tools for smooth performance and idiomatic UI.

Tech Stack

App Screens

Development Tools

Build & Deploy

Claude Code handles the build process. Each platform builds independently:

1. iOS — Open mobile-ios/AlpacaPlayhouse.xcodeproj in Xcode, press Play to build and run on simulator or device
2. Android — Open mobile-android/ in Android Studio, press Run to build the APK and deploy
3. Kiosk (Android) — A separate alpaca-kiosk/ project provides a lockdown kiosk mode with device admin, boot receiver, photo booth, and HTTP API server

Key Design Decisions

• Fully native — SwiftUI (iOS) and Jetpack Compose (Android) for platform-idiomatic UI, smooth 60fps animations, and full native API access
• Shared API layer — Both apps connect to the same Supabase backend and HAOS APIs, keeping data in sync with the web app
• Brand theming — Both apps use the same brand color tokens (accent gold, warm backgrounds) defined in their respective theme files
• Kiosk variant — A dedicated Android kiosk app (alpaca-kiosk/) with device admin lockdown, guest book photo booth, and HTTP API for remote control
• macOS kiosk — A Swift Package (oldmackiosk/) for legacy Mac kiosk displays with screen lockdown, audio management, and JS bridge