pulse-lets-go/docs/development.md

Development

Requirements

• Go 1.26+
• Node.js 22+
• NATS Server (auto-downloaded via make nats)

Build

git clone git@git.totmin.ru:en2zmax/pulse-lets-go.git
cd pulse-lets-go
make build

Makefile Commands

Command	Description
make build	Full build (Go + SvelteKit)
make dev	Go backend + SvelteKit dev server (hot-reload)
make test	Go tests with coverage
make test-race	Tests with race detector
make lint	go vet ./...
make fmt	go fmt ./...
make build-agent	Build pulse-lets-go-agent
make build-siptest	Build SIP tester
make emulate-*	Metrics emulation (normal, overload, chaos, stale, ...)
make siptest-*	SIP testing (uas, uac, full)
make nats	Start local NATS server

Running Locally

# Terminal 1: NATS
make nats

# Terminal 2: balancer
./bin/pulse-lets-go

# Terminal 3: metrics emulator (3 healthy nodes)
make emulate-normal

Code Style

Before committing:

make fmt
make lint
make test

Project Structure

pulse-lets-go/
├── cmd/
│   ├── pulse-lets-go/       # Main entry point
│   ├── pulse-lets-go-agent/ # Metrics collector (FS / Asterisk)
│   ├── emulator/            # Metrics emulator for testing
│   └── siptest/             # SIP tester for e2e checks
├── internal/
│   ├── api/                 # HTTP handlers (auth, nodes, trunks, users, monitoring, ws, route)
│   ├── config/              # JSON config manager (atomic save, thread-safe)
│   ├── engine/              # Scoring engine + router (sync.RWMutex, best-node cache)
│   ├── esl/                 # FreeSWITCH ESL client (raw TCP)
│   ├── ami/                 # Asterisk AMI client (raw TCP)
│   ├── log/                 # ASCII metrics logger with rotation
│   ├── models/              # Data types (NodeMetric, NodeState, Trunk, User, ...)
│   └── nats/                # NATS subscriber
├── contrib/                 # route.lua, agent configs
├── deploy/                  # systemd unit
├── web/                     # SvelteKit frontend
└── data/                    # Runtime JSON files (gitignored)

Adding a New Endpoint

1. Define model in internal/models/types.go
2. Implement handler in internal/api/<name>.go
3. Register route in internal/api/router.go with required middleware (auth, admin)
4. Add tests in internal/engine/engine_test.go if scoring is affected

Commit Messages

Conventional Commits format:

feat: add support for custom scoring weights
fix: handle nil ESL client in route handler
docs: add API reference table to README
refactor: extract scoring logic into separate method
test: add lethal condition tests for stale nodes
chore: update Go dependencies

Implementation Order

1. cmd/pulse-lets-go/main.go + Go module + пустая структура internal/
2. internal/models/ — все типы данных
3. internal/config/ — чтение/запись JSON, атомарное сохранение
4. internal/nats/ — подписка, in-memory store
5. internal/engine/ — scorer + router
6. internal/api/ — все хендлеры
7. internal/log/ — ASCII-логгер + ring buffer
8. Web-фронт (SvelteKit)
9. Makefile + systemd unit
10. Тесты + graceful shutdown

PR Process

1. Branch from main, named feature/, fix/, or docs/
2. One PR — one logical change
3. All tests pass (make test)
4. Code passes make lint
5. If API changes — update docs