MyClub/central-directory/README.md

# 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

```json
{
  "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

```dockerfile
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

```yaml
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:

```env
# 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:

```typescript
// 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
```bash
curl https://directory.myclub.cz/api/v1/health
```

### Statistics
```bash
curl https://directory.myclub.cz/api/v1/stats
```

### Logs
The service logs:
- New club registrations
- Instance updates
- Cleanup activities
- Authentication failures

## Development

### Local Development
```bash
cd cmd/central-directory
export DIRECTORY_TOKEN=dev-token
go run .
```

### Testing Registration
```bash
# 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
```bash
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