Prerequisites¶

Required for All Users¶

Docker and Docker Compose¶

Docker is required to run the full application stack.

macOSLinuxWindows

# Install Docker Desktop
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

Download and install Docker Desktop for Windows.

Verify installation:

docker --version
docker compose version

AI Provider Setup¶

The application uses Google Gemini for document analysis and image generation. Choose one:

Option A: Vertex AI (Production / Recommended)¶

Uses GCP service account authentication — no API key needed.

Create or select a Google Cloud project
Enable the Vertex AI API
Set GEMINI_USE_VERTEXAI=true in .env
For local dev, use service account impersonation

Option B: REST API Key (Quick Start / Development)¶

Go to Google AI Studio
Click "Get API key"
Copy the key and set GOOGLE_CLOUD_API_KEY in .env
Set GEMINI_USE_VERTEXAI=false

Required for Local Development¶

If you want to run services without Docker:

Python 3.10+¶

macOSLinuxWindows

brew install python@3.11

sudo apt install python3.11 python3.11-venv

Download from python.org

UV (Python Package Manager)¶

UV provides 75x faster package installation than pip.

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

Node.js 18+¶

macOSLinuxWindows

brew install node@20

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs

Download from nodejs.org

pnpm (JavaScript Package Manager)¶

pnpm provides 5-10x faster installs than npm.

# Install pnpm
npm install -g pnpm

# Verify
pnpm --version

Optional Tools¶

PostgreSQL Client¶

For direct database access:

macOSLinux

brew install postgresql

sudo apt install postgresql-client

Graphviz¶

For generating workflow diagrams:

macOSLinux

brew install graphviz

sudo apt install graphviz graphviz-dev

Terraform¶

For GCP infrastructure deployment:

# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Verify
terraform --version

Google Cloud CLI¶

For GCP deployment and management:

# macOS
brew install --cask google-cloud-sdk

# Initialize
gcloud init

Development Environment¶

Recommended VS Code Extensions¶

Python (Microsoft)
Pylance
ESLint
Tailwind CSS IntelliSense
Docker
GitLens

Recommended Settings¶

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "python.defaultInterpreterPath": "./backend/.venv/bin/python",
  "python.formatting.provider": "black",
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
}

Verification Checklist¶

Run these commands to verify your setup:

# Docker
docker --version          # Should show Docker version
docker compose version    # Should show Compose version

# Python (for local dev)
python3 --version         # Should show 3.10+
uv --version              # Should show UV version

# Node.js (for local dev)
node --version            # Should show 18+
pnpm --version            # Should show pnpm version