ankouros/samakia-evaluations repository overview

⁠samakia-evaluations

⁠Overview

Samakia Evaluations lets breeders record evaluations for birds against breed standards and view per‑item averages over time.

• JWT/OIDC‑protected REST API with global prefix /evaluations.
• Persists to MariaDB schema DB_DATABASE_EVALUATIONS.
• Emits Prometheus metrics at /metrics and health at /evaluations/health.
• Publishes events (future) for analytics and notifications.

⁠Ports & Health

• Port: EVALUATIONS_APP_PORT (default 3700).
• Health: GET /evaluations/health (also responds at / and /health).

⁠Configuration (via @samakia-platform/config)

• Database: DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_DATABASE_EVALUATIONS.
• Auth verify: AUTH_JWT_* keys.
• RabbitMQ (optional; planned): RABBITMQ_*.
• Logging: LOG_LEVEL.

⁠Endpoints (JWT required)

• GET /evaluations/birds/:birdId → list evaluations
• POST /evaluations/birds/:birdId → create evaluation (scorecard + items)
• GET /evaluations/:id → fetch with items
• PATCH /evaluations/:id → update (replace items supported)
• DELETE /evaluations/:id
• GET /evaluations/:id/report → summarised report

⁠Docker

docker run --rm -p 3700:3700 \
  -e DB_HOST=... -e DB_PORT=3306 -e DB_USER=... -e DB_PASSWORD=... \
  -e DB_DATABASE_EVALUATIONS=samakia_evaluations \
  -e AUTH_JWT_ISSUER=https://sso.samakia.net/realms/samakia-ecosystem -e AUTH_JWT_AUDIENCE=samakia-platform \
  -e AUTH_JWT_PUBLIC_KEY="$(cat jwk_pub.pem)" \
  docker.io/<namespace>/samakia-evaluations:latest

⁠Kubernetes

• Overlay: ops/k8s/samakia-evaluations (Deployment/Service/Ingress evaluations.samakia.net).
• Secrets via ExternalSecrets: mariadb-env, platform-config, auth-env.

⁠Visual Map

flowchart TD
  n1["Overview"]
  n2["Ports & Health"]
  n3["Configuration (via @samakia-platform/config)"]
  n4["Endpoints (JWT required)"]
  n5["Docker"]
  n6["Kubernetes"]
  n1 --> n2
  n1 --> n3
  n1 --> n4
  n1 --> n5
  n1 --> n6