Gabriel Radureau
886cbab36d
AGENTS.md and README.md were stale since ~2026-04-11 (4 weeks). Updated to reflect magic-link + OIDC auth (ADR-0028), pkg/auth, pkg/email, pkg/user/api packages, and 30-ADR index. Endpoints listing decision : keep curated short list + pointer to swagger as source of truth (see body of changes). Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# dance-lessons-coach
|
|
|
|
[](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/actions/workflows/ci-cd.yaml)
|
|
[](https://goreportcard.com/report/github.com/arcodange/dance-lessons-coach)
|
|
[](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/releases)
|
|
[](LICENSE)
|
|
[](https://gitea.arcodange.lab/arcodange/dance-lessons-coach)
|
|
[](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, source of truth at `/swagger/doc.json`)
|
|
- Username + password authentication with JWT (rotating secrets)
|
|
- Passwordless magic-link authentication (email-delivered, ADR-0028 Phase A)
|
|
- OIDC authentication with PKCE (multi-provider, ADR-0028 Phase B)
|
|
- PostgreSQL user persistence with GORM
|
|
- BDD + unit tests (Godog)
|
|
- Mistral autonomous PR pattern (cf. [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](documentation/MISTRAL-AUTONOMOUS-PATTERN.md))
|
|
|
|
## 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
|
|
|
|
The full interactive list is in the Swagger UI at `/swagger/` (source of truth at `/swagger/doc.json`). Most-used endpoints :
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| GET | `/api/health` | Liveness check |
|
|
| GET | `/api/ready` | Readiness check (503 during shutdown) |
|
|
| GET | `/api/version` | Version info |
|
|
| GET | `/api/v1/greet/{name}` | Named greeting |
|
|
| POST | `/api/v1/auth/login` | Login (JWT) |
|
|
| POST | `/api/v1/auth/magic-link/request` | Passwordless magic-link |
|
|
| GET | `/api/v1/auth/oidc/{provider}/start` | OIDC login |
|
|
| GET | `/swagger/` | Swagger UI |
|
|
|
|
This decision is intentional : the markdown table drifts ; swagger.json doesn't (it's regenerated from `swag` annotations on every build). Curated short list here for discovery, swagger for completeness.
|
|
|
|
## 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
|