# dance-lessons-coach

[![Build Status](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/actions/workflows/ci-cd.yaml/badge.svg)](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/actions/workflows/ci-cd.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/arcodange/dance-lessons-coach)](https://goreportcard.com/report/github.com/arcodange/dance-lessons-coach)
[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![BDD Coverage](https://img.shields.io/badge/BDD_Coverage-51.1%%-red?style=flat-square)](https://gitea.arcodange.lab/arcodange/dance-lessons-coach)
[![UNIT Coverage](https://img.shields.io/badge/UNIT_Coverage-8.9%%-red?style=flat-square)](https://gitea.arcodange.lab/arcodange/dance-lessons-coach)

Go web service demonstrating idiomatic package structure, versioned JSON API, and production-ready features.

## Features

- Versioned JSON API (`/api/v1`, `/api/v2`)
- Chi router with graceful shutdown
- Zerolog structured logging (console and JSON modes)
- Viper configuration (file + env vars)
- Readiness endpoint for Kubernetes / service mesh
- OpenTelemetry / Jaeger distributed tracing
- OpenAPI / Swagger UI (embedded in binary)
- PostgreSQL user service with JWT auth
- BDD + unit tests

## Quick Start

```bash
git clone https://gitea.arcodange.lab/arcodange/dance-lessons-coach.git
cd dance-lessons-coach
./scripts/build.sh          # produces ./bin/server and ./bin/greet
./scripts/start-server.sh start
```

```bash
curl http://localhost:8080/api/health
curl http://localhost:8080/api/v1/greet/Alice
```

Stop: `./scripts/start-server.sh stop`

## Greet CLI

```bash
go run ./cmd/greet           # Hello world!
go run ./cmd/greet Alice     # Hello Alice!
```

## Configuration

All options are available via `config.yaml` or `DLC_*` environment variables.

| Env var | Default | Description |
|---------|---------|-------------|
| `DLC_SERVER_PORT` | `8080` | Listening port |
| `DLC_SERVER_HOST` | `0.0.0.0` | Bind address |
| `DLC_LOGGING_JSON` | `false` | JSON log format |
| `DLC_LOGGING_OUTPUT` | stderr | Log file path |
| `DLC_SHUTDOWN_TIMEOUT` | `30s` | Graceful shutdown window |
| `DLC_API_V2_ENABLED` | `false` | Enable `/api/v2` routes |
| `DLC_CONFIG_FILE` | `./config.yaml` | Override config path |

See `config.example.yaml` for a full template.

## API

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/health` | Liveness check |
| GET | `/api/ready` | Readiness check (503 during shutdown) |
| GET | `/api/version` | Version info (`?format=plain\|full\|json`) |
| GET | `/api/v1/greet/` | Default greeting |
| GET | `/api/v1/greet/{name}` | Named greeting |
| POST | `/api/v2/greet` | V2 greeting with validation |
| GET | `/swagger/` | Swagger UI |

## Testing

```bash
go test ./...                          # unit + integration tests
./scripts/test-graceful-shutdown.sh    # lifecycle + JSON logging validation
./scripts/test-opentelemetry.sh        # tracing end-to-end
```

## Gitea Client

AI agent helper script at `.vibe/skills/gitea-client/scripts/gitea-client.sh`.

Auth setup:
```bash
echo "your_token" > ~/.gitea_token
chmod 600 ~/.gitea_token
export GITEA_API_TOKEN_FILE="$HOME/.gitea_token"
```

Get a token at https://gitea.arcodange.lab → Profile → Settings → Applications.

## Architecture

Key decisions are documented in [adr/](adr/). See [AGENTS.md](AGENTS.md) for the full development reference (commands, config, ADR index, commit conventions).

## License

MIT