mirror of
https://github.com/Dvorinka/MyClubServer.git
synced 2026-06-03 18:22:57 +00:00
Tomas Dvorak
518 lines
15 KiB
Markdown
518 lines
15 KiB
Markdown
# 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
|