🔍 Idea Sieve - AI-Powered Idea Validator

A rigorous, honest, and evidence-based system for validating startup and product ideas.

Built with TypeScript, React, Hono, AI SDK, and OpenAI • Powered by Bun

Quick Start • Features • Architecture • Manual Setup • Contributing

⚠️ Disclaimer

This tool provides AI-generated insights for informational purposes only. Validation results, competitor analysis, and market assessments are generated by AI and may not be accurate, complete, or current.

Not professional advice: This is not business, legal, financial, or investment advice

Do your own research: Always verify information independently before making decisions

No guarantees: Generated insights do not predict future success

AI limitations: Competitor data and market analysis may contain errors

Use this tool as a starting point for research, not the sole basis for business decisions.

🎬 Demo

idea-sieve-demo.mp4

🚀 Quick Start with Docker (Recommended)

Get up and running in under 2 minutes:

Prerequisites

Docker and Docker Compose installed (Get Docker)
OpenAI API key (Get one here)
Tavily API key (Get one here)

Steps

Clone the repository

git clone https://github.com/kzeitar/idea-sieve.git
cd idea-sieve

Set up environment variables

cp .env.example .env

Edit .env and add your API keys:

# Required: Add your actual API keys
OPENAI_API_KEY=sk-proj-your-actual-openai-key
TAVILY_API_KEY=tvly-your-actual-tavily-key

# These are pre-configured for Docker
DATABASE_URL=postgresql://postgres:password@postgres:5432/idea-sieve
CORS_ORIGIN=http://localhost:3002  # 3002 for development, 3001 for production
VITE_SERVER_URL=http://localhost:3000

Start the application

docker-compose up

Access the application

🌐 Web App: http://localhost:3001 (production) or http://localhost:3002 (development)
🔌 API: http://localhost:3000
📊 Database: PostgreSQL on port 5432

That's it! The application is now running with a complete stack including the database, backend, and frontend.

Note: Production mode uses port 3001, while development mode (with hot-reload) uses port 3002 to avoid port conflicts.

Docker Commands

# Start in production mode
docker-compose up

# Start in background (detached mode)
docker-compose up -d

# Stop the application
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

# View logs
docker-compose logs -f

# Rebuild after code changes
docker-compose up --build

# Development mode with hot-reload (see Development section)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

✨ Features

🎯 Configurable Assessment Styles

Choose the validation tone that matches your needs:

Brutal 🔥 - Harshly critical, very high standards, emphasizes every risk
Balanced ⚖️ - Fair and honest, constructive criticism (DEFAULT)
Encouraging 💪 - Supportive while honest, focuses on solving challenges
Optimistic ✨ - Highlights potential and opportunities, growth-focused

All tones maintain:

✅ Real competitor research with actual company names
✅ Evidence-based assessments on market data
✅ Specific, actionable feedback
✅ Honest risk identification
❌ Never fabricate statistics or competitors

🔬 Validation Framework

Multi-stage validation with research tasks and analysis
Real-time progress updates using Server-Sent Events (SSE)
Competitor research using Tavily AI search
Evidence-based recommendations with market data
Detailed scoring across multiple dimensions
Actionable insights for next steps

📊 Supported Idea Types

SaaS (Software as a Service)
Micro-SaaS
Mobile Applications
Chrome Extensions
API Tools
Marketplaces
Information Products (courses, ebooks, templates)
Generic products

🏗️ Architecture

Tech Stack

Frontend (apps/web)

⚛️ React 19 - Modern UI library
🔀 TanStack Router - File-based routing with full type safety
🎨 TailwindCSS 4 - Utility-first CSS
🧩 shadcn/ui - Reusable UI components
📡 TanStack Query - Server state management
🔥 Vite - Lightning-fast build tool

Backend (apps/server)

🔥 Hono - Lightweight, ultra-fast web framework
⚡ Bun - Fast JavaScript runtime
📡 Server-Sent Events - Real-time progress updates

AI (packages/ai)

🤖 AI SDK - AI-powered validation
🔍 Tavily AI - Web research and competitor analysis

Database (packages/db)

🐘 PostgreSQL - Reliable relational database
🔷 Prisma - TypeScript-first ORM
🐳 Docker - Containerized database

Monorepo Tools

📦 pnpm - Fast, disk space efficient package manager
⚡ Turborepo - High-performance build system
🎯 TypeScript - End-to-end type safety
🧹 Biome - Fast linting and formatting
🪝 Husky - Git hooks for code quality

Project Structure

