Order-Service

[GENERATED TelemetryFlow SDK] Order-Service - RESTful API with DDD + CQRS Pattern

Architecture

This project follows Domain-Driven Design (DDD) with CQRS (Command Query Responsibility Segregation) pattern.

order-service/
├── cmd/
│   └── api/
│       └── main.go               # Application entry point
├── internal/
│   ├── domain/                   # Domain Layer
│   │   ├── domain.go             # Domain types and interfaces
│   │   ├── entity/               # Domain entities (Order, OrderItem)
│   │   └── repository/           # Repository interfaces (contracts)
│   ├── application/              # Application Layer (CQRS)
│   │   ├── command/              # Write operations (Create, Update, Delete)
│   │   ├── query/                # Read operations (Get, List)
│   │   ├── handler/              # Command & Query handlers
│   │   └── dto/                  # Data Transfer Objects
│   └── infrastructure/           # Infrastructure Layer
│       ├── config/               # Configuration loading (env, YAML)
│       ├── http/                 # HTTP transport
│       │   ├── server.go         # Echo server setup
│       │   ├── router.go         # Route registration
│       │   ├── handler/          # HTTP handlers (auth, order, swagger, health)
│       │   └── middleware/       # Middleware (JWT auth, CORS, rate limit, logger)
│       └── persistence/          # Database implementations (GORM/PostgreSQL)
├── pkg/                          # Shared packages
│   ├── logger/                   # Structured logging
│   ├── response/                 # HTTP response helpers
│   ├── safefile/                 # Safe file operations
│   └── validator/                # Request validation (Echo-compatible)
├── telemetry/                    # TelemetryFlow SDK integration
│   ├── init.go                   # SDK initialization and shutdown
│   ├── logs/                     # Log signal configuration
│   ├── metrics/                  # Metric signal configuration
│   └── traces/                   # Trace signal configuration
├── configs/                      # Service configurations
│   ├── config.yaml               # Application defaults
│   ├── otel/                     # TFO Collector pipeline config
│   ├── prometheus/               # Prometheus scrape config + alerting rules
│   ├── alertmanager/             # Alertmanager routing config
│   ├── grafana/                  # Dashboards + datasource/dashboard provisioning
│   ├── loki/                     # Loki OTLP ingestion + retention config
│   └── jaeger/                   # Sampling strategies
├── docs/                         # Documentation
│   ├── api/                      # OpenAPI spec (openapi.yaml, swagger.json)
│   ├── diagrams/                 # ERD, DFD (Mermaid)
│   ├── postman/                  # Postman collection + environment
│   ├── githooks/                 # Git hook scripts
│   └── wiki/                     # Wiki pages (Getting Started, Architecture, etc.)
├── tests/                        # Tests (external test packages)
│   ├── unit/                     # Unit tests (no I/O)
│   │   ├── application/          # Command/query handler tests
│   │   ├── domain/               # Entity and domain logic tests
│   │   ├── infrastructure/       # Middleware, config, HTTP handler tests
│   │   ├── observability/        # Prometheus rule validation tests
│   │   ├── pkg/                  # Validator, response helper tests
│   │   └── telemetry/            # SDK initialization tests
│   ├── integration/              # Integration tests (require Docker)
│   │   ├── observability/        # Live Prometheus/Alertmanager queries
│   │   ├── api_test.go           # API endpoint integration tests
│   │   └── order_api_test.go     # Order CRUD integration tests
│   ├── e2e/                      # End-to-end tests
│   ├── mocks/                    # Shared mock implementations
│   └── fixtures/                 # Test data fixtures
├── migrations/                   # Database migration files
├── scripts/                      # Utility scripts (hooks, run, test)
├── .github/                      # GitHub Actions (CI, Docker, Release)
├── Dockerfile                    # Multi-stage Docker build
├── docker-compose.yml            # Profile-based orchestration (db, app, monitoring, platform, all)
├── docker-compose.prometheus.yml # Prometheus-only compose override
├── Makefile                      # Build, test, lint, migrate automation
├── .golangci.yml                 # Linter configuration
├── go.mod                        # Go module definition
└── go.sum                        # Dependency checksums

