seatkit

SeatKit

Open-source restaurant reservation management system for high-turnover, small-seat restaurants

CI License

Status: 🚧 Early Development - API Backend Phase

🎯 What is SeatKit?

SeatKit is a modern, modular reservation management system built specifically for small restaurants (14-20 seats) with high turnover. Originally deployed as an iOS Swift app for a Japanese-Venetian restaurant in Venice, we’re rebuilding it as an open-source TypeScript web application.

Why SeatKit?

🚀 Quick Start

Prerequisites

1. Clone the Repository

git clone https://github.com/seatkit/seatkit.git
cd seatkit

2. Install Dependencies

pnpm install

This installs all dependencies for the monorepo workspace.

3. Set Up Local Secrets (Development)

The API uses Google Cloud Secret Manager in production, but for local development you have three options:

Create packages/api/.env manually:

# Database
DATABASE_URL=postgresql://localhost:5432/seatkit_dev
TEST_DATABASE_URL=postgresql://localhost:5432/seatkit_test

# Supabase (use local Supabase or public test instance)
SUPABASE_URL=http://localhost:54321
SUPABASE_PUBLISHABLE_KEY=your-local-key
SUPABASE_SECRET_KEY=your-local-key

The Fastify server will automatically fall back to .env if GCP authentication fails.

Option 2: Use GCP Secret Manager (For Core Team)

If you have access to the project’s GCP account:

# Authenticate with Google Cloud
gcloud auth application-default login

# Set project ID
export GOOGLE_CLOUD_PROJECT=seatkit-dev

# Secrets will be fetched automatically on startup
pnpm dev

Note: You need IAM permissions (roles/secretmanager.secretAccessor) on the project to access secrets.

Option 3: Your Own GCP Project

Set up your own GCP project and secrets:

cd packages/api
# Edit the script with your credentials
pnpm secrets:setup

# Then set your project ID
export GOOGLE_CLOUD_PROJECT=your-project-id

This uploads secrets to your GCP project. See SECURITY.md for details.

4. Set Up Database

# Create databases
createdb seatkit_dev
createdb seatkit_test

# Run migrations
cd packages/api
pnpm db:migrate
pnpm db:migrate:test

5. Build Packages

# From root
pnpm build

This builds all TypeScript packages in dependency order.

6. Run Tests

pnpm test

7. Start Development Server

# API server (port 3001)
cd packages/api
pnpm dev

Visit http://localhost:3001/health to verify the API is running.

📦 Project Structure

seatkit/
├── packages/
│   ├── types/          # ✅ Zod schemas + TypeScript types
│   ├── utils/          # ✅ Shared utilities (date, money, database)
│   ├── api/            # 🚧 Fastify backend + Drizzle ORM
│   ├── engine/         # 📝 Business logic (coming soon)
│   ├── ui/             # 📝 React components (coming soon)
│   └── web/            # 📝 Next.js frontend (coming soon)
├── docs/               # Architecture decision records & guides
└── .github/workflows/  # CI/CD pipelines
Legend: ✅ Complete 🚧 In Progress 📝 Planned

🛠 Development Workflow

Common Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run linting
pnpm lint

# Run type checking
pnpm typecheck

# Run tests
pnpm test

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

# Clean all build artifacts
pnpm clean

Package-Specific Commands

# Work on a specific package
cd packages/api

# Start dev server
pnpm dev

# Run migrations
pnpm db:migrate

# Open Drizzle Studio (database GUI)
pnpm db:studio

For real-time type checking during development:

# Watch all packages
pnpm typecheck:watch

# Or watch specific package
cd packages/types
pnpm typecheck:watch

See DEVELOPMENT.md for detailed development guidelines.

🏗 Architecture

SeatKit uses a modern monorepo architecture with:

Key Design Decisions

See ARCHITECTURE.md for complete technical details.

📚 Documentation

🧪 Testing

Running Tests

Quick Start (All Packages)

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @seatkit/types test
pnpm --filter @seatkit/utils test

API Tests (Requires Database)

API tests require a PostgreSQL test database and use GCP Secret Manager for credentials:

cd packages/api

# Authenticate with Google Cloud (required)
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=seatkit-dev

# Run API tests with automatic database setup
pnpm test:local

What test:local does:

  1. Fetches test database credentials from Secret Manager
  2. Runs migrations on the test database
  3. Executes all tests with Vitest

Alternative: Run tests manually:

# Set up test database first
pnpm db:migrate:test

# Then run tests
TEST_DATABASE_URL="postgresql://localhost:5432/seatkit_test" pnpm test

# Or in watch mode
TEST_DATABASE_URL="postgresql://localhost:5432/seatkit_test" pnpm test:watch

Test Database

Tests use a separate PostgreSQL database (seatkit_test) to avoid affecting development data:

🔒 Security

Secrets Management

SeatKit uses Google Cloud Secret Manager for production secrets. For local development:

Contributors: Use a local .env file (no GCP account needed) Core Team: Authenticate with gcloud auth application-default login Your Own Setup: Run pnpm secrets:setup to configure your GCP project

Secret Names (GCP)

Production and development secrets are stored with environment prefixes:

Replace dev with prod for production secrets.

Authentication Flow

  1. Try GCP Secret Manager (if GOOGLE_CLOUD_PROJECT is set)
  2. Fallback to .env file (in development mode)
  3. Fail if neither is available

See SECURITY.md for security policies and best practices.

🤝 Contributing

We welcome contributions! This project is in early development, so there’s plenty to do.

Ways to Contribute

Development Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/amazing-feature)
  3. Make your changes
  4. Run tests and linting (pnpm test && pnpm lint)
  5. Commit with conventional commits (git commit -m "feat: add amazing feature")
  6. Push to your fork (git push origin feat/amazing-feature)
  7. Open a Pull Request

See DEVELOPMENT.md for coding standards.

📋 Current Progress

✅ Phase 1: Foundation (Complete)

🚧 Phase 2: Backend API (In Progress)

🚧 Phase 3: Frontend (In Progress)

See docs/FEATURES.md for complete roadmap.

📄 License

This project is licensed under the Apache License 2.0 - see LICENSE.md for details.

Third-Party Notices

See NOTICE.md for third-party software attributions.

🙏 Acknowledgments

📞 Support

Built with ❤️ for small restaurants

This site is open source. Improve this page.