Skip to content

Installation & Setup Guide

What is this?

The step-by-step technical guide to bootstrapping the ChatKcal development environment, from prerequisites to the task setup command.

This guide outlines the steps required to set up the ChatKcal development environment from scratch.

🛠️ Prerequisites

Before you begin, ensure you have the following tools installed:

  • Node.js & Bun: Lightning-fast package management. Install Guide.
  • Python 3.12+ & uv: Python tool and script management. Install Guide.
  • AWS CLI: Backend deployment and AppSync evaluation. Install Guide.
  • AWS SAM CLI: Serverless backend building and deployment. Install Guide.

🚀 One-Command Setup

We use Go Task to automate our workflow. Once you have bun and uv installed, you can bootstrap the entire project with a single command:

# Install the Task runner if you don't have it
uv tool install go-task-bin

# Run the project setup
task setup

What task setup does:

  1. Installs root Node.js dependencies (including node-jq for local AppSync evaluation).
  2. Installs frontend dependencies.
  3. Ensures the Task runner and pre-commit hooks are installed and configured via uv.

📂 Project Structure

  • /appsync: JavaScript resolvers for AWS AppSync.
  • /frontend: React (Vite + Tailwind) application.
  • /graphql: GraphQL schema definitions.
  • /docs: Project documentation (this site).
  • /scripts: Python and Shell utility scripts.

🧪 Verifying the Setup

To ensure everything is working correctly, run the full test suite:

task test

This will run:

  • Backend Tests: Vitest logic tests for resolvers.
  • AppSync Evaluation: Verifies resolvers against the real AWS runtime engine.
  • Frontend Tests: Component and utility tests.

🛠️ Common Commands

Task Command
Start Frontend task dev
Serve Docs task docs
Start Both (PM2) task pm2:start
Check PM2 Status task pm2:status
Stop PM2 Apps task pm2:stop
Build Backend sam build
Deploy to TEST task deploy:test
Lint Everything task lint

PM2 commands use a repo-local PM2_HOME=.pm2 so process state and logs stay isolated per worktree.

🔐 Environment Variables

The frontend requires specific environment variables to connect to AWS. These are stored in frontend/.env.

See the Multi-Environment Strategy for details on switching between TEST and PROD.