Amp Demo App

This repository is a carefully crafted demo that showcases the capabilities of Amp, centered around an example e-commerce platform featuring a FastAPI backend and a React frontend. Data is stored in SQLite, so it is self-contained and easy to run.

For more information about Amp visit the Amp manual.

How to use this repo

Follow the Quick Start guide to get started. Once the front and back ends are running (with the just dev command), then you can open your browser on one side of the screen with Amp up on the other (in VS Code or the CLI).

See the DEMO.md for more information about how to effectively use this repo for an array of different demo purposes ranging from issue to PR to advanced feature adds.

Project Structure

.
├── .devcontainer/      # VS Code Dev Container configuration
├── .github/            # GitHub workflows and CI configuration
├── backend/            # FastAPI backend
│   ├── app/            # Application source code
│   ├── tests/          # Backend tests
│   ├── alembic/        # Database migrations
│   ├── pyproject.toml  # Python dependencies (managed by uv)
│   ├── pytest.ini      # Test configuration
│   ├── main.py         # FastAPI entry point
│   ├── AGENTS.md       # Agent documentation for backend
│   └── store.db        # SQLite database file
├── frontend/           # React frontend (TypeScript/Vite)
│   ├── src/            # React components and pages
│   │   ├── api/        # API client and types
│   │   ├── components/ # Reusable UI components
│   │   ├── context/    # React Context providers
│   │   ├── hooks/      # Custom React hooks
│   │   ├── mockDB/     # Mock data for development
│   │   ├── pages/      # Page-level components
│   │   └── theme/      # Chakra UI theme configuration
│   ├── e2e/            # Playwright E2E tests
│   ├── public/         # Static assets
│   ├── package.json    # Node.js dependencies
│   ├── vite.config.ts  # Vite configuration
│   ├── eslint.config.js # ESLint configuration
│   ├── AGENTS.md       # Agent documentation for frontend
│   └── playwright.config.ts # Playwright test configuration
├── specs/              # Project specifications
├── logs/               # Service logs (dev-headless mode)
├── test-results/       # Test output and reports
├── justfile            # Development automation commands
├── package.json        # Root package.json for shared dependencies
├── settings.json       # Workspace settings
├── AGENTS.md           # Agent documentation for overall project
├── DEMO.md             # Demo usage guide
└── README.md           # README

Quick Start

Option 1: Dev Container (recommended)

The fastest way to get started! No local installation beyond Podman required. If you encounter any errors, get the logs and feed them into Amp to help resolve. If that doesn't work, please ask an SE.

What you need:

If you have any of these preinstalled, make sure to update them before proceeding!

• VS Code download

• Amp VS Code extension and/or CLI download

• Podman Desktop (download)

  • Once installed, open it up and follow through the prompts to install podman
  • When you get to the virtual machine setup, make sure you dedicate at least 4 cores and 10gb of RAM
  • Once installed and ready, you should see this in your Mac menu bar:

• VS Code Dev Containers extension

• Change the VS Code setting: "dev.containers.dockerPath": "docker" to "dev.containers.dockerPath": "podman"

  • Access settings in VS Code:
  • Type in the search box dev.containers.dockerPath
  • Change the box "Dev > Containers: Docker Path" from docker to podman:

• Homebrew (optional if you want to install the GitHub CLI) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• GitHub CLI gh (optional) if you would like to reference issues, push PRs, etc. directly from Amp brew install gh

Code Setup:

• Open VS Code
• Ensure VS Code Amp extension and/or Amp CLI are authenticated. You might need to authenticate the first time you bring up the devcontainer.
• Open the terminal:
• Enter the command below:

git clone https://github.com/sourcegraph/ecommerce-app.git

• From File -> Open Folder, open the ecommerce-app folder in VS Code:

• Authenticate to GitHub (optional)

gh auth login

• Click the remote window menu in the lower left corner:

• In the menu that pops up, select "Reopen in Container":

• Wait a few minutes, the first build takes a few minutes, then it will be cached and near instant in the future

• To start the demo app instances, either open the terminal and run just dev or ask Amp to start all services in the background

Access the application on your local browser (ports will automatically be forwarded):

• Frontend: http://localhost:3001
• Backend API: http://localhost:8001

Reverting Changes

