MyClub/README.md

MyClub - Football Club Management System

A comprehensive content management system for football clubs, featuring visual page building, team management, match tracking, and engagement tools.

🚀 Quick Start

# Clone and start with Docker (recommended)
git clone <repository-url>
cd fotbal-club
make docker-up

# Or manual setup
docker-compose up -d postgres
cd backend && go run main.go &
cd frontend && npm start

Visit: http://localhost:3000 (frontend) | http://localhost:8080 (API)

📋 System Requirements

Minimum Requirements

• RAM: 2GB
• CPU: 1 core
• Storage: 10GB free space
• OS: Linux/macOS/Windows (with Docker)

Recommended Requirements

• RAM: 4GB+
• CPU: 2+ cores
• Storage: 20GB+ SSD
• OS: Ubuntu 20.04+ / CentOS 8+ / macOS 12+

Dependencies

• Docker: 20.10+ (recommended) or native installation
• Docker Compose: 2.0+ (for Docker setup)
• Node.js: 18+ (for manual development only)
• Go: 1.21+ (for manual development only)
• PostgreSQL: 14+ (managed by Docker or native)

🏗️ Architecture

High-Level Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Database      │
│   (React)       │◄──►│   (Go/Gin)      │◄──►│  (PostgreSQL)   │
│   Port: 3000    │    │   Port: 8080    │    │   Port: 5432    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       
         ▼                       ▼                       
┌─────────────────┐    ┌─────────────────┐
│   Nginx Proxy   │    │   File Storage  │
│   Static Assets │    │   /uploads/     │
└─────────────────┘    └─────────────────┘

Technology Stack

Backend

• Framework: Go with Gin
• ORM: GORM
• Database: PostgreSQL (supports SQLite/MySQL)
• Authentication: JWT with CSRF protection
• File Storage: Local filesystem (/uploads)
• Email: SMTP with templates
• Background Jobs: Newsletter automation, data prefetching

Frontend

• Framework: React 18
• UI Library: Chakra UI
• State Management: React Query
• Routing: React Router
• Build Tool: CRACO (Create React App Configuration Override)
• Rich Text: Quill.js
• Visual Editor: Custom MyUIbrix page builder

Infrastructure

• Containerization: Docker & Docker Compose
• Reverse Proxy: Nginx
• Monitoring: Prometheus metrics
• Logging: Structured logging with request IDs

📁 Project Structure

fotbal-club/
├── backend/                    # Go backend application
│   ├── main.go                # Application entry point
│   ├── internal/              # Internal application code
│   │   ├── controllers/       # HTTP handlers
│   │   ├── models/           # Database models
│   │   ├── services/         # Business logic
│   │   ├── middleware/       # HTTP middleware
│   │   └── routes/           # Route definitions
│   ├── pkg/                  # Reusable packages
│   │   ├── database/         # Database utilities
│   │   ├── email/           # Email service
│   │   └── httpclient/      # HTTP clients
│   ├── database/            # Database migrations
│   └── cache/               # Cached data files
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   ├── pages/           # Page components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── services/        # API services
│   │   ├── layouts/         # Layout components
│   │   └── styles/          # CSS/styling
│   ├── public/              # Static assets
│   └── package.json         # Dependencies
├── uploads/                  # User uploaded files
├── dist/                     # Built frontend assets
├── docker-compose.yml        # Docker configuration
├── Dockerfile               # Backend Docker image
├── Makefile                 # Development commands
└── README.md               # This file

🎯 Core Features

1. Visual Page Builder (MyUIbrix)

• Drag & Drop: Elementor-style page building
• Live Preview: Real-time editing with instant feedback
• Responsive Design: Mobile/tablet/desktop preview modes
• Custom CSS: Advanced styling capabilities
• Component Library: 17+ pre-built page sections
• Template System: Save and reuse page layouts

2. Content Management

• Articles/Blog: Rich text editing with media support
• Gallery: Zonerama integration with automatic sync
• Videos: YouTube channel import and manual management
• Files: Document upload and organization
• Rich Text Editor: Quill.js with image upload

3. Sports Management

