Skip to content

CLAUDE.md

Latest commit

 

History

History
230 lines (166 loc) · 5.75 KB

CLAUDE.md

File metadata and controls

230 lines (166 loc) · 5.75 KB

CLAUDE.md - GitHub Profile Trophy

Attach to conversations about github-profile-trophy only.

Component Context

Architecture

Runtime: Deno (TypeScript) Entry Point: main.ts → api/index.ts Cache: Redis/Valkey for GitHub API response caching

Key Files

File Purpose
main.ts HTTP server entry point
api/index.ts Request handler, routing logic
src/config/cache.ts Redis/Valkey cache provider
src/card.ts SVG trophy card rendering
src/trophy.ts Trophy calculation logic
deps.ts Deno dependencies

Platform Dependencies

Required (Core)

Dependency Purpose
ingress External HTTPS access via github-trophies.solidrust.net
cert-manager Automatic SSL certificates (DNS-01)

Optional (Services)

Service Purpose Integration
data/valkey API response caching Set ENABLE_REDIS=true, REDIS_HOST, REDIS_PORT
observability Metrics collection Add ServiceMonitor to k8s/

External Dependencies

Endpoint Purpose Required
api.github.com GitHub user data Yes
valkey.shared-data-layer.svc.cluster.local:6379 Cache No

Dependency Declaration (Machine-Readable)

dependencies:
  requires:
    core:
      - ingress
      - cert-manager
    services: []
  optional:
    services:
      - data/valkey
      - observability
  external:
    - endpoint: "api.github.com"
      purpose: "GitHub API for user stats"
      required: true
    - endpoint: "valkey.shared-data-layer.svc.cluster.local:6379"
      purpose: "Redis-compatible cache"
      required: false

Building

Local Development

# Run locally
deno run --allow-net --allow-env --allow-read --allow-write main.ts

# With cache (requires local Redis/Valkey)
ENABLE_REDIS=true REDIS_HOST=localhost REDIS_PORT=6379 \
  deno run --allow-net --allow-env --allow-read --allow-write main.ts

Docker Build

# Build image
docker build -t github-profile-trophy .

# Run locally
docker run -p 8080:8080 -e GITHUB_TOKEN=ghp_xxx github-profile-trophy

# Build and push to Gitea registry
docker build -t poseidon.hq.solidrust.net:30008/shaun/github-profile-trophy:v1.0.0 .
docker push poseidon.hq.solidrust.net:30008/shaun/github-profile-trophy:v1.0.0

Deployment

Deployed to srt-hq-k8s via FluxCD:

  • Manifests: /Users/shaun/repos/srt-hq-k8s/manifests/apps/github-trophies/
  • Image: poseidon.hq.solidrust.net:30008/shaun/github-profile-trophy
  • Namespace: github-trophies

Manual Trigger

# Force Flux reconciliation
flux reconcile ks github-trophies

# Check deployment status
kubectl get pods -n github-trophies
kubectl logs -n github-trophies -l app=github-trophies

Access

Configuration

Environment Variables

Variable Required Description
GITHUB_TOKEN Yes GitHub Personal Access Token for API access
PORT No HTTP port (default: 8080)
ENABLE_REDIS No Enable caching (true/false)
REDIS_HOST No Redis/Valkey hostname
REDIS_PORT No Redis/Valkey port (default: 6379)
REDIS_USERNAME No Redis auth username (if required)
REDIS_PASSWORD No Redis auth password (if required)

Secrets (Kubernetes)

Secret Namespace Keys
github-token github-trophies token

Troubleshooting

Common Issues

  1. Redis AUTH error with Valkey

    • Valkey runs without authentication by default
    • Don't set REDIS_USERNAME or REDIS_PASSWORD unless auth is enabled
    • The cache.ts fix conditionally includes auth only when env vars are set

  2. GitHub API rate limiting

    • Enable Redis caching to reduce API calls
    • Verify GITHUB_TOKEN is valid

  3. Pod not starting

    kubectl describe pod -n github-trophies -l app=github-trophies
kubectl logs -n github-trophies -l app=github-trophies

  4. Cache not working

    # Verify Valkey connectivity
kubectl exec -n shared-data-layer deploy/valkey -- redis-cli KEYS "*"

Development Notes

Fork Maintenance

This is a fork with self-hosting modifications:

  • Fixed Valkey AUTH issue (empty credentials trigger AUTH)
  • Removed Vercel-specific artifacts
  • Optimized Dockerfile for production
  • Added health endpoint for Kubernetes probes

Upstream Sync

git remote add upstream https://github.com/ryo-ma/github-profile-trophy.git
git fetch upstream
git merge upstream/master --no-commit
# Resolve conflicts, keeping our modifications

User Preferences

When working on this app:

  • Complete, production-ready solutions
  • Run commands directly (no permission prompts)
  • NO workarounds or temp fixes
  • Prefer Deno best practices

References

  • Platform: /Users/shaun/repos/srt-hq-k8s/PLATFORM.md
  • Main CLAUDE.md: /Users/shaun/repos/srt-hq-k8s/CLAUDE.md
  • K8s Manifests: /Users/shaun/repos/srt-hq-k8s/manifests/apps/github-trophies/
  • Upstream Docs: https://github.com/ryo-ma/github-profile-trophy

Version: 1.0 | Updated: 2026-01-23