Quick Start

Prerequisites

Go 1.26+
PostgreSQL 18+
Docker & Docker Compose (recommended)

Setup

Clone the repository
Copy environment file:
```
cp .env.example .env
```
Edit .env with your configuration
Install dependencies:
```
make deps
```
Run migrations:
```
make migrate-up
```
Start the server:
```
make run
```

Docker Compose

The easiest way to run the service with all dependencies:

# Start all services (PostgreSQL + API + TFO Collector + Prometheus + Alertmanager + Grafana + Jaeger + Loki)
docker compose --profile all up -d

# Or use profiles for selective startup
docker compose --profile db up -d         # Start only PostgreSQL
docker compose --profile app up -d        # Start API + PostgreSQL + Collector
docker compose --profile monitoring up -d # Start Collector + Prometheus + Alertmanager + Grafana + Jaeger + Loki

# Rebuild after code changes
docker compose --profile app up -d --build api

# Stop all services
docker compose --profile all down

# View logs
docker compose --profile app logs -f api

Profiles

Profile	Services
`db`	PostgreSQL
`app`	API (Order Service)
`monitoring`	TFO-Collector, Prometheus, Alertmanager, Grafana, Jaeger, Loki
`platform`	TFO-Backend, TFO-Viz, PostgreSQL, ClickHouse, Valkey, NATS
`all`	All services

# Start platform services for end-to-end observability
docker compose --profile platform up -d

# Start development stack
docker compose --profile db --profile app --profile monitoring up -d

# Start everything
docker compose --profile all up -d

Services

Service	Container	Port	Description
PostgreSQL	`TFO-SDK-PostgreSQL`	5432	Order database
API	`TFO-SDK-Order-Service`	8080	RESTful API
TFO-Collector	`TFO-SDK-OTEL`	4317, 4318, 8889, 13133, 55679, 1777	TelemetryFlow Collector (v1.3.0)
Prometheus	`TFO-SDK-Prometheus`	9090	Metrics collection + exemplars
Alertmanager	`TFO-SDK-Alertmanager`	9093	Alert routing
Grafana	`TFO-SDK-Grafana`	3001	Dashboards (metrics + logs + traces correlation)
Jaeger	`TFO-SDK-Jaeger`	16686	Distributed tracing UI
Loki	`TFO-SDK-Loki`	3100	Log aggregation (OTLP native)
TFO-Backend	`TFO-Platform-Backend`	8081	TelemetryFlow Platform API (platform profile)
TFO-Viz	`TFO-Platform-Viz`	3000	TelemetryFlow Visualization UI (platform profile)

OTEL Collector Ports

Port	Protocol	Description
4317	gRPC	OTLP gRPC (v1 & v2)
4318	HTTP	OTLP HTTP (v1 & v2)
8889	HTTP	Prometheus metrics
13133	HTTP	Health check
55679	HTTP	zPages (debugging)
1777	HTTP	pprof (profiling)

OTLP Endpoints (Dual Ingestion)

The collector supports both TelemetryFlow (v2) and OTEL Community (v1) endpoints:

TelemetryFlow Platform (Recommended):

POST http://localhost:4318/v2/traces
POST http://localhost:4318/v2/metrics
POST http://localhost:4318/v2/logs

OTEL Community (Backwards Compatible):

POST http://localhost:4318/v1/traces
POST http://localhost:4318/v1/metrics
POST http://localhost:4318/v1/logs

gRPC: localhost:4317 (both v1 and v2)

Network Configuration

All services run on a custom Docker network order_service_net with subnet 172.152.0.0/16:

