From ed44d3544028785f5a1b03f5e842f3af04901167 Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
<159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:28:31 +0000
Subject: [PATCH 1/3] Changes
---
README.md | 130 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 85 insertions(+), 45 deletions(-)
diff --git a/README.md b/README.md
index 70b7c82..b9bdf62 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,113 @@
-# Welcome to your Lovable project
+# madewithlovable
-## Project info
+A step-by-step guide to de-risking your [Lovable](https://lovable.dev) project for production use.
-**URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID
+Lovable is excellent for agility and speed-to-market, but shipping AI-generated code to production without guardrails introduces structural risks — from unreviewed changes breaking infrastructure to vendor lock-in on hosting. This project provides a repeatable playbook to mitigate those risks while keeping the benefits of rapid AI-assisted development.
-## How can I edit this code?
+**Live app:** [made-with.lovable.app](https://made-with.lovable.app)
-There are several ways of editing your application.
+---
-**Use Lovable**
+## What This Is
-Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting.
+An interactive wizard that walks you through six steps to establish ownership, safety, and operational independence over a Lovable-built application. Each step is optional (except the first), so you can adopt only what makes sense for your project.
-Changes made via Lovable will be committed automatically to this repo.
+---
-**Use your preferred IDE**
+## The Six Steps
-If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.
+### 1. Project URL
-The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
+Enter your Lovable project URL. The wizard extracts the project UUID and uses it to generate context-aware links throughout the remaining steps (e.g., direct links to your project's GitHub settings, Knowledge configuration, etc.).
-Follow these steps:
+### 2. Connect to GitHub
-```sh
-# Step 1: Clone the repository using the project's Git URL.
-git clone
+Export your Lovable project to a GitHub repository. This is the foundation of everything else — without version control, you can't review changes, run CI/CD, or deploy independently. Lovable syncs commits bidirectionally, so you keep the AI editor workflow while gaining full Git history.
-# Step 2: Navigate to the project directory.
-cd
+### 3. Guardrails
-# Step 3: Install the necessary dependencies.
-npm i
+Add a `LOVABLE.md` file to your repository root that scopes what the AI is allowed to modify. This file acts as a contract: Lovable (and any other AI agent) should only touch application source code inside `src/`, frontend build configuration, and database migrations. Protected files include:
-# Step 4: Start the development server with auto-reloading and an instant preview.
-npm run dev
-```
+- Infrastructure (`Dockerfile`, `docker-compose.yml`, `terraform/`)
+- CI/CD pipelines (`.github/`)
+- The guardrails file itself (`LOVABLE.md`)
+
+The guardrails are enforced in two ways:
+1. **At authoring time** — by registering `LOVABLE.md` as custom knowledge in your Lovable project settings, so the AI respects the boundaries while generating code.
+2. **At merge time** — by the CI/CD pipeline's automated review (see Step 6).
+
+### 4. Local Development Setup
+
+Run the full application locally using Docker, independent of Lovable's preview environment. This enables:
+
+- Working in your preferred IDE or with other AI coding agents (Cursor, Claude Code, etc.)
+- Offline development
+- Running the test suite locally
+- Building production artifacts
+
+The setup is a single command: `docker-compose up`, which starts a development server on `localhost:8081` with hot-reloading and volume-mounted source code.
+
+### 5. Production Self-Hosting
-**Edit a file directly in GitHub**
+Decouple your production environment from Lovable's hosting. The guide covers:
-- Navigate to the desired file(s).
-- Click the "Edit" button (pencil icon) at the top right of the file view.
-- Make your changes and commit the changes.
+- **Creating a `production` branch** in GitHub to separate what's deployed from what's being developed.
+- **AWS S3 + CloudFront** as the hosting infrastructure (private S3 bucket as origin, CloudFront for delivery). Terraform configuration is provided, but manual setup via the AWS Console works too.
+- **Building and deploying** — running `npm run build` (locally or via Docker) and uploading the `dist/` folder to S3.
+- **Lovable Cloud (Supabase) considerations** — by default, self-hosted frontends share the same backend. For a dedicated production database, a manual migration to a managed Supabase instance is required.
-**Use GitHub Codespaces**
+**Key technical notes:**
+- CloudFront must have `index.html` set as the Default root object.
+- Lovable occasionally desyncs `package-lock.json` from `package.json`. If `npm ci` fails, use `npm install` and commit the updated lock file.
-- Navigate to the main page of your repository.
-- Click on the "Code" button (green button) near the top right.
-- Select the "Codespaces" tab.
-- Click on "New codespace" to launch a new Codespace environment.
-- Edit files directly within the Codespace and commit and push your changes once you're done.
+### 6. CI/CD Pipeline
-## What technologies are used for this project?
+Three GitHub Actions workflows automate the release process:
-This project is built with:
+| Workflow | Trigger | Purpose |
+|---|---|---|
+| `initiate-release.yml` | Manual (workflow_dispatch) | Creates a PR from `main` → `production` with an auto-generated changelog |
+| `ci-guardrails.yml` | PR to `production` | Claude reviews the diff against `LOVABLE.md` guardrails — approves and merges if clean, requests changes if violations are found |
+| `deploy.yml` | Push to `production` | Builds the app, syncs to S3, and invalidates the CloudFront cache |
-- Vite
-- TypeScript
-- React
-- shadcn-ui
-- Tailwind CSS
+**Required setup:**
+- Install the [Claude GitHub app](https://github.com/apps/claude) on your repository
+- Add the `ANTHROPIC_API_KEY` secret (from [Anthropic Console](https://console.anthropic.com/settings/keys))
+- Add AWS IAM credentials as secrets (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) with permissions for S3 and CloudFront
+- Add GitHub Actions **variables**: `S3_BUCKET` and `CLOUDFRONT_DISTRIBUTION_ID`
+- If using Lovable Cloud: add `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLISHABLE_KEY` as secrets
+- Enable "Allow GitHub Actions to create and approve pull requests" in your organization/repository settings
-## How can I deploy this project?
+**The release flow:**
+1. A non-technical user (or anyone) triggers the "Move main to production" workflow manually.
+2. Claude generates a release PR with a summary of changes.
+3. The guardrails workflow automatically reviews the PR diff — if all changes are within scope, it approves and merges. If guardrail violations are detected, it requests changes with inline comments.
+4. On merge to `production`, the deploy workflow builds and publishes to AWS.
-Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish.
+---
-## Can I connect a custom domain to my Lovable project?
+## Tech Stack
-Yes, you can!
+- [React](https://react.dev) + [TypeScript](https://www.typescriptlang.org)
+- [Vite](https://vitejs.dev)
+- [Tailwind CSS](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com)
+- [Framer Motion](https://www.framer.com/motion/) for step transitions
-To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
+---
+
+## Getting Started
+
+```sh
+git clone
+cd
+npm install
+npm run dev
+```
+
+Or with Docker:
+
+```sh
+docker-compose up
+```
-Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
+The app will be available at `http://localhost:8081`.
From 1efe7be4282ab80700e7c9c7007929f99d1cdc09 Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
<159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:29:09 +0000
Subject: [PATCH 2/3] Changes
---
README.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index b9bdf62..1e70bd9 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,8 @@ A step-by-step guide to de-risking your [Lovable](https://lovable.dev) project f
Lovable is excellent for agility and speed-to-market, but shipping AI-generated code to production without guardrails introduces structural risks — from unreviewed changes breaking infrastructure to vendor lock-in on hosting. This project provides a repeatable playbook to mitigate those risks while keeping the benefits of rapid AI-assisted development.
-**Live app:** [made-with.lovable.app](https://made-with.lovable.app)
+- **Lovable-hosted:** [made-with.lovable.app](https://made-with.lovable.app)
+- **Self-hosted (AWS):** [d12vini1os6dc2.cloudfront.net](https://d12vini1os6dc2.cloudfront.net)
---
From ac66e1acc491dea6bfbbfe606ad90db6da58979c Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
<159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:51:00 +0000
Subject: [PATCH 3/3] Changes
---
src/components/steps/StepProjectUrl.tsx | 19 ++++++++++++++++---
1 file changed, 16 insertions(+), 3 deletions(-)
diff --git a/src/components/steps/StepProjectUrl.tsx b/src/components/steps/StepProjectUrl.tsx
index 3fcbb09..5758d7d 100644
--- a/src/components/steps/StepProjectUrl.tsx
+++ b/src/components/steps/StepProjectUrl.tsx
@@ -41,9 +41,22 @@ export function StepProjectUrl() {
✓ Valid project detected