# Clone the repository
git clone https://github.com/yourusername/DanceLessonsCoach.git
cd DanceLessonsCoach

# Build all binaries
./scripts/build.sh

# Use the new Cobra CLI
./bin/dance-lessons-coach --help

# Or use the legacy greet CLI
go run ./cmd/greet

Configuration

Basic configuration options:

# Start with default configuration
./scripts/start-server.sh start

# Custom port
export DLC_SERVER_PORT=9090
./scripts/start-server.sh start

# JSON logging
export DLC_LOGGING_JSON=true
./scripts/start-server.sh start

See AGENTS.md for comprehensive configuration guide including:

File-based configuration
Environment variables
Configuration priority rules
OpenTelemetry setup
Advanced scenarios

Usage

New Cobra CLI (Recommended)

# Show help
./bin/dance-lessons-coach --help

# Show version
./bin/dance-lessons-coach version

# Greet someone
./bin/dance-lessons-coach greet John

# Start server
./bin/dance-lessons-coach server

Legacy CLI (Deprecated)

# Default greeting
go run ./cmd/greet
# Output: Hello world!

# Custom greeting
go run ./cmd/greet John
# Output: Hello John!

Web Server

Using the server control script (recommended):

# Start the server
./scripts/start-server.sh start

# Test API endpoints
./scripts/start-server.sh test

# Access OpenAPI documentation
# Swagger UI: http://localhost:8080/swagger/
# OpenAPI spec: http://localhost:8080/swagger/doc.json

# Stop the server
./scripts/start-server.sh stop

Manual server management:

# Start the server
go run ./cmd/server

# Test API endpoints
curl http://localhost:8080/api/health
# Output: {"status":"healthy"}

curl http://localhost:8080/api/ready
# Output: {"ready":true}

curl http://localhost:8080/api/v1/greet
# Output: {"message":"Hello world!"}

curl http://localhost:8080/api/v1/greet/John
# Output: {"message":"Hello John!"}

Testing

# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/greet/

Project Structure

DanceLessonsCoach/
├── adr/                    # Architecture Decision Records
├── cmd/                    # Entry points (greet CLI, server)
├── pkg/                    # Core packages (config, greet, server, telemetry)
│   └── server/docs/        # Generated OpenAPI documentation (gitignored)
├── config.yaml             # Configuration file
├── scripts/                # Management scripts
└── go.mod                   # Go module definition

See AGENTS.md for detailed structure and component explanations.


## Development

### Generate OpenAPI Documentation

The project uses [swaggo/swag](https://github.com/swaggo/swag) to generate OpenAPI/Swagger documentation from code annotations:

```bash
# Generate documentation
go generate ./pkg/server/

# This creates:
# - pkg/server/docs/docs.go (swagger template)
# - pkg/server/docs/swagger.json (OpenAPI spec)
# - pkg/server/docs/swagger.yaml (YAML version)

Note: pkg/server/docs/ is gitignored. Documentation is embedded in the binary at build time.

Documentation Annotations

Add swagger annotations to handlers and models:

// @Summary Get personalized greeting
// @Description Returns a greeting with the specified name
// @Tags greet
// @Accept json
// @Produce json
// @Param name path string true "Name to greet"
// @Success 200 {object} GreetResponse "Successful response"
// @Failure 400 {object} ErrorResponse "Invalid name parameter"
// @Router /v1/greet/{name} [get]
func (h *apiV1GreetHandler) handleGreetPath(w http.ResponseWriter, r *http.Request) {
    // handler implementation
}

Architecture

This project uses Architecture Decision Records (ADRs) to document key technical choices. See adr/ for complete documentation including decisions on Go 1.26.1, Chi router, Zerolog, OpenTelemetry, interface-based design, graceful shutdown, configuration management, testing strategies, and OpenAPI documentation.

Adding new decisions? See adr/README.md for guidelines.

License

MIT

Languages

Go 71.2%

Shell 21.7%

Gherkin 3.9%

TypeScript 1.4%

Vue 0.5%

Other 1.2%