SlothForge MVP

SlothForge is a living software factory that converts product ideas into deployed MVPs. It combines LLM-powered requirement extraction, automated ticket generation, intelligent build orchestration, and continuous drift detection to maintain alignment between specifications and implementation.

Overview

SlothForge automates the entire software development lifecycle:

BRD Extraction: Chat with an LLM to extract structured Business Requirements Documents from product ideas
Ticket Generation: Automatically generate epic/story hierarchies with acceptance criteria and dependency graphs
Build Orchestration: Execute tickets in topological order, generating code that satisfies acceptance criteria
Drift Detection: Compare PR implementations against acceptance criteria to detect gaps and bugs
CI Integration: Trace test failures back to originating tickets and create bug tickets automatically

Architecture

SlothForge is built as a monorepo with the following structure:

slothforge-mvp/
├── apps/
│   ├── web/              # Next.js 14 frontend (port 3000)
│   └── api/              # Fastify backend (port 3001)
├── packages/
│   ├── db/               # Prisma schema + generated client
│   └── shared/           # TypeScript types + Zod schemas
├── docker-compose.yml    # PostgreSQL + Redis services
├── turbo.json           # Build pipeline configuration
└── pnpm-workspace.yaml  # Workspace definitions

Technology Stack

Layer	Technology	Purpose
Package Manager	pnpm	Fast, disk-efficient, first-class monorepo support
Monorepo Tool	Turborepo	Parallel task execution, build caching
Backend Runtime	Node.js 20+ + TypeScript	Async-first, rich LLM SDK ecosystem
API Framework	Fastify	Low overhead, built-in schema validation
ORM	Prisma	Type-safe DB access, migrations, JSONB support
Database	PostgreSQL 16	JSONB for flexible metadata, strong transactions
Cache/Queue	Redis 7	Async build jobs, prevents blocking API responses
Frontend	Next.js 14 App Router	SSE support, React Server Components
UI Library	Tailwind CSS + shadcn/ui	Fast, consistent, composable components
LLM SDK	Vercel AI SDK	Unified API across providers, structured output
LLM Provider	Google Gemini	Generous free tier, large context windows
Schema Validation	Zod	Runtime + compile-time safety for LLM outputs
Ticket Provider	Linear	Clean GraphQL API, free tier, webhooks
VCS Provider	GitHub	REST API + webhooks, widest adoption
Local Tunneling	ngrok	Expose local API for webhook testing

Prerequisites

Before setting up SlothForge, ensure you have the following installed:

Node.js 20+: Download from nodejs.org
pnpm 9+: Install with npm install -g pnpm
Docker: Download from docker.com
ngrok: Download from ngrok.com (for webhook testing)

Local Setup

Follow these steps to run SlothForge locally:

1. Clone the Repository

git clone <repository-url>
cd slothforge-mvp

2. Copy Environment Variables

cp .env.example .env

Edit .env and fill in your API keys (see Environment Configuration below).

3. Start Docker Services

Start PostgreSQL and Redis:

docker compose up -d

Verify services are running:

docker compose ps

You should see both slothforge-postgres and slothforge-redis with status "Up".

4. Install Dependencies

Install all workspace dependencies:

pnpm install

5. Run Database Migrations

Apply Prisma migrations to create database tables:

pnpm db:migrate

6. Start Development Servers

Start both frontend and backend in parallel:

pnpm dev

This will start:

Frontend: http://localhost:3000
Backend API: http://localhost:3001

Verify the API is running:

curl http://localhost:3001/health
# Should return: {"status":"ok"}

ngrok Setup

To receive webhooks from GitHub and Linear during local development, you need to expose your local API using ngrok.

1. Install ngrok

Download and install ngrok from ngrok.com/download.

2. Start ngrok Tunnel

In a new terminal window, run:

ngrok http 3001

You should see output like:

Forwarding  https://abc123.ngrok.io -> http://localhost:3001

3. Copy HTTPS URL

Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok.io).

4. Set Environment Variable

Add the ngrok URL to your .env file:

NGROK_URL=https://abc123.ngrok.io

Note: The ngrok URL changes every time you restart ngrok (unless you have a paid plan). You'll need to update webhooks whenever the URL changes.

Webhook Registration

SlothForge receives webhooks from GitHub (for CI events) and Linear (for ticket updates).

GitHub Webhook Setup

Go to your GitHub repository
Navigate to Settings > Webhooks > Add webhook
Set Payload URL to: https://your-ngrok-url.ngrok.io/webhooks/github
Set Content type to: application/json
Select Let me select individual events:
- ✅ Pull requests
- ✅ Pull request reviews
- ✅ Workflow runs
- ✅ Push
Click Add webhook

