# 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

```bash
# 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)

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

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

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

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

```nginx
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
```bash
# 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
```http
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
```

### Content Management
```http
GET    /api/v1/articles
POST   /api/v1/admin/articles
PUT    /api/v1/admin/articles/:id
DELETE /api/v1/admin/articles/:id
```

### Sports Data
```http
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**
```bash
# Check PostgreSQL status
docker-compose ps postgres
docker-compose logs postgres

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

**Frontend Build Errors**
```bash
# Clear cache and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install
npm start
```

**Backend Migration Issues**
```bash
# 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
```bash
# 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
```bash
# 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