Underthe hood.
What happens
after the click?
A working app starts
with a working folder.
Your editor, terminal, Git, and hosting service all need to agree on where the project is. A clear structure helps you change the right files, find missing pieces, and reproduce a build on another machine.
A shelf for separate projects. Keep each site’s working folder easy to identify.
The app’s source, instructions, and configuration. This is the root in our example.
The tools read those files and produce the app. A tidy folder alone does not publish it.
Your computer / Projects /
Select a file or folder to look inside. This illustration does not read your computer.
The project's home base.
This example keeps one app inside one repository. Open this folder in your editor and use it as your terminal's starting location. Its package.json identifies the app and its commands.
Projects/my-website/package.jsonProjects is your organizer. my-website is the project root. Your organizer can have a different name or live on another drive.
Read the documentation ↗One workable structure, not a universal template. Other frameworks use different names. Some Next.js projects put application code inside src/; larger repositories can contain several apps.
Open the folder.
Then open the terminal.
- Create or clone the project. If it already lives on GitHub, clone it into your Projects folder. A clone is a local working copy, not a move away from GitHub.
- Open that project in your editor. Give your coding assistant the same project context. Read the README and any project instructions before changing files.
- Confirm the terminal location. An editor window and a terminal can be pointing at different folders. The path and package.json are your first checks.
- Follow the setup instructions. Use the required Node.js version and package manager, install dependencies, and configure local environment values. Then run the development server and check a build.
cd "$HOME/Projects/my-website"
pwd
lsYou should be inside my-website and see package.json. A full path identifies one location; a relative path starts from your current folder. Quote paths that contain spaces.
npm ciInstall from an existing, matching npm lockfile. This recreates node_modules.npm run devStart this example’s local development server. Open the URL it prints.npm run buildCheck the production build. Stop the dev command with Ctrl+C, or use another terminal in the same project.These examples assume Node.js/npm are installed and the shown scripts exist. A different project may use pnpm, Yarn, Bun, or another toolchain. Follow its README.
What npm ci does ↗Same code.
Different starting point.
Choose an example to see why the folder matters.
Projects/my-website/One project. The same source.
Your editor, terminal, and Git repository point at this app. The host builds the intended repository and branch, using the app's root directory.
What to doCheck the README, install the recorded dependencies, supply the required environment values, then run the project's checks. Correct folders are a foundation, not a guarantee that the code is bug-free.
Your computer → GitHub → Vercel.
Edit and test locally. Commit the intended source and lockfile, then push the reviewed branch to GitHub. With a Git integration configured, Vercel builds the chosen revision using the correct root and environment settings. Check the deployment and live URL. Saving a file, making a commit, and publishing are three different events.
Keep paths portable. Use project-relative paths or configured import aliases, not links to your personal Desktop. Match filename capitalization exactly; a mismatch can surface on the deployment machine.
Keep copies intentional. Use a clear active checkout and deliberate branches or worktrees. Keep unrelated downloads, exports, and private business documents outside the app’s working files.
Keep secrets separate. Commit the placeholder template, not live credentials. Configure production values with the host and use the key-placement lab below to understand the boundary.
Pick a chain reaction.
Someone requests a quote.
Follow one message from a form to a saved lead, an AI summary, and two notifications.
Current connection / 1
Break something.
Choose a fault, then follow the request to find what stops and what survives.
If the email fails,
did we lose the inquiry?
A well-designed system tracks each operation separately. Try a failure to see why the order of the connections matters.
Different jobs.
Connected possibilities.
Open a tool to see what it does, where its responsibility ends, and what you could make with it.
InterfaceYour browserThe front door
The part of a website you can see, tap, and type into.
The browser displays the interface and sends requests. Anything shipped to it can be inspected, including code and public configuration.
- Fill out a form
- Read a dashboard
- Upload a photo
A hidden button is not a permission check. The receiving service must enforce access.
DevelopmentYour workbenchWhere ideas become code
You, your editor, and a coding assistant working on the application.
Claude Code or Codex can help edit and test a project. Chatting in Claude or ChatGPT is another way to plan. Neither automatically adds an AI feature to your deployed site.
- Prototype an idea
- Investigate a bug
- Review and test a change
Review generated code and test the resulting behavior before shipping it.
DevelopmentGitHubCode + change history
A shared home for source code, recorded changes, and reviews.
A repository contains files and their history. Branches let you work on changes; pull requests let people review them. A connected host can deploy a chosen revision.
- Compare versions
- Review a pull request
- Recover an earlier implementation
Keep secret credentials out of commits. Private repositories are not secret managers.
HostingVercelThe running application
Delivers the website and runs its server-side application logic.
The application code coordinates services: validate an input, check permissions, save data, and call an API. Vercel hosts that code; it does not invent the connections for you.
- Preview a branch
- Publish a website
- Handle a form or webhook
Put privileged API calls behind server-side validation and authorization.
BackendSupabaseData, accounts + files
Stores application records, manages sign-ins, and holds uploaded files.
Postgres stores structured records; Auth identifies users; Storage holds file objects. Permissions decide which records and files each user can access.
- Build a customer portal
- Save preferences
- Store documents and photos
Publishable keys work with access policies. Secret keys bypass row-level security and stay on trusted servers.
IntelligenceClaude / OpenAIAn AI API call
Your application asks a model to interpret, summarize, or generate something.
Use Anthropic or OpenAI through their APIs. Send the task and relevant context; receive output your application checks before using. An AI API integration is separate from using a chat app or coding assistant.
- Summarize an inquiry
- Extract document fields
- Answer from supplied references
Model output can be wrong. Validate it and keep API credentials on the server.
CommunicationResendEmail delivery
Your application requests an email; Resend handles sending it.
Use a verified sending domain and a server-side API key. Delivery events can return to your application through webhooks.
- Send confirmations
- Deliver receipts
- Notify a team
Accepted for sending does not mean delivered. Record delivery events when they matter.
CommunicationTwilioTexts + phone calls
Connects an application with SMS, phone calls, and other communication channels.
Your app can request a message. Incoming messages and call events can trigger webhooks back to your app. Channel, sender, and regional requirements vary.
- Send opted-in reminders
- Handle incoming texts
- Build a phone workflow
Track consent and opt-outs. Validate incoming webhook signatures before acting.
CommerceStripePayments
Collects a payment through a checkout connected to your application.
Your server creates checkout using trusted prices. A verified payment event lets the application update an order or grant access.
- Sell a digital product
- Take a deposit
- Manage a subscription
A visit to a success page is not proof of payment. Verify the payment event and handle duplicates.
InfrastructureDomain / DNSFinding the address
DNS helps turn a human-readable domain into the address of a service.
A provider such as Cloudflare can manage DNS records. DNS lookup and optional proxying are different jobs. The domain name, DNS provider, and website host can be separate.
- Connect a custom domain
- Configure email records
- Point a subdomain at an app
DNS records can be cached. HTTPS certificates are another part of establishing a secure connection.
Automationn8nWorkflow automation
Runs a sequence of connected actions when an event occurs.
A workflow can receive an event, transform its data, and call other applications. Code in your application can perform these jobs too; an automation platform is an optional choice.
- Route incoming leads
- Sync records between tools
- Prepare a daily digest
Design retries to avoid duplicate messages or records. Limit each connection's permissions.
ObservabilitySentryErrors + diagnostics
Helps a team see application errors and investigate what happened.
An error report can include the failing operation and useful context. Developers use that evidence to reproduce and fix a problem.
- Spot failed requests
- Investigate regressions
- Follow an error to its source
Scrub secrets and personal data from reports. A monitoring alert does not fix the application.
AutomationScheduled jobThe alarm clock
Starts an application task at a configured time.
A scheduler such as Vercel Cron calls a protected endpoint. Your code finds due work, performs it, and records the result.
- Send appointment reminders
- Prepare a morning report
- Clean up expired records
Make jobs safe to retry and prevent overlapping runs from doing the same work twice.
IntelligenceMCP connectionTools an assistant can use
A standard way for an AI application to discover and use connected tools and context.
An MCP client communicates with a server that exposes capabilities. That server may call an existing API. MCP is a protocol, not a model, database, or replacement for access control.
- Look up an authorized record
- Read project context
- Connect an assistant to business tools
A discovered tool is not blanket permission to act. Scope access and require approval for consequential operations.
Chat with it. Use Claude or ChatGPT to think through an idea.
Build with it. Use a coding assistant to edit and test the project.
Put it in your app. Your running application calls a model API for a specific task.
What belongs where?
Pick a credential, then choose where to put it. Every value here is a dummy example.
sb_publishable_EXAMPLEA key is not a user's identity.
This identifies the public app. Database grants, row-level security, Storage policies, and the user's session control access. It is not an admin credential.
Read the Supabase key guide ↗Every call has a context.
Explore the arithmetic behind a new inquiry. Change the assumptions and watch the estimate respond.
Hypothetical USD rates for learning. These are not provider quotes. This models successful runs, independently of the failure simulator above.
- Fixed costs
- $20.00
- AI / 1000 calls
- $1.10
- Email / 1000 sends
- $1.00
- SMS / 1000 segments
- $20.00
Assumes one segment per text. Excludes free allowances, tier changes, taxes, carrier fees, phone numbers, retries, indexing, storage, bandwidth, and variable hosting or automation charges.
Show the calculation
Fixed costs + email sends × rate / 1,000 + SMS segments × rate + AI calls × (input tokens × input rate + output tokens × output rate) / 1,000,000 + paid orders × (order value × percentage / 100 + flat fee).
What would you build?
Each recipe opens a complete journey in the simulator.
A new inquiry
Follow one message from a form to a saved lead, an AI summary, and two notifications.
Explore the recipe ↗02 / BuildPublish a change
See the difference between writing code, saving a revision, reviewing a preview, and publishing it.
Explore the recipe ↗03 / BuildConnect an address
Separate the name you type, the DNS lookup, and the host that answers the request.
Explore the recipe ↗04 / UseA customer portal
Follow a sign-in, a permissions check, and a private file upload.
Explore the recipe ↗05 / UseAsk a document
Retrieve relevant passages, send them with a question, and return an answer with references.
Explore the recipe ↗06 / UseAn appointment reminder
A scheduled job finds due appointments and sends reminders through the chosen channels.
Explore the recipe ↗07 / UseA paid booking
Follow a checkout request and the verified event that turns a pending booking into a paid one.
Explore the recipe ↗08 / UseRoute an incoming text
An incoming SMS becomes a tracked request and an email to the right person.
Explore the recipe ↗09 / UseAn assistant uses a tool
See how an MCP connection exposes an authorized tool to an AI application.
Explore the recipe ↗The words between the wires.
Small explanations for the concepts that make the whole system click.
API request
One piece of software asks another to do something through a defined interface.
An HTTP API commonly uses a method, URL, headers, and optional body. The response carries a status and data. Requests can fail or time out.
Your app asks Resend to send a confirmation email.
Go deeper in the documentation ↗API key
A credential that identifies an application or grants it access to a service.
Keys have different scopes. Supabase publishable keys work with database policies; its secret keys bypass row-level security. A project key is not a user's identity.
The browser can use a Supabase publishable key; an AI provider secret stays on the server.
Go deeper in the documentation ↗Webhook
A service calls your application when an event happens.
The service sends an HTTP request to your configured endpoint. Verify its authenticity and handle duplicates and delayed delivery.
Twilio tells your app that a text has arrived.
Go deeper in the documentation ↗Browser vs. server
The browser runs on the visitor's device. Server code runs in infrastructure you control.
Browser code and bundled configuration are inspectable. Server endpoints still need input validation, authentication where applicable, and authorization.
The browser submits a form; a server function uses the secret email key.
Go deeper in the documentation ↗Environment variable
Configuration supplied to a running program instead of written directly into its source.
In Next.js, NEXT_PUBLIC_ variables are bundled for the browser. An environment variable is not automatically secret: exposure depends on how it is used.
RESEND_API_KEY is server configuration; it should never appear in a browser payload.
Go deeper in the documentation ↗Authentication vs. authorization
Authentication establishes who you are. Authorization decides what you may do.
A valid session alone does not grant access to every row. Database and Storage policies should restrict access to the user's intended records and objects.
Two customers can both sign in, but each sees their own project.
Go deeper in the documentation ↗Database vs. file storage
A database holds structured records. File storage holds objects such as photos and PDFs.
A database row can reference an object path and store ownership metadata. The row and the object need appropriate access rules and lifecycle handling.
A project row has an owner and status; its inspection photos live in Storage.
Go deeper in the documentation ↗Preview vs. production
A preview lets you check a change. Production is the version visitors use.
Environments can have separate URLs, configuration, and data. A preview is not safely isolated if it accidentally uses production credentials and records.
Review a new booking page before connecting it to real customers.
Go deeper in the documentation ↗Retry + idempotency
Try again after a failure without accidentally repeating the business action.
A stable operation ID and durable state help deduplicate retries. Idempotency support and retention windows differ by service.
Retry the receipt email without charging the customer again.
Go deeper in the documentation ↗Retrieval / RAG
Find relevant source material and give it to the model before asking for an answer.
Ingest and index documents, retrieve with permission filters, then supply selected passages as context. Check citations and allow an insufficient-evidence response.
Answer an inspection-date question using a passage from the customer's own project guide.
Go deeper in the documentation ↗MCP
A protocol for connecting AI applications with tools and context.
The host manages clients that connect to MCP servers. Servers expose capabilities and enforce access to their underlying systems. MCP is not a model or a blanket authorization grant.
An assistant looks up a booking through a narrowly scoped tool.
Go deeper in the documentation ↗Monitoring
Collect signals that help you see whether an application is working.
Errors, logs, and traces can reveal a failing operation. Scrub sensitive data and correlate events by request or release when possible.
An error report points to the release that broke a booking request.
Go deeper in the documentation ↗