As you work with this repo, you can revert any changes made by selecting all files changed and discarding them (indicated by a number showing in the source control sidebar:

The most foolproof way to reset is to delete the entire ecommerce-app repo and run git clone https://github.com/sourcegraph/ecommerce-app.git again.

Demo Flow

Once your setup is working and you can see the UI on http://localhost:3001. Go to the DEMO.md page to learn about the different demo modules to use.

In the future, to use this repo, just open VS Code, open the ecommerce-app folder, and click "Reopen in Container," and you should be ready to go.

What's Included in the Dev Container

Python 3.13, Node.js 22, all dependencies, Playwright browsers, GitHub CLI, Amp CLI, and all VS Code extensions pre-configured. Amp is set to run in Autonomous mode (most non-destructive commands allowed by default) with Playwright MCP Internal cost display is disabled.

See .devcontainer/README.md for detailed documentation and troubleshooting.

Option 2: Local Installation

For direct installation on your host machine:

1. Install Amp (VS Code extension and/or CLI)

2. Install the prerequisites and clone the project:

# Install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install just
brew install just

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Install python
uv python install 3.13 --default

# Install node
brew install node

# Install gh CLI and authenticate
brew install gh
gh auth login

# Install direnv for toolboxes to work
brew install direnv

# Verify you have the required tools
source $HOME/.local/bin/env
just --version
python --version
uv --version
node --version
direnv --version

git clone https://github.com/sourcegraph/ecommerce-app.git
cd ecommerce-app

3. Install dependencies and setup testing:

just install-all      # Install all dependencies (backend, frontend, E2E browsers)

4. Run the application:

just dev             # Start both services with native hot-reload using concurrently

Access the application:

• Frontend: http://localhost:3001
• Backend API: http://localhost:8001

Development Commands

Lifecycle Commands

just dev              # Start both services (native hot-reload, interactive)
just dev-headless     # Start both services in background (for agentic development)
just stop             # Stop headless services
just dev-backend      # Start only backend
just dev-frontend     # Start only frontend

Seed Database

just seed             # Populate database with sample data (only needed if database changes)

Manual Development (individual services)

Install dependencies (if not already done):

just install-all      # All dependencies (backend, frontend, E2E browsers)

Run services individually (if needed):

just dev-backend      # Start only backend
just dev-frontend     # Start only frontend

Testing & Quality

Setup E2E Testing (Required First Time)

just setup-e2e        # Install Playwright browsers

Running Tests

# Backend tests
just test-local                        # Backend tests
just test-local-single TEST            # Run single test

# E2E tests (Playwright)
just test-e2e         # E2E tests (headless)
just test-e2e-headed  # E2E tests (headed - for debugging)

# Combined test suites
just test-all-local   # All tests (backend + E2E)

Note: Frontend has no unit tests - only E2E tests with Playwright that test the full application.

Code Quality

# backend
just check            # Run linting (ruff) and type checking (mypy)

# formatting
just format           # Format backend (ruff) and frontend (prettier) code

# frontend
just lint             # Lint frontend TypeScript
cd frontend && npm run format:check  # Check frontend formatting without changes

Pre-Push Validation (Recommended)

Before pushing to CI, ensure all checks pass locally to avoid CI failures:

# One-time setup (if not done already)
just install-all      # Install all dependencies

# Run complete CI pipeline locally
just ci               # Runs: lint, tests, build, e2e (mirrors CI exactly)

just ci runs the exact same checks as the GitHub Actions CI pipeline:

1. Backend Quality: Ruff linting + MyPy type checking
2. Backend Tests: Full test suite with coverage
3. Frontend Quality: ESLint + TypeScript build
4. E2E Tests: End-to-end Playwright tests

Build & Deployment

just build            # Build frontend for production
cd frontend && npm run build  # Alternative frontend build

Database Management

just reset-db         # Reset SQLite database
just db-shell         # Open SQLite CLI
just migrate-create "message"  # Create new migration
just migrate-up       # Apply migrations
just migrate-down     # Rollback migration

Monitoring & Debugging

just health           # Check service health
just logs             # View last 100 lines from backend and frontend logs
just logs-follow      # Follow both logs live (Ctrl+C to exit)

Headless Development Workflow:
When using just dev-headless for agentic development, services run in the background and log to logs/backend.log and logs/frontend.log. Use just logs to inspect output and just stop to stop the services.

Source

Based on the ecommerce-demo repo.