MyClub/central-directory

MyClub Central Directory Service

This is the central directory service that enables the MyClub Mobile app to discover and connect to all MyClub-enabled clubs.

Architecture

The central directory service solves the cross-domain problem by providing a unified API for:

1. Club Registration: Each MyClub instance automatically registers itself
2. Heartbeat: Regular health checks to keep the directory current
3. Discovery: Mobile app queries this service to find all available clubs
4. Metadata: Rich information about each club including features, location, etc.

Features

API Endpoints

Public Endpoints

• GET /api/v1/clubs - List all active clubs (with search/filter)
• GET /api/v1/clubs/:id - Get specific club details
• GET /api/v1/health - Service health check
• GET /api/v1/stats - Directory statistics

Protected Endpoints (require token)

• POST /api/v1/directory/register - Register/update club instance
• POST /api/v1/directory/heartbeat - Send heartbeat

Data Model

{
  "club_id": "unique-club-identifier",
  "club_name": "FC Example",
  "api_base_url": "https://club.example.com/api/v1",
  "logo_url": "https://example.com/logo.png",
  "city": "Prague",
  "country": "Czechia",
  "is_active": true,
  "version": "1.0.0",
  "tags": {
    "instance_host": "club.example.com",
    "environment": "production",
    "instance_id": "club-example-com"
  },
  "features": ["dashboard", "news", "auth", "matches", "gallery"],
  "last_seen": "2025-01-09T15:00:00Z",
  "registered_at": "2025-01-09T10:00:00Z"
}

Deployment

Environment Variables

• PORT - Service port (default: 8083)
• DIRECTORY_TOKEN - Authentication token for club registration

Docker Deployment

FROM golang:1.21-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o central-directory ./cmd/central-directory

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/

COPY --from=builder /app/central-directory .
EXPOSE 8083

CMD ["./central-directory"]

Docker Compose

version: '3.8'
services:
  myclub-directory:
    build: ./cmd/central-directory
    ports:
      - "8083:8083"
    environment:
      - DIRECTORY_TOKEN=your-secure-token-here
    restart: unless-stopped

Integration

Club Instance Configuration

Each MyClub instance needs these environment variables:

# Directory registration
DIRECTORY_INGEST_URL=https://directory.myclub.cz/api/v1/directory/register
DIRECTORY_INGEST_TOKEN=directory-registration-token

# Existing error config
ERROR_INGEST_URL=https://errors.tdvorak.dev/api/v1/errors
ERROR_INGEST_TOKEN=error-ingest-token

Mobile App Configuration

The mobile app automatically uses the central directory:

// services/directory.ts
const CENTRAL_DIRECTORY_URL = 'https://directory.myclub.cz/api/v1/clubs';

// Automatic fallback to local data if central service is unavailable

Security

• Token-based authentication for club registration
• CORS enabled for mobile app access
• Automatic cleanup of inactive instances (1 hour timeout)
• Request rate limiting recommended for production

Monitoring

Health Check

curl https://directory.myclub.cz/api/v1/health

Statistics

curl https://directory.myclub.cz/api/v1/stats

Logs

The service logs:

• New club registrations
• Instance updates
• Cleanup activities
• Authentication failures

Development

Local Development

cd cmd/central-directory
export DIRECTORY_TOKEN=dev-token
go run .

Testing Registration

# Register a test club
curl -X POST https://localhost:8083/api/v1/directory/register \
  -H "Content-Type: application/json" \
  -H "X-Directory-Token: dev-token" \
  -d '{
    "club_id": "test-club",
    "club_name": "Test FC",
    "api_base_url": "https://test.example.com/api/v1",
    "city": "Test City",
    "country": "Czechia",
    "features": ["dashboard", "news", "auth"]
  }'

List Clubs

curl https://localhost:8083/api/v1/clubs

Production Deployment

1. Set up SSL certificate (Let's Encrypt recommended)
2. Configure firewall rules
3. Set up monitoring and alerting
4. Configure backup strategy
5. Set up log aggregation

Scaling

The service is designed to handle hundreds of club instances with minimal resource usage. For large-scale deployments:

• Consider adding database persistence for reliability
• Implement caching for frequently accessed data
• Add rate limiting to prevent abuse
• Set up load balancing for high availability

Troubleshooting

Common Issues

1. Club not appearing in directory

   • Check environment variables in club instance
   • Verify network connectivity to central directory
   • Check authentication token

2. Mobile app showing fallback data

   • Check central directory service status
   • Verify network connectivity
   • Check CORS configuration

3. Authentication failures

   • Verify DIRECTORY_TOKEN matches between services
   • Check token format (should be plain string)
   • Verify request headers