idea-sieve/
├── apps/
│   ├── web/              # React frontend (Vite + TanStack Router)
│   │   ├── src/          # Source code
│   │   ├── Dockerfile    # Production Docker image
│   │   └── Dockerfile.dev # Development Docker image
│   └── server/           # Hono backend API
│       ├── src/          # Source code
│       ├── Dockerfile    # Production Docker image
│       └── Dockerfile.dev # Development Docker image
├── packages/
│   ├── ai/               # AI validation logic (OpenAI + Tavily)
│   ├── db/               # Database schema & queries (Prisma)
│   ├── env/              # Environment variable validation
│   └── config/           # Shared TypeScript config
├── docker-compose.yml    # Production stack
├── docker-compose.dev.yml # Development overrides
├── .env.example          # Environment template
└── README.md            # You are here!

How It Works

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│             │      │              │      │             │
│   React     │─────▶│   Hono API   │─────▶│  PostgreSQL │
│   Frontend  │◀─────│   (Bun)      │◀─────│   Database  │
│             │ SSE  │              │      │             │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │              │
                     │  OpenAI +    │
                     │  Tavily AI   │
                     │              │
                     └──────────────┘

User submits an idea through the React frontend
Backend creates a validation job and streams progress via SSE
AI agent performs research tasks using OpenAI and Tavily
Results are stored in PostgreSQL and streamed back to the frontend
User receives a comprehensive validation report

💻 Manual Installation

If you prefer not to use Docker:

Prerequisites

Bun (v1.0+) or Node.js (v18+)
pnpm (v8+)
PostgreSQL (v14+)

Steps

Clone the repository

git clone https://github.com/kzeitar/idea-sieve.git
cd idea-sieve

Install dependencies

pnpm install

Set up environment variables

Create .env files in the following locations:

apps/server/.env

DATABASE_URL=postgresql://postgres:password@localhost:5432/idea-sieve
OPENAI_API_KEY=sk-proj-your-openai-api-key
TAVILY_API_KEY=tvly-your-tavily-api-key
CORS_ORIGIN=http://localhost:3001

apps/web/.env

VITE_SERVER_URL=http://localhost:3000

packages/db/.env

DATABASE_URL=postgresql://postgres:password@localhost:5432/idea-sieve

Start PostgreSQL

Using Docker:

pnpm run db:start

Or start your own PostgreSQL instance and create a database named idea-sieve.

Push database schema

pnpm run db:push

Start development servers

pnpm run dev

This will start:

Frontend: http://localhost:3001
Backend: http://localhost:3000
Database: PostgreSQL on port 5432

Available Scripts

# Development
pnpm run dev              # Start all services
pnpm run dev:web          # Start only frontend
pnpm run dev:server       # Start only backend

# Building
pnpm run build            # Build all applications
pnpm run check-types      # Type-check all packages

# Database
pnpm run db:push          # Push schema changes
pnpm run db:studio        # Open Prisma Studio
pnpm run db:generate      # Generate Prisma client
pnpm run db:migrate       # Run migrations
pnpm run db:seed          # Seed the database
pnpm run db:start         # Start PostgreSQL (Docker)
pnpm run db:stop          # Stop PostgreSQL (Docker)

# Code Quality
pnpm run check            # Run Biome linting and formatting

🔧 Development

Development with Docker (Hot-Reload)

For a development environment with hot-reload:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

This mounts the source code into the containers, so changes are reflected immediately without rebuilding.

Access the development environment:

🌐 Web App: http://localhost:3002 (note: different port than production)
🔌 API: http://localhost:3000
📊 Database: PostgreSQL on port 5432

Note: Development mode uses port 3002 for the frontend to avoid conflicts with other services.

Development without Docker

# Terminal 1: Start PostgreSQL
pnpm run db:start

# Terminal 2: Start all dev servers
pnpm run dev

# Or start services individually
pnpm run dev:server    # Backend only
pnpm run dev:web       # Frontend only

Database Management

# View/edit data in Prisma Studio
pnpm run db:studio

# Push schema changes without migrations (development)
pnpm run db:push

# Create a migration (production)
pnpm run db:migrate

# Regenerate Prisma client after schema changes
pnpm run db:generate

🌐 Environment Variables

Required Variables

Variable	Description	Example
`OPENAI_API_KEY`	OpenAI API key for AI validation	`sk-proj-...`
`TAVILY_API_KEY`	Tavily API key for web research	`tvly-...`
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`CORS_ORIGIN`	Frontend URL for CORS	`http://localhost:3002` (dev) or `http://localhost:3001` (prod)
`VITE_SERVER_URL`	Backend API URL (frontend)	`http://localhost:3000`

