Run the inbox where your team can see the boundaries.

02 / local setup

Get a complete development stack running.

The root development compose file provides PostgreSQL, NATS, Centrifugo, Meilisearch, and MinIO. The root bun run devcommand starts the application processes, including the web and marketing servers.

Quick start

git clone https://github.com/ygncode/wateaminbox.git
cd wateaminbox

# Create the ignored local environment file.
cp .env.example .env

# Install JavaScript dependencies and fetch Go dependencies during builds.
bun install

# Start PostgreSQL, NATS, Centrifugo, Meilisearch, and MinIO.
docker compose up -d

# Create the central and tenant database structures.
bun run db:migrate

# Start the web app, API, workers, and marketing site.
bun run dev

Open the web app at http://localhost:4444. The API is athttp://localhost:4445/api; the marketing site useshttp://localhost:4446.

Local service map

NATS monitoring is available at http://localhost:8222. The optional NATS toolbox can be started withdocker compose --profile debug up -d nats-box.

03 / configuration

Configure the runtime without guessing.

The checked-in root .env.example is the authoritative development inventory. Copy it, then change the secrets and any hostnames that differ from the defaults. Environment variables are loaded from the repository root when commands run from the root.

Browser URLs

The web client defaults to the local API URL. Set these values when the browser reaches the API or Centrifugo through a different host, port, or TLS endpoint:

VITE_API_URL=http://localhost:4445/api
VITE_CENTRIFUGO_URL=ws://localhost:4451/connection/websocket

The static marketing site and waitlist

The marketing site is a static Astro build. Its Cloud waitlist form uses the explicit build-time PUBLIC_WAITLIST_API_URL; it does not guess a missing /api proxy. If this copy is self-hosted without a waitlist Worker, leave the value unset and the form explains that no signup service is configured.

# Separate Worker origin for a self-hosted marketing deployment.
PUBLIC_WAITLIST_API_URL=https://waitlist-api.example.com

# Optional public Turnstile site key; the Worker validates the token server-side.
PUBLIC_WAITLIST_TURNSTILE_SITE_KEY=your-public-site-key

The documented Cloudflare Pages setup uses the same-origin Worker route at https://wateaminbox.com. Use that value only when the reviewed route exists; otherwise use the real Worker origin. See the Cloud waitlist guide ↗.

04 / WhatsApp connections

Pair a device, then let the sync settle.

1. 1
   Create and verify your user.

   Open the web app at your configured APP_URL, register, and verify the email link. Create a workspace or accept an invitation.

2. 2
   Open Settings → Connections.

   Add a named WhatsApp connection. The default maximum is five active or pending connections; a company-level setting can change that limit.

3. 3
   Scan the pairing QR code.

   On the phone, open WhatsApp → Settings → Linked Devices → Link a Device, then scan the code shown by the workspace. The code expires quickly; restart the pairing attempt if the UI reports expiry.

4. 4
   Watch the initial history sync.

   Messages, contacts, groups, receipts, and available media are imported through the worker and API. The UI exposes sync progress; a connected account may continue processing history after pairing.

05 / teams and access

Make visibility and ownership explicit.

Access is workspace-scoped. Roles provide defaults, while the owner can apply custom permissions to admins and members. Conversation visibility is not automatically global: withoutcan_view_all_chats, a member normally sees active assignments.

06 / implemented features

A capability map, not a roadmap.

These are the main surfaces represented by the current web, API, database, and worker code. Feature access still depends on role, connection state, migrations, and configuration.

07 / production self-hosting

Use the hardened baseline, then do your own review.

Do not promote the development docker-compose.yml to production. The repository's compose.production.ymlis a single-host baseline with Caddy at the edge and private data services. It is deployment guidance, not a hosted service or a guarantee of production readiness for every environment.

08 / API guide

Integrate against the routes that exist.

The API base is /api in the documented reverse-proxy shape, or http://localhost:4445/api locally. Most workspace routes require a short-lived bearer access token and theX-Company-ID header. Refresh tokens are held in an HttpOnly cookie; do not copy server secrets into browser variables.

Authorization: Bearer <access-token>
X-Company-ID: <workspace-uuid>

The canonical send route is POST /api/messages.POST /api/conversations/:id/messages remains for compatibility and is deprecated. Export routes return CSV, JSON, or ZIP rather than only JSON. See the route source ↗ for the current surface.

Realtime transport

The browser obtains a short-lived token fromPOST /api/realtime/token and connects to the configured Centrifugo WebSocket endpoint. Events invalidate or update local UI state; clients reconcile with PostgreSQL-backed API reads after reconnects.

message:new
message:status
contact:updated
connection:status
notification:new
labels:updated
catalogs:updated