• Teams & Players: Roster management with profiles
• Matches: FACR integration with live results
• Standings: League tables and statistics
• Calendar: Event scheduling and management
• Scoreboard: Live match display system

4. Communication

• Newsletter: Automated weekly digests and notifications
• Contact Forms: Multi-channel contact management
• Comments: User engagement with reactions
• Polls & Surveys: Interactive content collection

5. Marketing & Engagement

• Sponsors: Banner management and display
• Merchandise: E-commerce for club products
• Rewards System: Gamification with points and achievements
• Shortlinks: URL tracking and analytics

6. Analytics & Monitoring

• Umami Integration: Privacy-focused analytics
• Performance Metrics: Prometheus endpoints
• Error Tracking: Centralized error reporting
• User Activity: Engagement tracking

🔧 Installation & Setup

Option 1: Docker (Recommended)

# 1. Clone repository
git clone <repository-url>
cd fotbal-club

# 2. Create environment file
cp .env.example .env
# Edit .env with your configuration

# 3. Start services
make docker-up

# 4. Initialize database (first time only)
docker-compose exec backend go run main.go -seed=true

Option 2: Manual Development Setup

# 1. Install dependencies
sudo apt update
sudo apt install postgresql nodejs npm golang-go

# 2. Setup database
sudo -u postgres createdb myclub
sudo -u postgres createuser myclub
sudo -u postgres psql -c "ALTER USER myclub PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE myclub TO myclub;"

# 3. Start backend
cd backend
export DATABASE_URL="postgres://myclub:password@localhost/myclub?sslmode=disable"
go run main.go

# 4. Start frontend
cd frontend
npm install
npm start

Environment Configuration

Create .env file in project root:

# Database
DATABASE_URL=postgres://myclub:password@localhost:5432/myclub?sslmode=disable

# Security
JWT_SECRET=your-super-secret-jwt-key-here
CSRF_SECRET=your-csrf-secret-key-here

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# External APIs
FACR_API_KEY=your-facr-api-key
GOOGLE_MAPS_API_KEY=your-google-maps-key
YOUTUBE_API_KEY=your-youtube-api-key
UMAMI_WEBSITE_ID=your-umami-id
OPENAI_API_KEY=your-openai-key

# Club Settings
CLUB_NAME=FC Example
CLUB_DOMAIN=example.club

🚀 Deployment

Production Deployment

# 1. Build production images
docker-compose -f docker-compose.prod.yml build

# 2. Run database migrations
docker-compose exec backend go run main.go -migrate=true

# 3. Seed initial data
docker-compose exec backend go run main.go -seed=true

# 4. Start production services
docker-compose -f docker-compose.prod.yml up -d

Nginx Configuration

