AI Stack

A curated platform for discovering, comparing, and sharing AI technology stacks

🎯 Purpose

AI Stack is a web application designed to help developers and teams discover, compare, and share AI technology stacks. Whether you're building a new AI-powered application or looking to optimize your existing stack, AI Stack provides a curated collection of tools, frameworks, and libraries to make informed decisions.

✨ Features

Discover AI tools and frameworks organized by stack
Compare different stacks side by side and cut costs for your own usage
Share your own AI stacks with the community
Add Missing Tools inline during stack creation or in batch mode
Stay Updated with the latest AI technology trends
Authentication via email/password and Google SSO

🛠 Tech Stack

Frontend

Framework: TanStack Start - Full-stack React framework
UI Library: React 19 - Latest React with concurrent features
Styling: Tailwind CSS v4 - Utility-first CSS framework
Icons: Lucide React - Beautiful & consistent icons
Animations: Motion & GSAP - Smooth animations
Components: Radix UI - Accessible component primitives

Backend & Data

Backend: Convex - Serverless database and backend functions
Authentication: Better Auth - Modern authentication solution
State Management: TanStack Query - Server state management
Forms: TanStack Forms - Type-safe form handling

Development Tools

Language: TypeScript - Type-safe JavaScript
Build Tool: Vite - Fast build tool and dev server
Package Manager: pnpm - Fast, disk space efficient package manager
Linting/Formatting: Biome - All-in-one toolchain
Testing: Vitest - Fast unit testing framework

Analytics

Analytics: PostHog - Product analytics suite

📁 Project Structure

aistack/              # Main web application
├── convex/           # Convex backend functions & schema
├── public/           # Static assets
├── src/              # React application source
│   ├── components/   # Shared UI primitives and cross-feature components
│   ├── features/     # Feature-scoped modules (landing, stack-editor, etc.)
│   ├── integrations/ # Third-party integrations
│   └── routes/       # File-based routing
└── README.md         # You are here

Frontend Architecture Notes

Route files should stay composition-focused (data fetch + section orchestration).
Landing page is organized under src/features/landing/*.
Stack editor is organized under src/features/stack-editor/* with:
- section components in sections/*
- reducer/selectors/hooks in state/*
- status computation in editor-status.ts
Reusable visual wrappers live under src/components/system/*.

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
pnpm (recommended) or npm
Git

Installation

Clone the repository

git clone https://github.com/alp82/aistack.git
cd aistack

Install dependencies
```
pnpm install
```

Set up environment variables

# Copy the example environment file
cp .env.example .env.local

# Configure your environment variables
# VITE_CONVEX_URL and CONVEX_DEPLOYMENT are required

Initialize Convex
```
pnpm convex dev
```
This will automatically set up your Convex deployment and update your environment variables.
Start the development server
```
pnpm dev
```
The application will be available at:
- Frontend: http://localhost:3019
- Convex Dashboard: http://localhost:3210

📜 Available Scripts

# Development
pnpm dev          # Start development server
pnpm convex dev   # Start Convex backend server

# Building
pnpm build        # Build for production
pnpm preview      # Preview production build

# Code Quality
pnpm lint         # Run Biome linter
pnpm format       # Format code with Biome
pnpm check        # Run all Biome checks

# Testing
pnpm test         # Run unit tests with Vitest

🧪 Testing

The project uses Vitest for unit testing. Tests are located in the src/**/__tests__ directories.

Vitest is configured in vite.config.ts with:

test.environment = "jsdom"
test.setupFiles = ["./src/test/setup.ts"]

src/test/setup.ts loads @testing-library/jest-dom/vitest matchers for DOM assertions.

# Run all tests
pnpm test

# Run a single test file
pnpm vitest run src/features/stack-editor/state/__tests__/editor-reducer.test.ts

# Run tests in watch mode
pnpm test --watch

# Generate coverage report
pnpm test --coverage

🎨 Adding Components

This project uses Shadcn UI components. Add new components with:

pnpm dlx shadcn@latest add [component-name]

📊 Development Notes

The development server runs on http://localhost:3019
The Convex backend runs on http://localhost:3210
Both servers should remain running during development
Use Chrome DevTools MCP for debugging and reviewing code updates
Dev Admin Access: In development mode, a "Dev Admin Login" button appears on the login page. It signs in as dev-admin@example.com with admin privileges. This requires the Convex env var IS_DEV=true to be set (email verification is also skipped when IS_DEV=true)