Service	IP Address
API	172.152.152.10
PostgreSQL	172.152.152.20
TFO Collector	172.152.152.30
Prometheus	172.152.152.50
Alertmanager	172.152.152.55
Loki	172.152.152.60
Jaeger	172.152.152.65
Grafana	172.152.152.70

Development

Running locally

# Build and run
make run

# Run with hot reload
make dev

# Run tests
make test

# Build binary
make build

Adding a new entity

Use the TelemetryFlow RESTful API Generator:

telemetryflow-restapi entity -n Product -f 'name:string,price:float64,stock:int'

This generates:

Domain entity
Repository interface & implementation
CQRS commands & queries
HTTP handlers
Database migration

API Documentation

Documentation	Location
OpenAPI Spec	`docs/api/openapi.yaml`
Swagger JSON	`docs/api/swagger.json`
ERD Diagram	`docs/diagrams/ERD.md`
DFD Diagram	`docs/diagrams/DFD.md`
Postman Collection	`docs/postman/collection.json`

API Endpoints

Method	Endpoint	Description
GET	`/health`	Health check
POST	`/api/v1/auth/token`	Generate JWT access token (public)
GET	`/api/v1/orders`	List all orders
POST	`/api/v1/orders`	Create order
GET	`/api/v1/orders/:id`	Get order by ID
PUT	`/api/v1/orders/:id`	Update order
DELETE	`/api/v1/orders/:id`	Delete order
GET	`/api/v1/orders/:order_id/items`	List items in an order
POST	`/api/v1/orders/:order_id/items`	Add an item to an order
GET	`/api/v1/orders/:order_id/items/:id`	Get an item within an order
PUT	`/api/v1/orders/:order_id/items/:id`	Update an item within an order
DELETE	`/api/v1/orders/:order_id/items/:id`	Remove an item from an order

Configuration

Configuration is loaded from environment variables and .env file.

Application Configuration

Variable	Description	Default
`SERVER_PORT`	HTTP server port	`8080`
`SERVER_READ_TIMEOUT`	Read timeout	`15s`
`SERVER_WRITE_TIMEOUT`	Write timeout	`15s`
`ENV`	Environment (development/production)	`development`

Database Configuration

Variable	Description	Default
`DB_DRIVER`	Database driver	`postgres`
`DB_HOST`	Database host	`localhost`
`DB_PORT`	Database port	`5432`
`DB_NAME`	Database name	`orders`
`DB_USER`	Database user	`postgres`
`DB_PASSWORD`	Database password	-
`DB_SSL_MODE`	SSL mode	`disable`
`DB_MAX_OPEN_CONNS`	Max open connections	`25`
`DB_MAX_IDLE_CONNS`	Max idle connections	`5`
`DB_CONN_MAX_LIFETIME`	Connection max lifetime	`5m`

JWT Configuration

Variable	Description	Default
`JWT_SECRET`	JWT signing secret	-
`JWT_REFRESH_SECRET`	JWT refresh secret	-
`JWT_EXPIRATION`	Token expiration	`24h`
`JWT_REFRESH_EXPIRATION`	Refresh token expiration	`168h`

TelemetryFlow / OpenTelemetry Configuration

Variable	Description	Default
`TELEMETRYFLOW_API_KEY_ID`	TelemetryFlow API Key ID	-
`TELEMETRYFLOW_API_KEY_SECRET`	TelemetryFlow API Key Secret	-
`TELEMETRYFLOW_ENDPOINT`	OTLP endpoint	`localhost:4317`
`TELEMETRYFLOW_SERVICE_NAME`	Service name	`Order-Service`
`TELEMETRYFLOW_SERVICE_VERSION`	Service version	`1.4.4`

Docker Compose Configuration

Image versions and container settings are defined in .env (see .env.example for the full list). Highlights:

