hot fix #1

2026-06-04 10:42:57 +00:00 · 2026-01-26 08:13:18 +01:00
parent aa036b6550
commit dfc079288f
505 changed files with 95755 additions and 5712 deletions
@@ -0,0 +1,211 @@
+# 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