Repository avatar
AI Tools
v0.3.0
active

meetplus

io.github.rakaaaa/meetplus

Create and publish timed MeetPlus meetups and questionnaires from ChatGPT or Claude.

Documentation

MeetPlus

MeetPlus is a pnpm monorepo for server-authoritative timed meetups. The backend uses Fastify, TypeScript, PostgreSQL, Redis pub/sub, secure cookie sessions, Argon2, Zod, multipart image uploads, and SMTP.

Prerequisites

  • Node.js 20 or newer
  • Corepack (included with standard Node.js 20 installations)
  • Docker Desktop or another Docker installation with Compose v2

If node, corepack, or docker compose is unavailable, install or enable the missing prerequisite and ensure it is on PATH. Docker must be running before the startup script is used.

Quick start

Single command (validates prerequisites, starts Docker services, migrates, runs API + web):

node run.mjs

Or use any of these equivalents:

PlatformCommand
Any (recommended)corepack pnpm start
Windowsrun.bat
macOS / Linuxchmod +x run.sh && ./run.sh

The script is safe to run repeatedly. It:

  1. Validates Node.js 20+, Docker, and Compose v2.
  2. Creates .env from .env.example only when .env does not exist.
  3. Installs packages with the pinned Corepack-managed pnpm version.
  4. Starts PostgreSQL 16, Redis 7, and Mailpit and waits until they are healthy.
  5. Runs database migrations.
  6. Starts the API and web dev servers (pnpm dev).

When startup finishes, open the web app at http://localhost:5173 (or your WEB_ORIGIN in .env).

The API is available at http://localhost:3001; health is at /health.

Services

  • PostgreSQL: localhost:5432
  • Redis: localhost:6379
  • Mailpit SMTP: localhost:1025
  • Mailpit UI: http://localhost:8025

Values can be changed in .env. Existing .env files are never overwritten by the startup scripts.

Workspace layout

  • apps/api — Fastify API, SQL migrations, media adapter, and maintenance jobs
  • apps/web — React/Vite admin and participant web application
  • apps/android — Kotlin/Compose hardened WebView shell
  • packages/shared — Zod schemas, inferred API types, and shared utilities

Commands

Run commands through Corepack to ensure the pinned pnpm version is used:

corepack pnpm dev
corepack pnpm build
corepack pnpm typecheck
corepack pnpm lint
corepack pnpm test
corepack pnpm migrate

Stack verification

These are stack-level checks, not unit tests. Both commands require a running Docker daemon with Compose v2. They start PostgreSQL, Redis, and Mailpit, apply migrations, launch the required application processes, and fail early with a clear prerequisite message when Docker is unavailable.

Install the Playwright Chromium browser once before the browser checks:

corepack pnpm exec playwright install chromium

Run the real API integration scenario:

corepack pnpm test:integration

It registers two admins and two participants and verifies owner isolation, meetup creation, code/link joining and join idempotency, server-timed active questions, immutable/idempotent answers, selected-count privacy, a question boundary transition, completion, and owner-grouped results against PostgreSQL, Redis, and the running API.

Run browser smoke and workflow checks:

corepack pnpm test:e2e

Playwright runs Chromium in desktop and mobile viewport projects. It covers the public authentication routes plus key admin creation and participant joining flows, and treats uncaught page errors, console errors, failed requests, and HTTP 5xx responses as failures. To point an already configured invocation at other endpoints, set PLAYWRIGHT_BASE_URL and PLAYWRIGHT_API_URL.

MCP server

mcp-servers/meetplus is an MCP server for AI clients. It lets ChatGPT/Claude/Gemini-style clients ask the right planning questions, create draft meetups and questionnaires, append a questionnaire to a draft, preview deterministic timing, validate, publish/cancel with explicit confirmation, and fetch the host-only invitation only when asked.

  • stdio for trusted local clients such as Claude Desktop, Cursor, Claude Code and Gemini CLI.
  • Streamable HTTP at https://<host>/mcp for ChatGPT and Claude.ai connectors, with OAuth 2.1 (dynamic client registration, PKCE, scoped tokens, rotation and revocation). Set MCP_PUBLIC_URL to enable it; it stays off when unset.

It reuses the real API and shared contracts; it does not query PostgreSQL or Redis. Setup, client configuration and security notes are in mcp-servers/meetplus/README.md and docs/mcp/.

ChatGPT, Claude.ai and Claude Code setup is in docs/mcp/client-setup.md. The remote connector uses the existing api and gateway containers; no separate MCP container is required. The public integration page is /integrations/mcp, and the official MCP Registry listing is built from mcp-servers/meetplus/server.json.

