System Architecture

StackPilot is built on three core pillars that work in sequence to move from a project description to a production-ready monorepo.

01 AI Engine

Uses LLMs (Gemini, Claude, GPT) to parse intent signals like "fast", "marketplace", or "real-time" into structured stack selections.

02 Validator

A deterministic rule engine that ensures selected components (e.g., Supabase + Prisma) are technically compatible before scaffolding.

03 Scaffolder

The execution layer that copies templates, injects variables via Handlebars, and orchestrates dependency installation.

CLI Command Reference

The CLI is distributed via NPM as stack-pilot-architect.

# Initialize your AI provider (Stored in local config)
stack-pilot-architect init

# Start the interactive AI scaffolding flow
stack-pilot-architect create

# Manually override or update specific stack configurations
stack-pilot-architect override

Global Configuration

Config is stored in the CLI installation directory. The init command manages these keys, but they can be bypassed using environment variables:

STACKPILOT_GEMINI_API_KEY
STACKPILOT_OPENAI_API_KEY
STACKPILOT_AI_PROVIDER

Scaffolder Logic & Workspace

StackPilot maintains a strict project organization policy to keep your development machine head-clean.

Centralized Hub: All generated projects are saved to Documents/StackPilot/projects/ by default.
Isolation: Each project is a standalone Monorepo (TurboRepo or standard) with its own Docker and deployment configs.
Deep Integration: Scaffolding isn't just file copying; it involves running npm install, git init, and DB generation.

Deployment Assets & Scripts

Beyond core stack templates, StackPilot uses shared assets to handle platform-specific configurations.

Deployments Folder: Contains global configuration blocks for Docker, Vercel, and Railway. These are injected into projects based on the user's choice, ensuring consistent infrastructure across different tech stacks.
Scripts Folder: Houses internal utility scripts used during local development. For example, generate-templates.js is used to validate or pre-process the template registry before build.

Adding New Templates

Templates live in the /templates directory. To add a new stack:

Create a new folder in /templates/[stack-name].
Add a manifest.json defining the stack capabilities.
Place boilerplates in a /root subfolder using .hbs extension for dynamic files.
Update config/stacks.config.json to register the new valid options.