diff --git a/hyperfleet/docs/naming-conventions.md b/hyperfleet/docs/naming-conventions.md
new file mode 100644
index 0000000..4d4df80
--- /dev/null
+++ b/hyperfleet/docs/naming-conventions.md
@@ -0,0 +1,866 @@
+# HyperFleet Naming Conventions Guide
+
+**Version**: 1.0
+**Date**: 2025-12-06
+**Status**: Draft for Review
+
+## Purpose
+
+This document defines standard naming conventions for concepts, components, and infrastructure across all HyperFleet repositories to ensure consistency, reduce cognitive load, and improve maintainability.
+
+**Scope**: This guide focuses on **conceptual naming** (major concerns and components), not general coding style.
+
+---
+
+## Table of Contents
+
+1. [Domain Concepts](#1-domain-concepts)
+2. [Architecture Patterns](#2-architecture-patterns)
+3. [Infrastructure Components](#3-infrastructure-components)
+4. [Configuration & Secrets](#4-configuration--secrets)
+5. [Observability](#5-observability)
+6. [API & HTTP Conventions](#6-api--http-conventions)
+7. [Database Schema](#7-database-schema)
+8. [Kubernetes Resources](#8-kubernetes-resources)
+9. [Messaging & Events](#9-messaging--events)
+10. [Repository Naming](#10-repository-naming)
+11. [Binary Naming](#11-binary-naming)
+12. [Makefile Conventions](#12-makefile-conventions)
+13. [Package & Module Naming](#13-package--module-naming)
+
+---
+
+## 1. Domain Concepts
+
+### 1.1 Resource Types
+
+**Standard**: Use **PascalCase** for resource type names in code, **lowercase** in URLs/config
+
+| Concept | Code (Type) | URL/Config | Plural | Database Table |
+|---------|-------------|------------|--------|----------------|
+| Cluster | `Cluster` | `cluster` | `clusters` | `clusters` |
+| Node Pool | `NodePool` | `nodepool` | `nodepools` | `node_pools` |
+| Adapter Status | `AdapterStatus` | `adapter_status` | `adapter_statuses` | `adapter_statuses` |
+
+### 1.2 Resource Phases
+
+**Standard**: Use **PascalCase** constants, **exact string values** in database
+
+| Phase | Constant Name | String Value | Description |
+|-------|---------------|--------------|-------------|
+| Not Ready | `PhaseNotReady` | `"NotReady"` | Resource not yet ready |
+| Provisioning | `PhaseProvisioning` | `"Provisioning"` | Resource being created |
+| Ready | `PhaseReady` | `"Ready"` | Resource is operational |
+| Failed | `PhaseFailed` | `"Failed"` | Resource in error state |
+| Terminating | `PhaseTerminating` | `"Terminating"` | Resource being deleted |
+| Terminated | `PhaseTerminated` | `"Terminated"` | Resource deleted |
+
+### 1.3 Condition Types
+
+**Standard**: Use **PascalCase** for condition types (Kubernetes-style)
+
+| Condition Type | Usage | Status Values |
+|----------------|-------|---------------|
+| `Ready` | Overall resource readiness | `True`, `False`, `Unknown` |
+| `Available` | Resource availability | `True`, `False` |
+| `Progressing` | Operation in progress | `True`, `False` |
+| `Degraded` | Partial functionality | `True`, `False` |
+
+**Note**: Status values are capitalized (`"True"`, `"False"`), not lowercase.
+
+### 1.4 Field Names
+
+**Standard**: Use **snake_case** in JSON/YAML and database, **PascalCase** in Go structs
+
+| Concept | JSON/YAML | Go Struct | Database Column | Description |
+|---------|-----------|-----------|-----------------|-------------|
+| Resource ID | `id` | `ID` | `id` | Unique identifier |
+| Created time | `created_time` | `CreatedTime` | `created_time` | Creation timestamp |
+| Updated time | `updated_time` | `UpdatedTime` | `updated_time` | Last update timestamp |
+| Generation | `generation` | `Generation` | `generation` | Spec version counter |
+| Observed generation | `observed_generation` | `ObservedGeneration` | `observed_generation` | Last processed version |
+| Status phase | `status_phase` | `StatusPhase` | `status_phase` | Current phase |
+| Owner ID | `owner_id` | `OwnerID` | `owner_id` | Parent resource ID |
+
+---
+
+## 2. Architecture Patterns
+
+### 2.1 Component Suffixes
+
+**Standard**: Use consistent suffixes for component types
+
+| Component Type | Suffix | Interface Name | Implementation | Package |
+|----------------|--------|----------------|----------------|---------|
+| Service layer | `Service` | `ClusterService` | `sqlClusterService` | `pkg/services/` |
+| Data access | `Dao` | `ClusterDao` | `sqlClusterDao` | `pkg/dao/` |
+| HTTP handler | `Handler` | `ClusterHandler` | `clusterHandler` (private) | `pkg/handlers/` |
+| HTTP client | `Client` | `HyperFleetClient` | `httpClient` (private) | `pkg/client/`, `internal/client/` |
+| Business logic | `Engine` | `DecisionEngine` | `decisionEngine` (private) | `internal/engine/` |
+| Configuration | `Config` | `SentinelConfig` | N/A | `pkg/config/`, `internal/config/` |
+| Middleware | `Middleware` | `AuthMiddleware` | `jwtMiddleware` (private) | `pkg/middleware/` |
+
+**Pattern**: Public interfaces use PascalCase, private implementations use camelCase.
+
+
+Service/DAO/Handler Pattern Example
+
+```go
+// Service Layer
+type ClusterService interface {
+ Get(ctx context.Context, id string) (*Cluster, error)
+ Create(ctx context.Context, cluster *Cluster) (*Cluster, error)
+}
+
+type sqlClusterService struct {
+ dao ClusterDao
+}
+
+// DAO Layer
+type ClusterDao interface {
+ Get(ctx context.Context, id string) (*Cluster, error)
+ List(ctx context.Context, args *ListArgs) ([]*Cluster, error)
+}
+
+type sqlClusterDao struct {
+ sessionFactory *SessionFactory
+}
+
+// Handler Layer
+type ClusterHandler interface {
+ List(w http.ResponseWriter, r *http.Request)
+ Get(w http.ResponseWriter, r *http.Request)
+}
+
+type clusterHandler struct {
+ service ClusterService
+}
+```
+
+
+
+### 2.2 Logger Naming
+
+TBC in https://issues.redhat.com/browse/HYPERFLEET-323
+
+**Standard**: `HyperFleetLogger` interface across all repositories
+
+We should standarize in:
+- Configuration
+- Output (e.g. JSON)
+- Common log fields
+
+### 2.3 Error Types
+
+**Standard**: `ServiceError` for business errors, `APIError` for HTTP client errors
+
+```go
+const ErrorCodePrefix = "hyperfleet"
+
+type ServiceError struct {
+ Code ServiceErrorCode
+ Reason string
+ HttpCode int
+ Details []ValidationDetail
+}
+
+type APIError struct {
+ Method string
+ URL string
+ StatusCode int
+ Retriable bool
+ Attempts int
+ Err error
+}
+```
+
+---
+
+## 3. Infrastructure Components
+
+### 3.1 Database Components
+
+| Component | Naming Convention | Example | Notes |
+|-----------|-------------------|---------|-------|
+| Database name | `hyperfleet_` | `hyperfleet_dev`, `hyperfleet_prod` | Lowercase with underscores |
+| Table names | `snake_case`, plural | `clusters`, `node_pools`, `adapter_statuses` | Lowercase, plural |
+| Column names | `snake_case` | `created_time`, `status_phase`, `owner_id` | Lowercase with underscores |
+| Index names | `idx__` | `idx_clusters_name`, `idx_adapter_statuses_owner` | Descriptive, snake_case |
+| Foreign keys | `fk__` | `fk_node_pools_clusters` | Explicit relationship |
+| Primary key | `id` | `id` | Always `id`, never `_id` |
+
+
+Complete Table Schema Example
+
+```sql
+CREATE TABLE clusters (
+ id VARCHAR(255) PRIMARY KEY,
+ name VARCHAR(63) NOT NULL UNIQUE,
+ spec JSONB NOT NULL,
+ labels JSONB,
+ generation INTEGER NOT NULL DEFAULT 1,
+ status_phase VARCHAR(50) NOT NULL DEFAULT 'NotReady',
+ status_observed_generation INTEGER NOT NULL DEFAULT 0,
+ created_time TIMESTAMP NOT NULL,
+ updated_time TIMESTAMP NOT NULL,
+ deleted_time TIMESTAMP,
+ created_by VARCHAR(255) NOT NULL,
+ updated_by VARCHAR(255) NOT NULL
+);
+
+CREATE INDEX idx_clusters_name ON clusters(name);
+CREATE INDEX idx_clusters_status_phase ON clusters(status_phase);
+
+CREATE TABLE node_pools (
+ id VARCHAR(255) PRIMARY KEY,
+ owner_id VARCHAR(255) NOT NULL REFERENCES clusters(id),
+ owner_kind VARCHAR(50) NOT NULL,
+ spec JSONB NOT NULL,
+ created_time TIMESTAMP NOT NULL
+);
+
+ALTER TABLE node_pools
+ ADD CONSTRAINT fk_node_pools_owner
+ FOREIGN KEY (owner_id) REFERENCES clusters(id);
+```
+
+
+
+### 3.2 Message Broker Components
+
+| Component | Naming Convention | Example | Environment Variable |
+|-----------|-------------------|---------|---------------------|
+| Topic name | `` | `Cluster`, `NodePool` | `BROKER_TOPIC` |
+| Queue/Subscription | `--sub` | `adapter-cluster-sub`, `sentinel-cluster-sub` | `BROKER_SUBSCRIPTION_ID` |
+| Exchange (RabbitMQ) | `hyperfleet` | `hyperfleet` | `BROKER_EXCHANGE` |
+| Exchange type | `topic` | `topic` | `BROKER_EXCHANGE_TYPE` |
+| Routing key | `.reconcile` | `Cluster.reconcile`, `NodePool.reconcile` | N/A |
+
+
+Broker Configuration Example
+
+```yaml
+# RabbitMQ
+broker:
+ type: rabbitmq
+ rabbitmq:
+ url: amqp://guest:guest@localhost:5672/
+ exchange: hyperfleet
+ exchange_type: topic
+
+topic: Cluster # PascalCase resource type
+subscription_id: dns-adapter-cluster-sub
+
+# Google Pub/Sub
+broker:
+ type: googlepubsub
+ googlepubsub:
+ project_id: hyperfleet-dev
+ topic: Cluster
+ subscription: sentinel-cluster-sub
+```
+
+
+
+### 3.3 Kubernetes Resources
+
+**Standard**: Follow Kubernetes naming conventions
+
+| Resource Type | Naming Pattern | Example | Labels |
+|---------------|----------------|---------|--------|
+| Namespace | `hyperfleet-` | `hyperfleet-dev`, `hyperfleet-prod` | `hyperfleet.io/environment` |
+| Deployment | `-` | `hyperfleet-api`, `dns-adapter`, `sentinel` | `app.kubernetes.io/name`, `app.kubernetes.io/component` |
+| Service | `` | `hyperfleet-api`, `dns-adapter` | `app.kubernetes.io/name` |
+| ConfigMap | `-config` | `hyperfleet-api-config`, `dns-adapter-config` | `hyperfleet.io/config-type` |
+| Secret | `-secret` | `hyperfleet-api-secret`, `dns-adapter-secret` | `hyperfleet.io/secret-type` |
+| ServiceAccount | `-sa` | `hyperfleet-api-sa`, `dns-adapter-sa` | `app.kubernetes.io/name` |
+
+
+Standard Kubernetes Labels
+
+```yaml
+metadata:
+ labels:
+ # Standard Kubernetes labels
+ app.kubernetes.io/name: hyperfleet-api
+ app.kubernetes.io/component: api-server
+ app.kubernetes.io/part-of: hyperfleet
+ app.kubernetes.io/version: "1.0.0"
+ app.kubernetes.io/managed-by: helm
+
+ # HyperFleet-specific labels
+ hyperfleet.io/environment: production
+ hyperfleet.io/tenant: shared
+ hyperfleet.io/adapter-type: dns # For adapters only
+```
+
+
+
+### 3.4 Container Images
+
+**Standard**: `//:`
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Development | `quay.io/hyperfleet/hyperfleet-api:dev` | `dev` tag for latest development |
+| Feature branch | `quay.io/hyperfleet/hyperfleet-api:feature-abc123` | Git branch + commit SHA |
+| Release | `quay.io/hyperfleet/hyperfleet-api:v1.2.3` | Semantic version with `v` prefix |
+| Stable | `quay.io/hyperfleet/hyperfleet-api:stable` | Latest stable release |
+
+---
+
+## 4. Configuration & Secrets
+
+### 4.1 Environment Variables
+
+**Standard**: Use `SCREAMING_SNAKE_CASE` with service prefix
+
+| Category | Prefix | Example | Description |
+|----------|--------|---------|-------------|
+| Database | `DB_` | `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` | Database connection |
+| Message Broker | `BROKER_` | `BROKER_TYPE`, `BROKER_RABBITMQ_URL`, `BROKER_TOPIC` | Message broker config |
+| HyperFleet API | `HYPERFLEET_API_` | `HYPERFLEET_API_BASE_URL`, `HYPERFLEET_API_VERSION` | API client config |
+| Authentication | `JWT_`, `OCM_` | `JWT_PUBLIC_KEY`, `OCM_CLIENT_ID`, `OCM_BASE_URL` | Auth configuration |
+| Kubernetes | `K8S_`, `KUBE_` | `K8S_NAMESPACE`, `KUBE_CONFIG_PATH` | Kubernetes config |
+| Application | `APP_` | `APP_ENV`, `APP_LOG_LEVEL`, `APP_PORT` | General app config |
+| Observability | `METRICS_`, `OTEL_` | `METRICS_PORT`, `OTEL_EXPORTER_ENDPOINT` | Monitoring config |
+
+### 4.2 Configuration Files
+
+**Standard**: Use `kebab-case` for filenames, `snake_case` for YAML keys
+
+| File Type | Naming Pattern | Example | Location |
+|-----------|----------------|---------|----------|
+| Main config | `.yaml` | `sentinel.yaml`, `adapter.yaml` | `configs/` |
+| Environment-specific | `-.yaml` | `sentinel-dev.yaml`, `adapter-prod.yaml` | `configs/` |
+| Example config | `-example.yaml` | `sentinel-example.yaml` | `configs/` |
+| Broker config | `broker.yaml` | `broker.yaml` | Project root |
+| Helm values | `values.yaml`, `values-.yaml` | `values.yaml`, `values-prod.yaml` | `charts//` |
+
+### 4.3 Secrets Management
+
+**Standard**: File-based secrets with standardized naming
+
+| Secret Type | Filename Pattern | Example | Kubernetes Secret Key |
+|-------------|------------------|---------|----------------------|
+| Database | `db.` | `db.host`, `db.password`, `db.user` | `db-host`, `db-password` |
+| API Token | `-token` | `hyperfleet-api-token`, `ocm-token` | `token` |
+| Certificate | `.` | `tls.crt`, `tls.key`, `ca.crt` | `tls.crt`, `tls.key` |
+| OAuth | `.client-` | `ocm.client-id`, `ocm.client-secret` | `client-id` |
+
+
+Secrets Directory Structure
+
+```
+secrets/
+├── db.host
+├── db.name
+├── db.user
+├── db.password
+├── db.port
+├── hyperfleet-api-token
+├── ocm.client-id
+├── ocm.client-secret
+├── tls.crt
+├── tls.key
+└── ca.crt
+```
+
+
+
+---
+
+## 5. Observability
+
+### 5.1 Metric Names
+
+**Standard**: Prometheus naming conventions with `hyperfleet_` prefix
+
+| Metric Type | Pattern | Example | Labels |
+|-------------|---------|---------|--------|
+| Counter | `hyperfleet_