Linear Webhook Setup

Go to your Linear workspace
Navigate to Settings > API > Webhooks
Click New webhook
Set URL to: https://your-ngrok-url.ngrok.io/webhooks/linear
Select events:
- ✅ Issue created
- ✅ Issue updated
- ✅ Issue deleted
Click Create webhook

Project Structure

Monorepo Layout

slothforge-mvp/
├── apps/
│   ├── api/                          # Fastify backend
│   │   ├── src/
│   │   │   ├── server.ts            # Main server entry point
│   │   │   ├── lib/
│   │   │   │   ├── prisma.ts        # Prisma client singleton
│   │   │   │   └── redis.ts         # Redis client singleton
│   │   │   ├── services/
│   │   │   │   └── llm/
│   │   │   │       └── providers.ts # LLM model configurations
│   │   │   └── adapters/
│   │   │       ├── ticket/
│   │   │       │   └── LinearAdapter.ts
│   │   │       └── vcs/
│   │   │           └── GitHubAdapter.ts
│   │   └── package.json
│   │
│   └── web/                          # Next.js frontend
│       ├── src/
│       │   └── app/
│       │       ├── layout.tsx       # Root layout
│       │       ├── page.tsx         # Landing page
│       │       └── globals.css      # Global styles
│       └── package.json
│
├── packages/
│   ├── db/                           # Database layer
│   │   ├── prisma/
│   │   │   └── schema.prisma        # Database schema
│   │   ├── index.ts                 # Prisma client export
│   │   └── package.json
│   │
│   └── shared/                       # Shared types and schemas
│       ├── src/
│       │   ├── types/               # TypeScript interfaces
│       │   ├── schemas/             # Zod validation schemas
│       │   └── index.ts             # Package exports
│       └── package.json
│
├── docker-compose.yml                # Local infrastructure
├── turbo.json                        # Turborepo configuration
├── pnpm-workspace.yaml               # Workspace definitions
└── .env.example                      # Environment template

Database Schema

SlothForge uses PostgreSQL with 10 core tables:

Project: Core entity representing a SlothForge project
BRD: Business Requirements Document with structured fields
Ticket: Work items (epics and stories) with acceptance criteria
TicketEdge: Dependency relationships between tickets
DriftResult: Output of drift detection runs
DriftFeedback: User feedback on drift detection accuracy
CIEvent: CI pipeline events from webhooks
ProcessedEvent: Idempotency table for webhook deduplication
ReviewQueue: Human review queue for LLM failures

View the full schema in packages/db/prisma/schema.prisma.

Available Scripts

Root Level

Run these commands from the repository root:

Command	Description
`pnpm dev`	Start all applications in development mode (parallel)
`pnpm build`	Build all applications for production
`pnpm lint`	Run linters across all workspaces
`pnpm test`	Run tests across all workspaces
`pnpm db:migrate`	Run Prisma migrations on the database

Workspace-Specific

Run these commands with pnpm --filter <workspace>:

API (`@slothforge/api`)

pnpm --filter @slothforge/api dev          # Start API in watch mode
pnpm --filter @slothforge/api build        # Build API for production
pnpm --filter @slothforge/api test         # Run API tests
pnpm --filter @slothforge/api test:watch   # Run API tests in watch mode

Web (`@slothforge/web`)

pnpm --filter @slothforge/web dev          # Start Next.js dev server
pnpm --filter @slothforge/web build        # Build Next.js for production
pnpm --filter @slothforge/web start        # Start production server

Database (`@slothforge/db`)

pnpm --filter @slothforge/db migrate:dev   # Run migrations (dev)
pnpm --filter @slothforge/db migrate:deploy # Run migrations (prod)
pnpm --filter @slothforge/db studio        # Open Prisma Studio
pnpm --filter @slothforge/db generate      # Generate Prisma client
pnpm --filter @slothforge/db test          # Run database tests

Shared (`@slothforge/shared`)

pnpm --filter @slothforge/shared test      # Run shared package tests
pnpm --filter @slothforge/shared lint      # Lint shared package

Environment Configuration

SlothForge requires several environment variables for external service integrations. Copy .env.example to .env and fill in the following:

Application Configuration

Variable	Default	Description
`NODE_ENV`	`development`	Node environment (development, production, test)
`PORT`	`3001`	API server port

Database Configuration

Variable	Required	Description
`DATABASE_URL`	✅	PostgreSQL connection string
`REDIS_URL`	✅	Redis connection string

Local Development Values:

DATABASE_URL=postgresql://slothforge:slothforge_local@localhost:5432/slothforge
REDIS_URL=redis://localhost:6379