Variable	Description	Default
`POSTGRES_VERSION`	PostgreSQL image version	`18-alpine`
`PROMETHEUS_VERSION`	Prometheus image version	`v3.13.2`
`ALERTMANAGER_VERSION`	Alertmanager image version	`v0.33.1`
`GRAFANA_VERSION`	Grafana image version	`13.1.1`
`LOKI_VERSION`	Loki image version	`3.7.4`
`JAEGER_VERSION`	Jaeger image version	`1.76.0`
`TFO_COLLECTOR_VERSION`	TFO Collector image version	`1.3.0`
`VALKEY_VERSION`	Valkey image version	`8-alpine`
`PORT_GRAFANA`	Grafana host port	`3001`
`PORT_JAEGER_UI`	Jaeger UI host port	`16686`
`PORT_LOKI`	Loki host port	`3100`
`PORT_OTEL_GRPC`	Collector OTLP gRPC port	`4317`
`PORT_OTEL_HTTP`	Collector OTLP HTTP port	`4318`
`PORT_OTEL_METRICS`	Collector Prometheus port	`8889`

Testing

# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests
make test-integration

# Generate coverage report
make test-coverage

Docker

# Build image
make docker-build

# Run container
make docker-run

# Start all services (app + database + monitoring)
make docker-compose-up

# Stop all services
make docker-compose-down

Observability

The service is instrumented with OpenTelemetry for:

Traces: Distributed tracing for request flows
Metrics: Application and runtime metrics
Logs: Structured logging

The OpenTelemetry Collector receives telemetry data and fans each signal out to multiple backends:

TelemetryFlow Platform (via platform profile - TFO-Backend + TFO-Viz)
Prometheus (metrics + span_metrics exemplars)
Jaeger (traces)
Loki (logs, OTLP native with traceId correlation)

Unified Grafana Dashboard

Start the monitoring profile for a single dashboard correlating metrics, logs, and traces:

docker compose --profile monitoring up -d

Open Grafana at http://localhost:3001 (admin / admin) → Dashboards → Order Service → "Observability Overview". Datasources and the dashboard are auto-provisioned. Click a Prometheus exemplar dot to open its trace in Jaeger; click a log line's traceId to jump to the trace.

Prometheus Metrics

Access metrics at: http://localhost:8889/metrics (collector) and http://localhost:9090 (Prometheus UI).

TelemetryFlow Platform

For full observability visualization, start the platform profile:

docker compose --profile platform up -d

This brings up TFO-Backend, TFO-Viz, and supporting infrastructure (PostgreSQL, ClickHouse, Valkey, NATS) for end-to-end telemetry visualization.

Navigation Menu

Uh oh!

Repository files navigation

Order-Service

Architecture

Quick Start

Prerequisites

Setup

Docker Compose

Profiles

Services

OTEL Collector Ports

OTLP Endpoints (Dual Ingestion)

Network Configuration

Development

Running locally

Adding a new entity

API Documentation

API Endpoints

Configuration

Application Configuration

Database Configuration

JWT Configuration

TelemetryFlow / OpenTelemetry Configuration

Docker Compose Configuration

Testing

Docker

Observability

Unified Grafana Dashboard

Prometheus Metrics

TelemetryFlow Platform

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
.kiro		.kiro
cmd/api		cmd/api
configs		configs
docs		docs
internal		internal
migrations		migrations
pkg		pkg
scripts		scripts
telemetry		telemetry
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.prometheus.yml		docker-compose.prometheus.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Order-Service

Architecture

Quick Start

Prerequisites

Setup

Docker Compose

Profiles

Services

OTEL Collector Ports

OTLP Endpoints (Dual Ingestion)

Network Configuration

Development

Running locally

Adding a new entity

API Documentation

API Endpoints

Configuration

Application Configuration

Database Configuration

JWT Configuration

TelemetryFlow / OpenTelemetry Configuration

Docker Compose Configuration

Testing

Docker

Observability

Unified Grafana Dashboard

Prometheus Metrics

TelemetryFlow Platform

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages