Buttonz

Buttonz is the standalone communication app for the GameForgeStudio ecosystem. It gives GameForgeStudio users a focused place to join shared channels, create chats, send messages, and keep community/team communication separate from the main platform hub.

This project is framed as professional progress: the current app demonstrates the core communication architecture, identity handoff, session flow, database-backed chat model, and full-stack implementation. It is intentionally kept separate from GameForgeStudio so it can evolve as its own product while still using GFS as the identity and navigation layer.

Tech Stack

Layer	Tools
Frontend	React 19, TypeScript, Vite, TanStack Query
UI	Tailwind CSS, Radix UI primitives, Lucide icons
Backend	Node.js, Express 5, TypeScript, Express sessions
Data	PostgreSQL, Drizzle ORM, postgres.js
Validation	Zod, drizzle-zod, shared TypeScript schemas
Build	Vite client build, tsx server runtime

Features

Communication Experience

• Main GameForge channel created automatically for verified users.
• User-created group chats with membership checks.
• Message creation, editing, deletion, and paginated message reads.
• Chat list ordered by recent activity.
• User directory view for GameForgeStudio identities.

GameForgeStudio Identity Flow

• Direct Buttonz login is disabled by design.
• Users are expected to sign in through GameForgeStudio first.
• Buttonz exchanges a short-lived GFS auth code through GAMEFORGE_API_URL and creates a local Buttonz session.
• Client requests use credentials: "include" so session cookies are included with API calls.
• The UI gets return-to-GameForgeStudio behavior from the Buttonz backend's GAMEFORGE_PUBLIC_URL config.

Product Direction

Buttonz is not embedded inside GFS. It is a separate app that GFS launches externally, which keeps communication concerns isolated from the main platform while still preserving ecosystem continuity.

Architecture

Buttonz uses a focused full-stack TypeScript structure:

client/          React app, Buttonz UI, hooks, query client, public logo assets
server/          Express server, auth/session flow, routes, storage layer, Vite integration
shared/          Drizzle table definitions, Zod insert schemas, shared app types

Frontend

• React renders a single Buttonz app surface from client/src/pages/buttonz.tsx.
• TanStack Query manages server state for the current user, chats, messages, and users.
• Vite serves the frontend locally on port 5175 and proxies /api requests to the Buttonz backend.
• Tailwind and Radix-based components provide a compact chat UI with accessible primitives.

Backend

• Express owns authentication code exchange, session creation, chat routes, message routes, and user lookup.
• POST /api/auth/gfs-session exchanges a GFS-issued code before creating a Buttonz session.
• Protected routes require a Buttonz session and chat membership where appropriate.
• Errors are returned through JSON responses with HTTP status codes.

Data Model

• users stores GameForgeStudio-compatible identity/profile data used by Buttonz.
• chats stores main and user-created chat channels.
• chatMembers connects users to chats and stores chat roles.
• messages stores text messages, timestamps, edit state, and optional replies.

Local Development

1. Install dependencies

npm install

2. Configure environment variables

Copy .env.example to .env and fill in values for your local database and GameForgeStudio app.

DATABASE_URL=postgresql://username:password@host/database?sslmode=require
MIGRATION_DATABASE_URL=postgresql://username:password@host/database?sslmode=require
SESSION_SECRET=replace-with-a-long-random-secret
PORT=5001
GAMEFORGE_APP_ID=buttonz
GAMEFORGE_PUBLIC_URL=http://localhost:5173
GAMEFORGE_API_URL=http://localhost:5000
USE_VITE_MIDDLEWARE=false

3. Prepare the database

Buttonz expects a PostgreSQL database with the schema defined in shared/schema.ts. Run npm run db:push before starting against a new database. GFS identities are mirrored into Buttonz after a successful backend authorization-code exchange.

4. Run the app locally

For the most predictable development setup, run the backend and frontend separately:

npm run dev:server
npm run dev:client

The Vite dev server runs on http://localhost:5175 and proxies API traffic to the backend on http://127.0.0.1:5001.

5. Run checks and build

npm run check
npm run build

Scripts

Command	Description
npm run dev	Start the Buttonz backend with tsx.
npm run dev:server	Start the backend server directly.
npm run dev:client	Start the Vite frontend dev server.
npm run check	Run TypeScript type checking.
npm run build	Build the frontend and compile the Express server.
npm run start	Run the compiled production server.
npm run db:push	Push the Buttonz schema to PostgreSQL.

Production Runtime

Buttonz builds its React client and Express API into one deployable service. For Render, use Node 22, npm ci --include=dev && npm run build, npm start, and /api/health as the health-check path.

• Use a pooled Neon connection for DATABASE_URL at runtime.
• Use Neon's direct connection for MIGRATION_DATABASE_URL during db:push.
• Set NODE_ENV=production and USE_VITE_MIDDLEWARE=false.
• Generate a unique SESSION_SECRET containing at least 32 characters.
• Configure GAMEFORGE_PUBLIC_URL and GAMEFORGE_API_URL with the GFS HTTPS Render URL; runtime code does not fall back to localhost.

Current Status

Buttonz is active and in progress. The app currently demonstrates the standalone communication model, GFS session handoff, protected chat APIs, database-backed storage, and a dedicated chat-focused interface.

The next phase is focused on making the app more production-shaped: clearer deployment flow, stronger cross-app authentication strategy, more complete chat UX, and cleaner operational boundaries between Buttonz and GameForgeStudio.

Related Project

• GameForgeStudio - central GameForgeStudio platform hub.