Labs ASP Quick Setup Guide

Welcome! This guide will help you get the Labs ASP project running on your computer. The database is already set up in the cloud, so you'll just be connecting to it.

What You'll Have After Setup

• AI Chatbot Client: A Next.js-based AI chatbot with web automation capabilities
• Web Automation: AI that can visit websites, interact with pages, and extract information using a browser tool
• Database: A cloud database with sample participant data for testing
• Browser Streaming: Real-time browser session viewing through Kernel.sh

Project Structure

This repository contains the infrastructure, deployment configuration, and supporting services for the Labs ASP project. The AI chatbot client lives in a separate repository and is included here as a Git submodule.

Client Submodule

The client/ directory is a Git submodule that pulls from the navapbc/ai-chatbot repository (develop branch). This is where the application code lives. It contains:

• Next.js application — the full AI chatbot frontend and API routes
• AI tools — browser automation, participant lookup, and other agent tools
• Database schema & migrations — Drizzle ORM schema for chats, users, documents, and participants
• Artifacts system — browser session viewer, code runner, and other interactive artifacts
• UI components — chat interface, sidebar, markdown rendering, and design system

Root Repository

The root repository provides:

• terraform/ — Infrastructure-as-code for GCP deployment
• scripts/ — Utility scripts for deployment and maintenance
• docs/ — Architecture documentation, setup guides, and decision records

Prerequisites

You'll need these installed on your computer:

• Node.js (version 20 or higher): Download here
• pnpm: Install by running: npm install -g pnpm
• gcloud CLI (optional): Install instructions — Only needed if working with GCP resources directly

Note: We use the develop branch as our primary working branch. Make sure to checkout develop after cloning.

Step-by-Step Setup

1. Get the Code with Submodules

This project uses Git submodules to manage the client frontend. You'll need to clone with submodules or set them up after cloning.

Option A: Clone with Submodules (Recommended)

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/navapbc/labs-asp.git
cd labs-asp

# Switch to the develop branch (our primary working branch)
git checkout develop

Option B: If You Already Cloned Without Submodules

# If you already cloned the repo, initialize submodules
git submodule update --init --recursive

Important: The client/ directory is a Git submodule that tracks the develop branch of the ai-chatbot repository.

2. Opening Terminal in Visual Studio Code

If you're using Visual Studio Code:

1. Open the project folder: Go to File > Open Folder and select the labs-asp directory
2. Open the terminal:
   • Use the keyboard shortcut: Ctrl+(backtick) on Mac
   • Or go to Terminal > New Terminal in the menu
   • Or use View > Terminal

The terminal should automatically open in the correct labs-asp directory. You can verify this by running pwd (on Mac) to see your current directory path.

3. Install Dependencies

# Navigate to the client directory and install packages
cd client
pnpm install

4. Set Up Environment Variables

You'll need to create a configuration file for the client. Ask your team lead for access to the 1Password secure notes containing the actual values.

Client .env.local file

cp client/.env.example client/.env.local

Then update the values with the contents from the 1Password secure note for the client environment.

Vertex AI Credentials

touch vertex-ai-credentials.json

Copy the service account JSON from the 1Password secure note. See docs/VERTEX_AI_ANTHROPIC_SETUP.md for details on creating your own credentials if needed.

Warning about 1Password: When copying from 1Password secure notes, ensure you're copying the raw text and not a markdown-rendered version. 1Password can convert files to markdown, which breaks commented lines (e.g., # comment becomes a heading). If you encounter unexpected behavior, verify your file contents match the original format.

5. Database Connection

Important: The database is already set up and populated with test data! As a team member, you only need to connect to it. Please don't run migration or seeding commands, these are reserved for admins to avoid accidentally modifying shared data.

The database is ready to use with sample participant data already loaded. You'll be able to see this data once you start the app!

6. Start the App

# From the client directory
cd client
pnpm dev

This starts the Next.js client at http://localhost:3000.

Success! The app should now be running. Click the URL in your terminal to open it!