Database Migrations

Migration scripts are located in convex/migrations/. Run them via the Convex Dashboard or CLI.

Running Migrations via Convex Dashboard

Open your Convex Dashboard at https://dashboard.convex.dev
Navigate to your project → Functions tab
Find the migration function under migrations/
Click on the function and use Run Function to execute it

Running Migrations via CLI

# Run an internal query (read-only, for previews)
npx convex run migrations/backup:exportStackDescriptions

# Run an internal mutation (makes changes)
npx convex run migrations/populateShortIds:populateAllShortIds

Available Migration Scripts

`migrations/backup.ts` - Backup & Restore

Function	Type	Description
`exportStackDescriptions`	Query	Export all stack descriptions as JSON backup
`exportShortIdMappings`	Query	Export tool/model/bundle shortId mappings
`restoreStackDescription`	Mutation	Restore a single stack from backup
`restoreStackDescriptionsBatch`	Mutation	Restore multiple stacks from backup array

`migrations/populateShortIds.ts` - ShortId Population

Function	Type	Description
`getMissingCounts`	Query	Check how many records are missing shortId
`populateAllShortIds`	Mutation	Populate shortIds for all tools, models, bundles
`populateToolShortIds`	Mutation	Populate shortIds for tools only
`populateModelShortIds`	Mutation	Populate shortIds for models only
`populateBundleShortIds`	Mutation	Populate shortIds for bundles only

`migrations/migrateStackDescriptions.ts` - Description Migration

Function	Type	Description
`getStackCounts`	Query	Count stacks with legacy blocks (iconurl attributes)
`dryRunMigration`	Query	Preview what would be migrated without changes
`previewStackMigration`	Query	Preview migration for a single stack
`migrateAllStackDescriptions`	Mutation	Run the actual migration on all stacks

Migration Workflow

Before running migrations on production, always create a backup first!

# Step 1: Backup existing stack descriptions
npx convex run migrations/backup:exportStackDescriptions > backup-stacks.json

# Step 2: Check how many records need shortId population
npx convex run migrations/populateShortIds:getMissingCounts

# Step 3: Populate shortIds for tools, models, and bundles
npx convex run migrations/populateShortIds:populateAllShortIds

# Step 4: Preview description migration (dry run)
npx convex run migrations/migrateStackDescriptions:dryRunMigration

# Step 5: Run the actual description migration
npx convex run migrations/migrateStackDescriptions:migrateAllStackDescriptions

Restoring from Backup

If something goes wrong, restore from your backup:

# For a single stack
npx convex run migrations/backup:restoreStackDescription \
  '{"stackId": "k1234...", "description": "<p>Original content...</p>"}'

# For multiple stacks (pass JSON array)
npx convex run migrations/backup:restoreStackDescriptionsBatch \
  '{"backups": [{"stackId": "k1234...", "description": "..."}]}'

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main branch.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the 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.

🔗 Links

📞 Support

If you have any questions or need help, please open an issue on GitHub.

Made with ❤️ by Alper Ortac: https://x.com/alperortac

Name		Name	Last commit message	Last commit date
Latest commit History 134 Commits
.github/workflows		.github/workflows
.vscode		.vscode
convex		convex
public		public
research		research
src		src
.cta.json		.cta.json
.cursorrules		.cursorrules
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
KNOWLEDGE-BASE.md		KNOWLEDGE-BASE.md
LICENSE		LICENSE
README.md		README.md
TASKS.md		TASKS.md
biome.json		biome.json
components.json		components.json
convex.json		convex.json
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

AI Stack

🎯 Purpose

✨ Features

🛠 Tech Stack

Frontend

Backend & Data

Development Tools

Analytics

📁 Project Structure

Frontend Architecture Notes

🚀 Getting Started

Prerequisites

Installation

📜 Available Scripts

🧪 Testing

🎨 Adding Components

📊 Development Notes

Database Migrations

Running Migrations via Convex Dashboard

Running Migrations via CLI

Available Migration Scripts

migrations/backup.ts - Backup & Restore

migrations/populateShortIds.ts - ShortId Population

migrations/migrateStackDescriptions.ts - Description Migration

Migration Workflow

Restoring from Backup

🤝 Contributing

📄 License

🔗 Links

📞 Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`migrations/backup.ts` - Backup & Restore

`migrations/populateShortIds.ts` - ShortId Population

`migrations/migrateStackDescriptions.ts` - Description Migration

Packages