LLM Integration

Variable	Required	Description	How to Obtain
`GOOGLE_GENERATIVE_AI_API_KEY`	✅	Google Gemini API key	1. Visit aistudio.google.com/app/apikey 2. Sign in with Google 3. Click "Create API Key" 4. Copy the generated key

External Service Integrations

Variable	Required	Description	How to Obtain
`LINEAR_API_KEY`	✅	Linear API key for ticket management	1. Visit linear.app/settings/api 2. Navigate to "Personal API keys" 3. Click "Create key" 4. Copy the generated key
`GITHUB_TOKEN`	✅	GitHub Personal Access Token	1. Visit github.com/settings/tokens 2. Click "Generate new token (classic)" 3. Select scopes: `repo` (all), `admin:repo_hook` (all) 4. Click "Generate token" 5. Copy the token (save it securely!)
`NGROK_URL`	✅	ngrok HTTPS URL for webhooks	1. Install ngrok 2. Run `ngrok http 3001` 3. Copy the HTTPS forwarding URL

Development Workflow

Typical Development Session

Start Infrastructure:
```
docker compose up -d
```
Start ngrok (in a separate terminal):
```
ngrok http 3001
```
Update NGROK_URL in .env with the new URL
Start Development Servers:
```
pnpm dev
```
Open Prisma Studio (optional, in a separate terminal):
```
pnpm --filter @slothforge/db studio
```

Making Database Changes

Edit packages/db/prisma/schema.prisma
Create a migration:
```
pnpm db:migrate
```
Prisma will prompt you to name the migration
The migration is automatically applied to your local database

Adding Dependencies

Add dependencies to specific workspaces:

# Add to API
pnpm --filter @slothforge/api add <package-name>

# Add to Web
pnpm --filter @slothforge/web add <package-name>

# Add to Shared
pnpm --filter @slothforge/shared add <package-name>

# Add dev dependency
pnpm --filter @slothforge/api add -D <package-name>

Running Tests

# Run all tests
pnpm test

# Run tests for specific workspace
pnpm --filter @slothforge/api test

# Run tests in watch mode
pnpm --filter @slothforge/api test:watch

Troubleshooting

Port Already in Use

If you see "Port 3000 (or 3001) is already in use":

# Find and kill the process using the port
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

Docker Services Not Starting

If Docker services fail to start:

# Stop all services
docker compose down

# Remove volumes (WARNING: deletes all data)
docker compose down -v

# Start fresh
docker compose up -d

Database Connection Errors

If the API cannot connect to PostgreSQL:

Verify Docker services are running: docker compose ps
Check DATABASE_URL in .env matches docker-compose.yml
Ensure migrations have been run: pnpm db:migrate

Prisma Client Not Found

If you see "Cannot find module '@prisma/client'":

# Regenerate Prisma client
pnpm --filter @slothforge/db generate

TypeScript Errors Across Workspaces

If you see import errors between workspaces:

# Rebuild all workspaces
pnpm build

ngrok URL Changed

If webhooks stop working after restarting ngrok:

Copy the new ngrok HTTPS URL
Update NGROK_URL in .env
Update webhook URLs in GitHub and Linear settings
Restart the API: pnpm --filter @slothforge/api dev

License

[Add your license here]

Contributing

[Add contributing guidelines here]

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
apps		apps
packages		packages
slothforge		slothforge
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

SlothForge MVP

Overview

Architecture

Technology Stack

Prerequisites

Local Setup

1. Clone the Repository

2. Copy Environment Variables

3. Start Docker Services

4. Install Dependencies

5. Run Database Migrations

6. Start Development Servers

ngrok Setup

1. Install ngrok

2. Start ngrok Tunnel

3. Copy HTTPS URL

4. Set Environment Variable

Webhook Registration

GitHub Webhook Setup

Linear Webhook Setup

Project Structure

Monorepo Layout

Database Schema

Available Scripts

Root Level

Workspace-Specific

API (@slothforge/api)

Web (@slothforge/web)

Database (@slothforge/db)

Shared (@slothforge/shared)

Environment Configuration

Application Configuration

Database Configuration

LLM Integration

External Service Integrations

Development Workflow

Typical Development Session

Making Database Changes

Adding Dependencies

Running Tests

Troubleshooting

Port Already in Use

Docker Services Not Starting

Database Connection Errors

Prisma Client Not Found

TypeScript Errors Across Workspaces

ngrok URL Changed

License

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

API (`@slothforge/api`)

Web (`@slothforge/web`)

Database (`@slothforge/db`)

Shared (`@slothforge/shared`)

Packages