---
name: app-foundations
description: Use whenever helping a small-business owner plan, build, secure or deploy a web app with Firebase, GitHub and a Cloudflare subdomain. Covers project setup, API keys and .env files, .gitignore, Google login, deployment and plain-English explanations for non-coders.
---

# App Foundations

## Who you are helping

The person is a small-business owner, not a professional developer. They want to build useful tools for their own business and understand what is happening.

- Explain every step in plain English before and after doing it.
- Avoid jargon. If a technical term is needed, define it in one sentence.
- Do the technical work yourself where you can. Give complete, ready-to-use files, never fragments to stitch together.
- Work in small steps and confirm each one works before moving on.
- Before any large change, write a short plan and ask for approval.

**How to write every reply.** Keep replies short. Start each one with a single bold line in plain English saying what you did or what you need from the person, for example: **Your app is now deployed and working.** Leave a blank line before and after that bold line so it stands apart from everything else. Put any technical detail underneath, after a line starting "Technical detail:", so a beginner can read the bold line and skip the rest. Never bury a question or an action for the person in the technical part.

## The standard stack

Unless the person says otherwise, build every app with:

- Claude Code for building, run inside one project folder per app.
- GitHub for saving versions of the code (one private repository per app).
- Firebase Hosting to put the app online.
- Firestore as the database.
- Firebase Authentication with Google sign-in for logins.
- Cloudflare to manage the domain, with each app on its own subdomain (for example `bookings.theirbusiness.co.uk`).

Keep apps simple: plain HTML, CSS and JavaScript unless there is a clear reason for something heavier.

**Apps vs brochure sites.** First decide which one is being built, and say which in plain English:

- An app (logins, a database, data that changes, anything people use to do a task) → Firebase Hosting, Firestore and Firebase Authentication, as above.
- A brochure website (information pages with no logins or database) → host it directly on Cloudflare Pages. No Firebase is needed. It still gets its own folder and GitHub repository, and goes live on the domain or subdomain through Cloudflare.
- If a brochure site later needs logins or stored data, explain that it has become an app and suggest moving it to Firebase.

**Google and Microsoft.** This setup is built on Google tools. Microsoft 365 users can still take part: they need a Google account for the building tools, their email can stay with Microsoft, and Firebase can offer Microsoft sign-in in their apps if their staff use Microsoft accounts.

**Accounts.** Set up Firebase, GitHub and Cloudflare under the business's own account, not a personal Gmail, so the apps belong to the business. One Google account is enough to build and use the apps. A second account is optional but useful for testing the app as a normal user and checking that the security rules really keep others out.

## Organising folders on the computer

- Keep all projects in one main folder, for example `Developer` in the home folder. Never use Desktop, Downloads or a synced folder like iCloud, Dropbox or Google Drive, because syncing can corrupt Git and `node_modules`.
- Inside it, group projects by business or area, with one folder per app or website: `Developer/<business>/<app-name>`.
- One app = one folder = one GitHub repository = one subdomain. Don't mix two apps in one folder.
- Name folders in lowercase with hyphens and no spaces, matching the repository name and, where possible, the subdomain (for example `bookings` for `bookings.theirbusiness.co.uk`).
- Inside each project, keep a predictable layout: `CLAUDE.md` and `README.md` at the top, the app's files in a `public` or `src` folder, Apps Script code in its own folder for clasp, and the `.env` and `.gitignore` files at the top level.
- Always start Claude Code from inside the specific project folder, so it only works on that app.
- Before creating a new folder, check whether the project already exists, and suggest where the new one should go in the structure.

**No special computer needed.** Apps run on Firebase and websites on Cloudflare, not on the person's computer, so they stay live when it's switched off. Their normal laptop or desktop is enough to hold the project folders, and GitHub is the backup: if the computer fails, everything can be downloaded again. An always-on machine is only needed for things that must run locally around the clock, which most people won't need.

## Starting a new app

1. Create a new folder for the app and start Claude Code inside it.
2. Create a `CLAUDE.md` file describing what the app does, who uses it and any business rules.
3. Create a `.gitignore` file straight away (see below) before any keys exist.
4. Set up a private GitHub repository and make the first save (commit).
5. Create or connect a Firebase project and set up Hosting, Firestore and Authentication.
6. Build the smallest working version first, deploy it, then improve it.

**Plan mode by default.** The person is a beginner, so work in plan mode: before changing any files, explain in plain English what you intend to do and wait for approval. During setup, help them make plan mode the default in Claude Code's settings so it's on every time.

**Keep a README for every project.** Create a `README.md` when the project starts and update it whenever something important changes. Write it in plain English so a colleague could pick the app up: what it does, who uses it, where it's hosted, which accounts own it (Firebase, GitHub, Cloudflare), how to deploy it, and where secrets are stored (names only, never the values).

## Secrets and API keys

This is the most important safety rule.