Optional Variables

Variable	Description	Default
`NODE_ENV`	Environment mode	`development`

🧪 Testing

# Run tests (when implemented)
pnpm test

# Type checking
pnpm run check-types

# Linting and formatting
pnpm run check

🐳 Docker Deployment

Production Deployment

Build production images

docker-compose build

Deploy to your server

# On your server
docker-compose up -d

Run database migrations

docker-compose exec server bun run db:push

Environment-Specific Configuration

For production, create a .env.production file:

DATABASE_URL=postgresql://user:password@prod-db:5432/idea-sieve
OPENAI_API_KEY=sk-proj-production-key
TAVILY_API_KEY=tvly-production-key
CORS_ORIGIN=https://yourdomain.com
VITE_SERVER_URL=https://api.yourdomain.com
NODE_ENV=production

Then use it with:

docker-compose --env-file .env.production up -d

📝 API Documentation

Endpoints

Ideas

GET /api/ideas - List all ideas
POST /api/ideas - Create a new idea
GET /api/ideas/:id - Get idea details
PUT /api/ideas/:id - Update an idea
DELETE /api/ideas/:id - Delete an idea

Validation

POST /api/validate - Start validation job
GET /api/validate/jobs/:jobId - Get job status
GET /api/validate/jobs/:jobId/stream - Stream job updates (SSE)
GET /api/validate/jobs/:jobId/progress - Get job progress
GET /api/validate/jobs/:jobId/tasks - Get task results
GET /api/validate/ideas/:ideaId/validation - Get validation report

Frameworks

GET /api/frameworks - List validation frameworks
GET /api/frameworks/:ideaType - Get framework for idea type

Stats

GET /api/stats - Get application statistics

For detailed API documentation, see API.md (coming soon).

🛠️ Troubleshooting

Common Issues

Docker build fails

# Clean and rebuild
docker-compose down -v
docker system prune -a
docker-compose up --build

Port already in use

# Check what's using the port
lsof -i :3000  # Backend API
lsof -i :3001  # Frontend (production Docker)
lsof -i :3002  # Frontend (development Docker)
lsof -i :5432  # Database

# Kill the process or change ports in docker-compose.yml / docker-compose.dev.yml

Database connection fails

# Make sure PostgreSQL is running
docker-compose ps

# Check DATABASE_URL in .env
# For Docker, use: postgres:5432
# For local, use: localhost:5432

Prisma Client not generated

# Regenerate Prisma client
pnpm run db:generate

# Or inside Docker
docker-compose exec server bun run db:generate

Hot-reload not working in Docker

# Make sure you're using the dev override
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Check volume mounts are correct
docker-compose -f docker-compose.yml -f docker-compose.dev.yml config

CORS errors

# Verify CORS_ORIGIN matches your frontend URL
# For production Docker: CORS_ORIGIN=http://localhost:3001
# For development Docker: CORS_ORIGIN=http://localhost:3002
# For manual development: CORS_ORIGIN=http://localhost:3001

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run linting and type checks (pnpm run check && pnpm run check-types)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Hono - Fast, lightweight web framework
Powered by OpenAI - AI validation
Research by Tavily - AI-powered web search
UI by shadcn/ui - Beautiful components

Remember: A harsh truth now saves months of wasted effort. Good luck! 🚀

⬆ Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.husky		.husky
apps		apps
packages		packages
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bts.jsonc		bts.jsonc
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json

License

kzeitar/idea-sieve

Folders and files

Latest commit

History

Repository files navigation

🔍 Idea Sieve - AI-Powered Idea Validator

🎬 Demo

🚀 Quick Start with Docker (Recommended)

Prerequisites

Steps

Docker Commands

✨ Features

🎯 Configurable Assessment Styles

🔬 Validation Framework

📊 Supported Idea Types

🏗️ Architecture

Tech Stack

Project Structure

How It Works

💻 Manual Installation

Prerequisites

Steps

Available Scripts

🔧 Development

Development with Docker (Hot-Reload)

Development without Docker

Database Management

🌐 Environment Variables

Required Variables

Optional Variables

🧪 Testing

🐳 Docker Deployment

Production Deployment

Environment-Specific Configuration

📝 API Documentation

Endpoints

Ideas

Validation

Frameworks

Stats

🛠️ Troubleshooting

Common Issues

🤝 Contributing

Quick Contribution Guide

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages