Development

Local development workflow for the Pug backend, dashboard, and Web SDK.

Initial setup


git clone git@github.com:fivebitsio/cotton.git
cd cotton
cp .env.example .env
make infra-up     # Postgres, NATS, ClickHouse in Docker
make migrate      # All database migrations

make infra-up starts:

Service	Port	UI
Postgres	5432	—
ClickHouse	8123	—
NATS	4222	—

Running the stack

All services (recommended)


make dev    # Server + all workers with hot reload

Individual processes

Useful for debugging a specific worker:


# Terminal 1
pug server
 
# Terminal 2
pug worker events
 
# Terminal 3
pug worker profile
 
# Additional workers as needed
pug worker email
pug worker scheduler

Code generation

Regenerate after changing proto or SQL files:


make proto    # Regenerate Go/TS clients from proto/
make sqlc     # Regenerate Postgres query code from SQL

Proto definitions: proto/
SQL queries: sql/

Testing


make test     # Run all tests
make lint     # golangci-lint

Run a single package:


go test ./internal/events/...

Architecture docs

Deep dives in the cotton repo:

Doc	Topic
`docs/architecture/ingestion.md`	Event pipeline, NATS, workers
`docs/architecture/clickhouse.md`	Schema, queries, performance
`docs/architecture/profiles.md`	Identity model, async writes
`docs/architecture/insights.md`	Query engine, aggregations
`docs/architecture/email.md`	Magic links, transactional email

Frontend (cotton-ui)

Run the dashboard against your local API:


git clone git@github.com:fivebitsio/cotton-ui.git
cd cotton-ui
cp .env.example .env
# VITE_API_URL=http://localhost:8080
pnpm install
pnpm dev

Open http://localhost:5173 and sign in. Create a project and copy the API key for SDK testing.

Web SDK against local API


init('PROJECT_ID', {
  apiKey: 'KEY',
  endpoint: 'http://localhost:8080',
  dryRun: false
})

Verify in the dashboard Live page or:


curl -X POST http://localhost:8080/events.v1.EventsService/BatchCreate \
  -H "Authorization: Bearer YOUR_SDK_API_KEY" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{"events":[{"name":"dev_test","properties":{"source":"curl"}}]}'

Docs site

Run the docs locally:


git clone git@github.com:fivebitsio/docs.git
cd docs
npm install
npm run dev

Open http://localhost:3000/docs/overview .

Common issues

Symptom	Fix
`make infra-up` fails	Confirm Docker is running; check port conflicts on 5432/8123/4222
Migrations fail	Run `make infra-up` first; check Postgres is healthy
Events not appearing	Confirm event worker is running: `pug worker events`
Profile not updating	Confirm profile worker is running: `pug worker profile`
Dashboard can’t connect	Check `VITE_API_URL` matches server port
CORS errors from SDK	Confirm `endpoint` matches server URL exactly

Port reference

Port	Service
8080	Pug API server (default)
5432	Postgres
8123	ClickHouse HTTP
4222	NATS
5173	cotton-ui dev server
3000	docs dev server