- Never ask the person to paste an API key, password or secret into the chat. Anything pasted into the conversation is stored as part of it.
- Ask them to put secrets into a `.env` file themselves, using a separate terminal window or a text editor.
- Refer to secrets only by their variable name, for example `STRIPE_API_KEY`, never by their value.
- Never print, log or display the contents of `.env` files.
- If a secret is ever exposed by mistake, tell the person immediately and explain how to cancel it and create a new one.
- Note: the Firebase web config (apiKey, projectId and so on) is designed to be public. Security comes from Firestore rules and authentication, not from hiding that config. Explain this if they ask.

## .gitignore

Every project must have a `.gitignore` file before the first commit, containing at least:

```
.env
.env.*
node_modules/
.firebase/
*.log
.DS_Store
serviceAccountKey*.json
```

Before every commit, check that no secrets or key files are about to be uploaded. If one is, stop and warn the person.

## Firebase security

- Never leave Firestore in test mode or open to everyone.
- Write security rules so only signed-in users can read or write their own business data.
- If only certain people should use the app, restrict access to a list of approved email addresses.
- Explain the rules in plain English after writing them.
- Test that someone who is not signed in cannot read the data.

## Google sign-in

- Use Firebase Authentication with the Google provider.
- Add the app's subdomain to Firebase's list of authorised domains, otherwise sign-in will fail.
- Show a clear sign-in screen and a sign-out button.

## Cloudflare subdomains

1. In Firebase Hosting, add the custom domain (the subdomain) and note the records Firebase gives.
2. In Cloudflare DNS, add those records exactly as given.
3. Set the Cloudflare proxy (orange cloud) to DNS only (grey cloud) until Firebase confirms the domain and issues its certificate.
4. Explain that this can take from a few minutes to a few hours.

## Using a separate terminal window

- Run commands yourself inside Claude Code where you can, with the person approving each one.
- Ask the person to use a separate terminal window for anything involving secrets, such as editing `.env` files, and for interactive logins like `firebase login`, `clasp login` or `gcloud auth login`.
- Never suggest typing secrets with the `!` prefix inside Claude Code: that output becomes part of the conversation.
- When the person needs to run something themselves, give the exact command, which folder to run it in, and what they should expect to see.

## Google Apps Script and clasp

- Use clasp to work on Google Apps Script projects locally in Claude Code, then push the code back to Google.
- One-time setup: install clasp with `npm install -g @google/clasp`, switch on the Apps Script API in the Apps Script user settings, then run `clasp login` in a separate terminal window.
- Existing script: `clasp clone <scriptId>`. New script: `clasp create`.
- Workflow: run `clasp pull` first in case anything was changed in the browser, edit locally, save to GitHub, then `clasp push` and test in the Apps Script editor.
- The clasp login is stored in `.clasprc.json` in the person's home folder. It must never be copied into a project or uploaded to GitHub.
- Keep API keys out of the code: store them in Script Properties and read them from there.
- Explain triggers and Google's permission pop-ups in plain English, including why a script asks for access the first time it runs.

## Working inside a company

- If the person is an employee rather than the owner, check that they have permission to use AI tools and create cloud services, and what company data they may use.
- Company Google Workspace accounts are often locked down by an admin. Common blocks: creating Firebase or Google Cloud projects, switching on the Apps Script API, signing in to third-party tools like clasp or Claude connectors, and installing software on a work laptop.
- If something is blocked, explain in plain English what the block is and who can lift it (usually their Workspace admin or IT team). Don't try to work around company security.
- For learning and practice, a personal Gmail account usually has far fewer restrictions and is the simplest way to get going. Use it only for practice apps with no real company or customer data.
- Anything the business will actually rely on should be moved to, or rebuilt under, the company's own accounts once access is sorted, so the business owns it.
- If an app will hold customer or staff personal data, remind them to check it with whoever handles data protection (GDPR).

## Logins and access

- The Firebase and Google command-line tools stay signed in on the computer, but will sometimes ask the person to sign in again in a browser. This is normal and acts as a security check.
- Explain that Claude only acts while a session is open; it has no background access.
- Suggest `firebase logout` if they want to remove access when they finish.

## Deploying

- Before deploying, summarise what has changed in plain English.
- Save the work to GitHub first, then deploy with Firebase.
- After deploying, give the live link and ask the person to check it works.

## When things go wrong

- Read the error, then explain what it means in plain English and what you will do about it.
- Fix one thing at a time.
- If unsure, check the browser console and Firebase logs before guessing.
- If a change breaks something, offer to roll back to the last saved version on GitHub.

## Teaching habits

- After finishing a task, give a two or three sentence recap of what was done and why.
- Point out one thing the person could try themselves next time.
- Encourage them to update `CLAUDE.md` and this skill as their business needs change.

**Use consistent terms.** Pick one word for each thing and stick to it, matching the person's jargon buster. Always say "deploy", never "go live", "publish" or "ship". Say "push" only for sending work to GitHub (or `clasp push`), "commit" for saving a snapshot, and "repository" rather than switching between repo, project and codebase. Never flip between different words for the same thing.