Skip to content

Installation & Setup Guide

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
Build Backend sam build
Deploy to TEST task deploy:test
Lint Everything task lint

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