Naming

  • Workspace packages are @meetplus/*; use corepack pnpm --filter @meetplus/api.
  • The ops CLI is deploy/meetplus.sh. deploy/meetcon.sh remains as a compatibility shim.
  • MEETPLUS_* ops variables are accepted first, with MEETCON_* fallbacks.
  • Docker project/image names, database names, the session cookie and the Android application ID intentionally keep their historical meetcon values so existing deployments, data volumes and Play updates keep working.

Backend

Copy .env.example to .env and replace TOKEN_ENCRYPTION_KEY outside local development. Generate it with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Run corepack pnpm migrate after PostgreSQL is healthy. Migrations are checksummed and serialized with a PostgreSQL advisory lock.

The API exposes:

  • Email/password plus LinkedIn, Google, X, Facebook and Instagram registration, login/logout/session restoration, password reset/change, LinkedIn-account password setup, and active-session revoke
  • Social invitation sharing to LinkedIn, X, Facebook and Gmail, plus native-share/copy fallback for Instagram
  • Profile editing, image upload/removal, theme/time-zone settings, LinkedIn disconnect, consent history/export, and anonymized deletion
  • Owner-isolated draft/published meetup CRUD with version checks, descriptions, locations, meeting links, cover URLs, duplication, draft deletion, and cancellation reasons
  • Code/token invitation preview, including anonymous preview before sign-in, and idempotent participant joining
  • Joined meetup lists with cancelled-meetup history, leaving, calendar export, server-authoritative active state, immutable answers, and live SSE updates
  • Live host controls for start now, pause/resume, next question, next questionnaire, and end meetup now
  • Owner-only grouped results, participant rosters/non-responders, live display mode, and raw or summary CSV exports
  • Question reminders, cancellation notifications, AI drafting through OAuth or a personal API key, and participant end-of-meetup recaps

Social sign-in setup

Each provider is optional. Set the client id and secret in .env (or the Jenkins secret file in production). The default callback URL is ${WEB_ORIGIN}/api/auth/<provider>/callback.

ProviderScopesNotes
LinkedInopenid profile emailRequires “Sign In with LinkedIn using OpenID Connect”.
Googleopenid email profileUses Google OpenID userinfo.
Xusers.read tweet.readPKCE; X does not return an email address.
Facebookemail,public_profileEmail is used when Facebook returns it.
Instagraminstagram_business_basicInstagram Login requires a professional account; no email is returned.

X and Instagram accounts are created with a private placeholder address when the provider does not return an email. The user can replace it from Profile. Social sign-in identities are stored in user_social_identities; existing LinkedIn identities are backfilled by migration 003_social_identities.sql.

Production website (port 30098)

Production is a separate Docker stack from local development. Local run.bat starts project meetcon (PostgreSQL, Redis, Mailpit only) and runs the app on the host. Production starts project meetcon-prod and runs the API, web, and database entirely in Docker.

LocalProductionSimulation
Startrun.bat / node run.mjsrun-production.bat / node run-production.mjs./deploy/meetplus.sh simulate
Compose projectmeetconmeetcon-prodmeetcon-sim
Env file.env.env.production.env.simulation
What Docker runsPostgres, Redis, MailpitGateway, API, Postgres, RedisSame services, isolated volumes
App imagesnone (host pnpm dev)meetcon-api:<git-sha>, meetcon-gateway:<git-sha>meetcon-api:simulation, meetcon-gateway:simulation
URLhttp://localhost:5173https://meetcon.aiadoptionecosystem.comhttps://127.0.0.1:30998

run-production refuses to start when .env.production still has the local password, a localhost database URL, or an http:// origin. Compose is started with COMPOSE_DISABLE_ENV_FILE=1, so the local .env cannot override it. Each production deploy tags images with the git commit. meetcon-api:production is an alias of that commit. Roll back with MEETCON_IMAGE_TAG=<older-sha>.

For an Ubuntu VM with Docker, use the production stack documented in deploy/DEPLOYMENT.md. It exposes only HTTPS port 30098 on the gateway, serves the React build, and proxies /api and /media to the internal API.

Quick start on the VM:

cp .env.production.example .env.production
# edit secrets. WEB_ORIGIN=https://meetcon.aiadoptionecosystem.com (port 30098 stays internal)
# add deploy/certs/fullchain.pem and deploy/certs/privkey.pem
chmod +x deploy/meetplus.sh
./deploy/meetplus.sh up

Or: corepack pnpm deploy:up. Ops guide: deploy/README.md. Jenkins: Build Now (deploy/jenkins/README.md).

Files added for production:

Session cookies are Secure in production. WEB_ORIGIN is the public site https://meetcon.aiadoptionecosystem.com. Docker still listens on port 30098 behind that name. The Android release app uses the same origin in a full-screen WebView with no URL bar.

Forgot-password mail is captured locally at http://localhost:8025. Expired sessions and reset tokens are cleaned hourly while the API is running.

To stop local services:

docker compose down

Add --volumes to that command only when you intentionally want to delete local PostgreSQL and Redis data.

No installation packages available.