Skip to main content

Contributing

This guide covers the workflow and conventions for contributing to Proxima Console.

Development Workflow​

  1. Create a feature branch from main:

    git checkout -b MNG-XXX
    # or
    git checkout -b feat/description

  2. Read the relevant standards in docs/standards/*.md for the area you are working on.

  3. Write code with tests. All new features must have at least 70% test coverage before merging to main.

  4. Run linters and tests before pushing:

    make lint && make test

  5. Open a merge request. The CI pipeline must pass before merging.

  6. No direct commits to main. All changes go through merge requests.

Key Conventions​

No ORM​

We use raw SQL with sqlx for all database access. There is no ORM in this project. Queries are explicit and easy to reason about.

REST + Polling + SSE (with deliberate exceptions)​

The public API is REST with polling and Server-Sent Events (SSE). Three surfaces are deliberately not:

  • WebSocket (served) — the interactive terminal at /api/v1/terminal/ws, and /api/v1/terminal/ws/join for collaborative sessions.
  • WebSocket (client) — the backend connects out to Asterisk ARI for voice paging.
  • gRPC — the terminal service consumed by the pc CLI (terminal, proxy-ssh, port-forward tunnels), served on PROXIMA_GRPC_PORT.

Anything else should be REST.

Config via Environment Variables​

All configuration is loaded from environment variables. Never hardcode secrets or connection strings in source code. See docs/standards/config.md for the full configuration loading order.

Structured Logging​

Use slog with JSON output for all logging. No fmt.Println or unstructured log calls.

slog.Info("host registered",
    "component", "worker",
    "host_id", hostID,
)

Error Wrapping​

Always wrap errors with context using fmt.Errorf:

if err != nil {
    return fmt.Errorf("fetching host by id: %w", err)
}

Pre-commit Hooks​

Pre-commit hooks are configured via .pre-commit-config.yaml and run automatically on each commit. They enforce formatting, linting, and other checks before code reaches CI.

Useful Commands​

make help              # List all available commands
make docker-up         # Start the local dev stack (PostgreSQL, NATS, Valkey, VictoriaMetrics, VictoriaLogs, Tempo, Grafana, Vault, …)
make test              # Run all tests
make lint              # Run all linters
make build             # Build all binaries
make migrate-up        # Apply database migrations
make seed              # Seed development data
make test-e2e          # Run end-to-end smoke tests
make run-backend       # Start the backend server
make run-agent         # Start the agent
make run-frontend      # Start the frontend dev server
note

make test-e2e builds the binaries and frontend, then uploads and runs the BATS + Playwright suites against a remote infrastructure host over SSH (requires E2E_HOST and an SSH key). It is typically CI-only — for local development use make test and make test-integration.

After Completing a Task​

  1. Run make test && make lint && make test-race to confirm a clean state.
  2. Run make test-e2e for any new features that touch NATS messages, API endpoints, or database writes.
  3. Update CHANGELOG.md with entries under ## [Unreleased].
  4. Commit with a conventional commit message: feat(agent): add host inventory [MNG-101].
  5. Add a Jira comment summarizing the work, decisions made, and edge cases found.
  6. Update Confluence if the change involves new architecture, APIs, or runbooks.