Prerequisites Before you begin, ensure you have the following installed:
Node.js Version 20 or higher
pnpm Version 10 or higher (required)
This project requires pnpm. Other package managers (npm, yarn) are not supported.
Clone and Install
Clone the repository
git clone < your-fork-ur l > cd < repo-nam e >
Install dependencies
This will install all dependencies for the monorepo workspace. Environment Configuration
Create environment files
Create .env files for the relevant apps based on the environment variables defined in:
apps/www/src/lib/env.server.tsapps/www/src/lib/env.client.tsSlack app config files under apps/slack-app/server/**
Required environment variables
# Database DATABASE_URL = postgresql://... # Authentication AUTH_SECRET = your-secret-here AUTH_GOOGLE_CLIENT_ID = your-google-client-id AUTH_GOOGLE_SECRET = your-google-secret # AI (optional for testing) OPENAI_API_KEY = your-openai-key # Redis/Upstash (optional) KV_URL = your-redis-url KV_REST_API_URL = your-kv-url KV_REST_API_TOKEN = your-kv-token # Vector Search (optional) UPSTASH_VECTOR_REST_URL = your-vector-url UPSTASH_VECTOR_REST_TOKEN = your-vector-token # System SYSTEM_USER_ID = your-system-user-uuid
# Slack SLACK_BOT_TOKEN = xoxb-... SLACK_SIGNING_SECRET = your-slack-signing-secret SLACK_APP_VERIFICATION = your-verification-token # Slack Channels SLACK_DIGEST_CHANNEL_ID = C... SLACK_GTM_FEEDBACK_CHANNEL_ID = C... # Shared with www DATABASE_URL = postgresql://...
Configure your infrastructure
You’ll need to set up or have access to:
PostgreSQL database (Neon recommended)Redis/Upstash KV for cachingGoogle OAuth credentials for authenticationOpenAI API key for AI features (optional for basic testing)Slack app credentials (optional, for Slack integration) Database Setup
Run migrations
This applies the Drizzle schema to your database.
Seed demo data (optional)
The seed script populates demo data and generates embeddings for feature requests if AI credentials are configured.
Running the Development Server Start all apps
Build all apps
Lint code
Once started:
Web app: http://localhost:3000
Slack app: http://localhost:3001
Monorepo Structure The project uses a pnpm workspace monorepo with the following structure:
gtm-feedback/ ├── apps/ │ ├── www/ # Next.js web application │ └── slack-app/ # Slack Bolt application ├── packages/ │ ├── ai/ # Shared AI utilities (agents, tools) │ ├── database/ # Drizzle ORM schema & DB helpers │ ├── redis/ # Redis client helpers │ └── config/ # Shared configuration └── pnpm-workspace.yaml # Workspace definition
Workspace Configuration The workspace is defined in pnpm-workspace.yaml:
packages : - "packages/*" - "apps/*"
Package Organization
apps/www Next.js 16 web app for feedback collection and reporting
apps/slack-app Slack integration for capturing feedback via reactions and commands
packages/ai Shared AI helpers (agents, tools, embeddings)
packages/database Drizzle ORM schema and utilities
packages/redis Redis/Upstash client helpers
packages/config Shared configuration and utilities
Development Commands Root-level commands Run from the monorepo root:
# Start all dev servers pnpm dev # Build all packages pnpm build # Lint all code (Biome) pnpm lint # Format all code pnpm format # Database operations pnpm db:push # Push schema changes pnpm db:seed # Seed demo data
Workspace-specific commands Run commands in specific workspaces:
# Run in www workspace pnpm --filter www dev pnpm --filter www build pnpm --filter www db:seed # Run in slack-app workspace pnpm --filter slack-app dev pnpm --filter slack-app build
Troubleshooting
If you see an error that port 3000 or 3001 is already in use: # Find the process using the port lsof -i :3000 # Kill the process kill -9 < PI D >
Ensure you’re using pnpm 10 or higher: pnpm --version # Upgrade if needed npm install -g pnpm@latest
Database connection errors
Verify your DATABASE_URL is correct and the database is accessible: # Test connection with psql psql $DATABASE_URL
Try clearing the cache and reinstalling: # Clear node_modules and lockfile rm -rf node_modules pnpm-lock.yaml # Reinstall pnpm install
Next Steps
Database Learn about database operations and schema
Workflows Create and test background workflows
Contributing Read the contribution guidelines