server {
    listen 80;
    server_name your-domain.com;
    
    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # Backend API
    location /api/ {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # Static files
    location /uploads/ {
        alias /path/to/uploads/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

📊 Performance & Scaling

Database Optimization

• Indexes: 25+ performance indexes on frequently queried columns
• Connection Pooling: GORM with optimized pool settings
• Query Timeouts: 15-second limit on database operations
• Caching: Optional Redis integration for frequently accessed data

Frontend Optimization

• Code Splitting: Lazy loading of admin pages
• Image Optimization: Automatic resizing and WebP conversion
• Bundle Size: <2MB total, <500KB initial load
• CDN Ready: Static asset optimization

Backend Performance

• HTTP Timeouts: Configurable timeouts (30s default, 5s fast)
• Circuit Breakers: Prevent cascading failures
• Rate Limiting: Configurable per-endpoint limits
• Memory Usage: <512MB for typical load (256MB minimum)

Actual Resource Usage (Docker Configuration)

Based on docker-compose.yml resource limits:

• Backend: 0.5-2.0 CPU cores, 256MB-1GB RAM
• Frontend: 0.25-2.0 CPU cores, 128MB-2GB RAM (build-time)
• PostgreSQL: 0.5-2.0 CPU cores, 512MB-2GB RAM
• Total Typical Usage: ~1.5 CPU cores, ~1GB RAM

Scaling Guidelines

• Small Club (100-500 users): Single instance, 2GB RAM sufficient
• Medium Club (500-2000 users): 4GB RAM recommended, consider read replica
• Large Club (2000+ users): 8GB+ RAM, load balancer + read replicas + Redis

🔐 Security Features

Authentication & Authorization

• JWT Tokens: Secure token-based authentication
• CSRF Protection: Double-submit cookie pattern
• Role-Based Access: Admin, Editor, User roles
• Session Management: Secure session handling

Data Protection

• XSS Prevention: Content Security Policy and sanitization
• SQL Injection: Parameterized queries via GORM
• File Upload Security: Type validation and sandboxing
• Rate Limiting: Prevent brute force attacks

Privacy Compliance

• GDPR Ready: Cookie consent and data management
• Data Minimization: Only collect necessary data
• Right to Deletion: User data export/removal
• Analytics: Privacy-focused (Umami) alternative to Google Analytics

🛠️ Development Guide

Adding New Features

1. Backend Models: Add to internal/models/
2. Database Migration: Create in database/migrations/
3. API Endpoints: Add controllers in internal/controllers/
4. Frontend Components: Add to frontend/src/components/
5. Pages: Add to frontend/src/pages/
6. Routes: Update internal/routes/ and frontend routing

Code Standards

• Go: Follow standard Go formatting and conventions
• React: Use TypeScript, functional components, hooks
• CSS: Use Chakra UI theme system, avoid inline styles
• Database: Use GORM conventions, add indexes for performance

Testing

# Backend tests
cd backend && go test ./...

# Frontend tests
cd frontend && npm test

# Integration tests
make test-integration

Debugging

• Backend Logs: docker-compose logs backend
• Frontend DevTools: React DevTools, Redux DevTools
• Database: docker-compose exec postgres psql -U myclub myclub
• API Testing: Use Swagger UI at /api/v1/docs

📚 API Documentation

Authentication

POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh

Content Management

GET    /api/v1/articles
POST   /api/v1/admin/articles
PUT    /api/v1/admin/articles/:id
DELETE /api/v1/admin/articles/:id

Sports Data

GET /api/v1/matches
GET /api/v1/teams
GET /api/v1/players
GET /api/v1/standings

Full API Reference

Visit: http://localhost:8080/api/v1/docs (when running)

🆘 Troubleshooting

Common Issues

Database Connection Failed

# Check PostgreSQL status
docker-compose ps postgres
docker-compose logs postgres

# Reset database
docker-compose down -v
docker-compose up postgres

Frontend Build Errors

# Clear cache and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install
npm start

Backend Migration Issues

# Check migration status
docker-compose exec backend go run main.go -migrate-status

# Force re-run migrations
docker-compose exec backend go run main.go -migrate-force

Performance Issues

• Check database query logs for slow queries
• Monitor memory usage with docker stats
• Use browser dev tools for frontend profiling
• Check Nginx access logs for traffic patterns

Getting Help

• Check documentation in /docs directory
• Review error logs in Docker containers
• Use admin support button in the interface
• Check GitHub issues for known problems

📈 Monitoring & Maintenance

Health Checks

# Backend health
curl http://localhost:8080/api/v1/health

# Frontend health
curl http://localhost:3000

# Database health
docker-compose exec postgres pg_isready

Backup Procedures

# Database backup
docker-compose exec postgres pg_dump -U myclub myclub > backup.sql

# File backup
tar -czf uploads-backup.tar.gz uploads/

# Automated backup script
./scripts/backup.sh

Log Management

• Application Logs: Structured JSON logging
• Access Logs: Nginx access logs
• Error Logs: Centralized error tracking
• Performance Metrics: Prometheus endpoints

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Development Workflow

• Use feature branches for all changes
• Write tests for new functionality
• Update documentation for API changes
• Follow code style guidelines
• Ensure all tests pass before PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Chakra UI for excellent React component library
• GORM for powerful Go ORM
• FACR for Czech football data API
• Zonerama for gallery integration
• Umami for privacy-focused analytics

📞 Support

For support and questions:

• Documentation: /admin/docs (when running)
• Issues: GitHub Issues
• Email: support@your-domain.com
• Community: [Discord/Slack channel]

---

MyClub - Empowering football clubs with modern technology. modified content modified