Naming Conventions

Consistent naming across the codebase makes it easier to navigate and understand. This page covers naming rules for Go, SQL, TypeScript, NATS subjects, and environment variables.

Go

Packages

• Lowercase, single word: store, domain, api, transport, worker, config
• No underscores or mixed case

Variables and Functions

• Unexported: camelCase -- hostID, clientSlug, parseInput
• Exported: PascalCase -- GetHost, RegisterAgent, NewServer

Errors

Sentinel errors use the Err prefix:

var (
    ErrNotFound     = errors.New("not found")
    ErrConflict     = errors.New("conflict")
    ErrInvalidInput = errors.New("invalid input")
)

Interfaces

Use descriptive names without prefixes. Follow the Go convention of naming single-method interfaces with an -er suffix:

type Reader interface { ... }
type Writer interface { ... }
type HostStore interface { ... }

Do not use IReader or IHostStore.

SQL

Tables

• snake_case, plural: hosts, clients, environments, metric_points

Columns

• snake_case: created_at, host_id, client_slug, os_version

Indexes

• Pattern: idx_{table}_{columns}
• Example: idx_hosts_client_id, idx_metric_points_host_id_collected_at

Foreign Keys

• Pattern: fk_{table}_{ref_table}
• Example: fk_hosts_clients, fk_environments_clients

TypeScript

Components

• PascalCase file names matching the component name:
  • HostDetail.tsx, ClientList.tsx, SidebarNav.tsx

Hooks

• camelCase with the use prefix:
  • usePolling.ts, useHosts.ts, useAuth.ts

Types and Interfaces

• PascalCase:
  • Host, Client, Environment, MetricPoint

Utility Files

• kebab-case:
  • date-utils.ts, api-client.ts, format-bytes.ts

NATS Subjects

Pattern

Agent data subjects are keyed by agent_id (not host_id — the two are distinct):

proxima.{client_slug}.{env_slug}.{agent_id}.{type}

Command Subjects

Backend-to-agent commands are published on a per-agent command channel, keyed by agent_id:

proxima.system.commands.{agent_id}

System Subjects

proxima.system.agent.config
proxima.system.agent.renew

Message Types

Type	Purpose
inventory	Host inventory data (OS, hardware, packages)
heartbeat	Agent liveness signal
metrics	System metrics (CPU, memory, disk)

Examples

proxima.acme-corp.production.agent-abc123.inventory
proxima.acme-corp.staging.agent-def456.metrics
proxima.system.commands.agent-abc123
proxima.system.agent.config
proxima.system.agent.renew

Environment Variables

Prefix

All project environment variables use the PROXIMA_ prefix.

Pattern

PROXIMA_{COMPONENT}_{SETTING}

Examples

Variable	Purpose
PROXIMA_DB_URL	PostgreSQL connection string
PROXIMA_NATS_URL	NATS server URL
PROXIMA_API_PORT	Backend HTTP port
PROXIMA_CORS_ORIGINS	Allowed CORS origins
PROXIMA_LOG_LEVEL	Logging level (debug, info, warn, error)
PROXIMA_INSTALL_TOKEN	Agent install token