What Can You Do Now?

Try the AI Chatbot

• Web Automation: Have the AI visit websites, fill out forms, and take screenshots
• Participant Lookup: Search for participant information in the database
• Browser Sessions: Watch the AI interact with websites in real time

Sample Prompts to Try

• "Visit google.com and take a screenshot"
• "Look up participant information for John Doe"
• "Go to benefits.gov and find information about WIC eligibility"

View Your Database

# Open database browser (from the client directory)
cd client
pnpm db:studio

This opens a web interface at http://localhost:5555 where you can browse the shared participant data (read-only).

If Something Goes Wrong

App Frontend Errors or Won't Start

If the app displays errors or becomes unresponsive:

1. Stop the current process:

   • In your terminal, press Ctrl+C (Mac) to stop the running process
   • If that doesn't work, close the entire terminal session:
     • In VS Code: Click the trash can icon in the terminal panel, or right-click the terminal tab and select "Kill Terminal"

2. Start fresh:

   • Open a new terminal (see "Opening Terminal in Visual Studio Code" above)
   • Navigate to the client: cd labs-asp/client
   • Restart the app: pnpm dev

3. If problems persist:

   • Try clearing the cache and reinstalling: rm -rf node_modules && pnpm install
   • Check that all environment variables are correctly set in your client/.env.local file

Database Connection Issues

• Make sure you have the correct DATABASE_URL in your client/.env.local file
• Contact your team lead if you're getting database connection errors

Missing API Keys

• Contact your team lead for the required API keys
• Make sure they're properly copied into your client/.env.local file

Need Fresh Data?

Contact your team lead if you need the database refreshed — regular team members shouldn't modify the shared database.

Quick Reference Commands

# Start the app
cd client && pnpm dev

# View database (read-only)
cd client && pnpm db:studio

# Update submodule to latest
git submodule update --remote client

Git Submodule Management

This project uses Git submodules to manage the client frontend. The client/ directory is a submodule that tracks the develop branch of the ai-chatbot repository.

Initial Setup (One-Time Configuration)

Set up Git to automatically handle submodules and create a convenient alias:

# Configure Git to automatically handle submodules in most operations
git config --global submodule.recurse true

# Create an alias for pulling with submodules
git config --global alias.spull "pull --recurse-submodules"

Daily Workflow Commands

# Pull latest changes from both main repo and submodules
git spull

# Alternative: Pull with submodules (if you don't have the alias)
git pull --recurse-submodules

# Update submodule to latest commit from its remote branch
git submodule update --remote client

# Check submodule status
git submodule status

# Initialize submodules if they're missing
git submodule update --init --recursive

Working with Submodules

After a PR is Merged

When PRs are merged into the main repository, always pull with submodules:

git spull  # Pulls both main repo and submodule changes automatically

If You Need to Update the Submodule Reference

Sometimes you'll need to update the main repository to point to a newer commit in the submodule:

# Update submodule to latest remote commit
git submodule update --remote client

# Add and commit the submodule reference update
git add client
git commit -m "chore: update client submodule to latest commit"
git push

Checking Submodule Configuration

You can view the submodule configuration in .gitmodules:

cat .gitmodules

This shows how the submodule is configured to track the develop branch.

Troubleshooting Submodules

Submodule Directory is Empty

git submodule update --init --recursive

Submodule is Out of Date

git submodule update --remote client

Reset Submodule to Match Main Repository

git submodule update --recursive

View What Branch the Submodule is Tracking

git config -f .gitmodules --get submodule.client.branch

Admin-Only Commands

Note: These commands are for admins only and will modify shared data:

# Add sample data (admin only)
pnpm seed:wic

# Reset everything (admin only)
pnpm db:reset

# Create migrations (admin only)
pnpm db:migrate

Learn More

• Client Repository: navapbc/ai-chatbot
• Detailed Database Guide: See docs/DATABASE_SETUP.md
• Architecture Docs: See the docs/ directory for detailed guides
• Need Help?: Ask your team lead or create an issue