Understanding the four-component architecture: pgsquash-engine, capysquash-api, capysquash-cli, and CAPYSQUASH Platform

CAPYSQUASH Ecosystem Architecture

A four-component architecture designed for flexibility: core library, REST API server, CLI tool, and SaaS platform.

Brand Hierarchy

CAPYSQUASH follows a clear naming structure:

CAPYSQUASH - The main product (web platform)
capysquash-api - The REST API server (powers the platform backend)
capysquash-cli - The free CLI tool for power users
pgsquash-engine - The open-source Go library that powers everything

Golden rule: CAPYSQUASH always leads in marketing. The API, CLI, and engine support the story, but CAPYSQUASH is the hero.

🏗️ The Four Components

The CAPYSQUASH ecosystem is built on a clean, layered architecture that provides maximum flexibility for different use cases:

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│                    CAPYSQUASH ECOSYSTEM                        │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │                                                          │ │
│  │          CAPYSQUASH Platform (SaaS)                     │ │
│  │                                                          │ │
│  │  ► Web Dashboard                                        │ │
│  │  ► Team Collaboration                                   │ │
│  │  ► GitHub Integration                                   │ │
│  │  ► Analytics & Reporting                                │ │
│  │  ► Enterprise Features                                  │ │
│  │                                                          │ │
│  └────────────────────┬─────────────────────────────────────┘ │
│                       │ HTTP API calls (JWT)                  │
│  ┌────────────────────▼─────────────────────────────────────┐ │
│  │                                                          │ │
│  │          capysquash-api (REST API Server)               │ │
│  │                                                          │ │
│  │  ► REST Endpoints                                       │ │
│  │  ► JWT Authentication                                   │ │
│  │  ► GitHub Webhooks                                      │ │
│  │  ► Operations Tracking                                  │ │
│  │  ► Rate Limiting                                        │ │
│  │                                                          │ │
│  └────────────────────┬─────────────────────────────────────┘ │
│                       │ Go library import                     │
│  ┌────────────────────▼─────────────────────────────────────┐ │
│  │                                                          │ │
│  │       pgsquash-engine (Core Go Library)                 │ │
│  │                                                          │ │
│  │  ► PostgreSQL Parser (pg_query_go)                      │ │
│  │  ► Migration Analysis Engine                            │ │
│  │  ► Consolidation Algorithms                             │ │
│  │  ► Docker Validation                                    │ │
│  │  ► Plugin System                                        │ │
│  │  ► Public Go API (pkg/*)                                │ │
│  │                                                          │ │
│  └──────────────────────────────────────────────────────────┘ │
│                       ▲                                        │
│                       │ Direct library import (no HTTP)       │
│  ┌────────────────────┴─────────────────────────────────────┐ │
│  │                                                          │ │
│  │          capysquash-cli (CLI Tool)                      │ │
│  │                                                          │ │
│  │  ► Command-line Interface                               │ │
│  │  ► Terminal Workflows                                   │ │
│  │  ► CI/CD Integration                                    │ │
│  │  ► Local Development                                    │ │
│  │  ► Offline Usage                                        │ │
│  │                                                          │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Key Architectural Points:

CAPYSQUASH Platform calls capysquash-api via HTTP (not the CLI)
capysquash-api uses pgsquash-engine as a Go library
capysquash-cli also uses pgsquash-engine as a Go library (direct, no HTTP)
Both API and CLI provide different interfaces to the same core engine

📦 Tier 1: pgsquash-engine (Core Library)

The foundation: open-source library that powers everything.

What It Is

Go library with public API packages
Core technology for migration optimization
MIT licensed - completely free and open-source
No CLI - pure library for programmatic use

Public API Packages

// pkg/engine - Programmatic migration optimization
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/engine"

result, err := engine.SquashDirectory("./migrations", &engine.Config{
    SafetyLevel: engine.Standard,
})

// pkg/cli - CLI execution API
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/cli"

cli.SetVersionInfo("0.9.7", "2025-10-21", "abc123")
cli.Execute()

// pkg/plugins - Plugin management
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/plugins"

plugins.RegisterDefault()

// pkg/utils - Logging utilities
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/utils"

logger := utils.NewLogger(utils.LogLevelInfo, os.Stdout)

Use Cases

Building custom migration tools
Integrating into existing systems
Creating automation workflows
Embedding in applications
Research and development

Repository

GitHub: github.com/CAPYSQUASH/pgsquash-engine
License: MIT
Language: Go 1.22+

View Library API Documentation →

🔌 capysquash-api (REST API Server)

The HTTP REST API server that powers the CAPYSQUASH Platform backend.

What It Is

Go HTTP server providing REST API endpoints
Uses pgsquash-engine as a Go library internally
Separate repository for better modularity and versioning
Production-ready with JWT authentication and rate limiting

Key Features

REST API endpoints for migration analysis and consolidation
JWT authentication for secure API access
GitHub webhook handling for PR automation
Operations tracking in PostgreSQL
Rate limiting via token bucket algorithm
CORS support for web integration

Architecture

// capysquash-api/cmd/api-server/main.go
package main

import (
    "github.com/CAPYSQUASH/pgsquash-engine/pkg/engine"
    "github.com/gorilla/mux"
)

func main() {
    // Initialize engine
    eng := engine.New(engine.Config{
        SafetyLevel: engine.Standard,
    })

    // Setup HTTP routes
    router := mux.NewRouter()
    router.HandleFunc("/analyze", analyzeHandler)
    router.HandleFunc("/squash", squashHandler)
    router.HandleFunc("/github/webhook", githubWebhookHandler)

    // Start server
    http.ListenAndServe(":8080", router)
}

Use Cases

Backend for CAPYSQUASH Platform (primary use)
Self-hosting CAPYSQUASH's backend
Custom deployments and integrations
Programmatic API access for external tools

Repository

GitHub: github.com/CAPYSQUASH/capysquash-api
License: MIT
Deployment: Docker, Fly.io, Railway, AWS ECS

View API Server Documentation →

💻 capysquash-cli (CLI Tool)

The official command-line tool built on pgsquash-engine.

What It Is

Command-line interface for terminal workflows
Wraps pgsquash-engine with a user-friendly CLI
Free and open-source (MIT license)
Ready to use - no coding required

Architecture

// capysquash-cli/cmd/capysquash/main.go
package main

import (
    "github.com/CAPYSQUASH/pgsquash-engine/pkg/cli"
    "github.com/CAPYSQUASH/pgsquash-engine/pkg/plugins"
    "github.com/CAPYSQUASH/pgsquash-engine/pkg/utils"
)

func main() {
    // Setup
    logger := utils.NewLogger(utils.LogLevelInfo, os.Stdout)
    utils.SetDefaultLogger(logger)

    // Configure
    cli.SetVersionInfo("0.9.7", "2025-10-21", "abc123")
    cli.SetBrandName("capysquash")

    // Register plugins
    plugins.RegisterDefault()

    // Execute CLI
    cli.Execute()
}

Features

All CLI commands (analyze, squash, validate, etc.)
Plugin auto-detection (Supabase, Clerk, Neon, etc.)
Docker validation built-in
Configuration files support
CI/CD friendly

Use Cases

Local development workflows
CI/CD pipelines
Quick migration analysis
Individual developers
Small teams

Repository

GitHub: github.com/CAPYSQUASH/capysquash-cli
License: MIT
Installation: brew install capysquash-cli or go install

View CLI Installation Guide →

🌐 CAPYSQUASH Platform (SaaS)

The complete platform with visual dashboards and team collaboration.

What It Is

Web-based SaaS platform (Next.js 15)
Uses capysquash-api via HTTP for backend operations
Adds team features and automation
Subscription-based pricing

Architecture

CAPYSQUASH Platform
├── Web Dashboard (Next.js)
│   ├── Project Management
│   ├── Team Collaboration
│   ├── Analytics & Reporting
│   └── Settings & Configuration
│
├── Backend API (Node.js/Go)
│   ├── REST API
│   ├── Webhook Handlers
│   ├── GitHub App Integration
│   └── Authentication (Clerk)
│
├── Optimization Engine
│   └── capysquash-cli (runs in containers)
│       └── pgsquash-engine (core library)
│
└── Infrastructure
    ├── PostgreSQL (Neon)
    ├── Redis (Upstash)
    ├── Storage (S3)
    └── Docker (validation)

Platform-Exclusive Features

Visual web dashboard
Team collaboration with RBAC
Automatic GitHub integration
Scheduled automation
Real-time analytics
Enterprise security (SSO, audit logs)
Priority support

Use Cases

Team collaboration
Enterprise deployments
Automated workflows
Compliance requirements
Analytics and reporting

Access

Website: https://capysquash.dev
Pricing: Subscription-based (Free tier available)

View Platform Documentation →

🔄 How They Work Together

Development Workflow Example

# 1. Developer uses capysquash-cli locally
$ capysquash analyze migrations/
☑ Found 47 migrations, 12 optimization opportunities

# 2. Commits changes and opens PR
$ git add migrations/
$ git commit -m "Add user authentication"
$ git push origin feature/auth

# 3. CAPYSQUASH Platform automatically analyzes PR
# (GitHub App integration)
# - Runs capysquash-cli in cloud
# - Posts analysis comment on PR
# - Updates team dashboard

# 4. Team reviews in Platform dashboard
# - Visual diff of changes
# - Optimization recommendations
# - Impact metrics

# 5. Merge and deploy
# - Platform tracks deployment
# - Analytics updated
# - Team notified

Custom Tool Integration Example

// Your custom migration tool
package main

import (
    "github.com/CAPYSQUASH/pgsquash-engine/pkg/engine"
    "github.com/yourcompany/migration-manager/internal/db"
)

func OptimizeMigrations(projectID string) error {
    // 1. Fetch migrations from your system
    migrations := db.GetMigrations(projectID)

    // 2. Use pgsquash-engine to optimize
    result, err := engine.SquashFiles(migrations, &engine.Config{
        SafetyLevel: engine.Conservative,
    })
    if err != nil {
        return err
    }

    // 3. Store optimized migrations
    db.SaveOptimizedMigrations(projectID, result.SQL)

    // 4. Optionally sync to CAPYSQUASH Platform
    platform.SyncResults(projectID, result)

    return nil
}

🎯 Choosing the Right Tier

Decision Matrix

Need	Recommended Tier
Build custom migration tool	pgsquash-engine (Library)
Integrate into existing system	pgsquash-engine (Library)
Local development workflow	capysquash-cli
CI/CD automation	capysquash-cli
Team collaboration	CAPYSQUASH Platform
Enterprise features	CAPYSQUASH Platform
Visual dashboards	CAPYSQUASH Platform
GitHub automation	CAPYSQUASH Platform

Hybrid Approach

Many teams use multiple tiers:

Development:
  └── capysquash-cli (local testing)

CI/CD:
  └── capysquash-cli (automated checks)

Production:
  └── CAPYSQUASH Platform (team coordination)

Custom Tools:
  └── pgsquash-engine (library integration)

🔧 Technical Details

Integration Status

Integration Maturity

Not all integrations are production-ready. Always check the current status before relying on a specific integration.

Integration	Status	Notes
GitHub App	✅ Production	Webhooks + PR automation. Requires GitHub App credentials.
Vercel	🛠 Foundation built	OAuth/webhook routes exist; needs Redis + polishing.
Supabase	🛠 Foundation built	Same as Vercel; widget stub present.
Neon	🛠 Foundation built	Branch tracking implemented; requires OAuth storage + QA.
Prisma/Drizzle	✅ Production	Engine scripts available in `pgsquash-engine/scripts`.
Slack/Discord	⚠️ UI only	Outbound connectors not implemented.
VS Code Extension	🚧 Not started	Roadmap item.

Architecture Overview

User → CAPYSQUASH (Next.js) → Engine API (Go, JWT) → pgsquash-engine core

Supporting services:
  • Clerk (auth)
  • Stripe (billing)
  • Neon (database)
  • GitHub (integration)
  • Docker (validation)

Version Compatibility

All four components share version compatibility:

pgsquash-engine v0.9.7 (Go library)
  ├── capysquash-api v0.9.7 (uses engine v0.9.7)
  │   └── CAPYSQUASH Platform (uses api v0.9.7 via HTTP)
  └── capysquash-cli v0.9.7 (uses engine v0.9.7 directly)

API Surface

// pgsquash-engine exports
pkg/
├── cli/        // CLI execution API
├── engine/     // Library API
├── plugins/    // Plugin management
└── utils/      // Logging utilities

// capysquash-cli uses
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/cli"
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/plugins"
import "github.com/CAPYSQUASH/pgsquash-engine/pkg/utils"

// CAPYSQUASH Platform uses
// Runs capysquash-cli in Docker containers
// Exposes additional REST APIs for web dashboard

Data Flow

User Input
    ↓
[Tier 3: Platform Web UI] → REST API
    ↓
[Tier 2: capysquash-cli] → CLI Commands
    ↓
[Tier 1: pgsquash-engine] → Core Processing
    ↓
PostgreSQL Parser (pg_query_go)
    ↓
Migration Analysis & Optimization
    ↓
Docker Validation
    ↓
Optimized SQL Output

📚 Learn More

For Each Tier

pgsquash-engine (Library)

capysquash-cli (CLI)

CAPYSQUASH Platform (SaaS)

Comparison Guides

🎉 Summary

The CAPYSQUASH ecosystem provides three complementary ways to optimize PostgreSQL migrations:

pgsquash-engine: Core library for developers building custom tools
capysquash-cli: Official CLI for terminal workflows and CI/CD
CAPYSQUASH Platform: SaaS for team collaboration and automation

All three share the same powerful migration optimization technology, giving you the flexibility to choose the right tool for your workflow.

Start with what fits your needs:

Building custom tools? → Use pgsquash-engine
Terminal workflow? → Install capysquash-cli
Team collaboration? → Try CAPYSQUASH Platform

CAPYSQUASH Ecosystem Architecture

On this page