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 task dev:session:detached
PM2 Status task pm2:status
Build Backend sam build
Deploy to TEST task deploy:test
Lint Everything task lint

task docs now starts from http://127.0.0.1:8010, and the PM2 combined session keeps docs on the same port while leaving the app on http://127.0.0.1:5173.

🔐 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.