Stack

Stack is a workspace‑centric chat and collaboration app where organizations create workspaces from GitHub repositories and collaborate in real time around code.

Each workspace is backed by a GitHub repo and provides:

• Channels for discussion.
• Collaborative coding spaces tied to repository content.
• Integration with GitHub (webhooks for PRs, issues, etc.).
• A path to richer real‑time features (live editing, threads, etc.).

This repo contains the desktop web app (Next.js) and Convex backend.

---

Tech stack

• Frontend
  • Next.js 16 (App Router)
  • React 19
  • TypeScript
  • Tailwind CSS 4 / shadcn‑ui / Radix UI
• Backend
  • Convex (database + serverless functions)
  • Convex schema for users, workspaces, memberships, channels, messages, threads, integrations
• Auth
  • better-auth with GitHub OAuth
  • @convex-dev/better-auth Convex integration
• Integrations
  • GitHub webhook handling for PRs, issues, comments, reviews, pushes
  • Web Crypto API for webhook signature validation
  • Event processing to create threads/messages from GitHub events
• Desktop
  • Tauri 2 (Rust wrapper)

---

Project structure

apps/desktop/
├── app/                      # Next.js App Router pages
│   ├── (onboarding)/         # Login/onboarding flow
│   └── (workspace)/          # Workspace pages
├── components/               # React components
│   ├── ui/                   # shadcn/ui components
│   ├── workspace/            # Workspace-specific components
│   └── onboarding/           # Onboarding flow components
├── convex/                   # Convex backend
│   ├── schema.ts             # Database schema
│   ├── auth.ts               # Better-auth integration
│   ├── users.ts              # User queries/mutations
│   ├── workspace.ts          # Workspace CRUD
│   ├── channels.ts           # Channel queries
│   ├── messages.ts           # Message queries/mutations
│   ├── presence.ts           # User presence
│   ├── github.ts             # GitHub API (Octokit)
│   ├── http.ts               # HTTP routes (webhooks)
│   └── integrations/         # Integration providers
│       ├── types.ts          # Integration type definitions
│       └── github.ts         # GitHub provider
├── hooks/                    # Custom React hooks
├── lib/                      # Utilities
└── types/                    # Shared TypeScript types

---

Database Schema

Core Tables

• users - User profiles with auth info, status, avatar
• workspaces - Workspace entities (name, slug, icon)
• memberships - User-workspace relationships with roles
• channels - Text/voice channels within workspaces
• messages - Chat messages with thread support
• threads - Threaded conversations on messages
• presence - User online/offline status
• unread - Unread message counts

Integration Tables

• integrations - GitHub/Jira/Linear configs per workspace
• integrationEvents - Raw webhook events for processing
• integrationSettings - Channel mapping & event filters

---

Features

Current

• Auth: GitHub OAuth via Convex better-auth
• Onboarding: Multi-step workspace creation wizard with repo selection
• Workspaces: Full CRUD with members and roles
• Channels: Default channels (general, pull-requests, releases) + custom channels
• Messaging: Real-time chat with threads, @mentions, #channel mentions
• Message rendering: Rich embeds for URLs, attachments, mentions
• Consecutive grouping: Messages grouped by author with timestamps
• GitHub webhooks: Pull requests, issues, comments, reviews, pushes
• EmbedBuilder: Fluent API for Discord-style rich embeds
• Event processing: Creates threads/messages from GitHub events
• Integration routing: Webhook routing by workspace slug
• Integration settings: Channel mapping and event filters
• Project board: Kanban with drag-and-drop, tasks, labels, due dates, comments
• Unread counts: Per-channel unread tracking

In Progress

• OAuth flow UI: User-initiated GitHub OAuth (functions exist, UI not connected)
• Presence indicators: Real-time online/offline UI (schema exists)
• Jira/Linear integrations: Schema ready, handlers not implemented
• Event enrichment: enrichGithubEvent() function not wired into webhook flow
• Desktop app: Tauri setup exists, app not complete

---

Getting started

Prerequisites

• Node.js (LTS)
• pnpm
• GitHub OAuth app
• Convex account

Environment setup

Create .env.local in apps/desktop/:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-secret
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

Run the app

# Install dependencies
pnpm install

# Run Convex backend
npx convex dev

# Run Next.js app
pnpm dev

---

Integration System

Overview

Stack supports integrations with external services (GitHub, Jira, Linear). Each integration can:

• Receive webhooks
• Authenticate via OAuth
• Create threads/messages in configured channels

GitHub Integration

• Webhook events: pull_request, issues, issue_comment, pull_request_review, push
• OAuth: User authorization for repo access
• Message formatting: Rich embeds with PR/issue details, emoji indicators

Adding New Integrations

1. Add provider to integration.provider union in schema
2. Create provider file in convex/integrations/
3. Implement webhook parsing & validation
4. Add OAuth flow if needed
5. Create frontend settings UI

---

Roadmap

Completed

• Workspace creation wizard
• Real-time messaging with threads
• GitHub webhook integration
• Event processing → threads
• Rich embed rendering
• Project board (Kanban)

In Progress

• OAuth flow UI
• Presence indicators
• Jira/Linear integrations
• Desktop app (Tauri)

Backlog

• Real-time code collaboration
• Video/audio calls
• Search
• Notifications

---

Contributing

• Keep Convex schema and TypeScript types in sync
• Follow existing code patterns (Effect for error handling, Convex queries/mutations)
• Update this README when changing core flows