MyClub/DOCS/overview.md

MyClub - Project Overview

Project Description

MyClub is a comprehensive football club CMS and website platform. It combines a Go (Gin) REST API backend with a modern React frontend to power club operations end‑to‑end: content/news, matches/standings (FAČR integration), teams/players, gallery and videos, banners/sponsors, newsletters, polls, comments, a live scoreboard overlay, and a powerful visual editor (MyUIbrix) for building the homepage.

Technical Stack

Backend

• Go (Golang) with Gin Web Framework
• PostgreSQL via GORM ORM; migrations in database/
• JWT authentication with role‑based access (Admin, Editor, User)
• REST API, static uploads at /uploads, email templates
• Background jobs: prefetcher (FAČR/YouTube/Zonerama), newsletter automation
• Prometheus metrics, rate limiting, CORS, gzip, request IDs

Frontend

• React 18 (TypeScript) with Chakra UI, React Router, React Query
• ClubThemeContext dynamic theming; dark mode and typography system
• Built with CRA + CRACO; service worker/PWA setup
• Modern UI components, responsive layouts, accessibility focus

DevOps & Infrastructure

• Docker Compose for local dev (backend 8080, frontend 3000, Postgres 5432)
• Nginx serving frontend build in production; static /uploads from backend
• Prometheus metrics; production‑safe logging; health checks
• CI/CD ready (GitHub Actions examples); Makefile helpers

Core Features

• Website & CMS

  • Articles/blog with rich text editor (images, attachments), categories, tags, search
  • Comments with reactions and moderation; attachments open in new tab
  • Static/legal pages (Privacy, Terms, Cookie policy with preferences)

• Sports

  • Teams and players (profiles, positions, numbers, nationality translations)
  • Matches: FAČR integration (schedule/results), upcoming/history, search with past scores
  • Tables/standings and competition aliases; team name/logo overrides
  • Scoreboard overlay and Remote controller; admin Scoreboard page

• Media

  • Gallery via Zonerama integration with caching and album covers
  • Videos: auto import from YouTube channel + manual items, de‑dup + date‑sorted
  • Local uploads management; simplified file previews

• Engagement

  • Polls with multiple styles (stars, scale, choices, chips/cards), live results, embedded on pages
  • Rewards (Odměny & Úspěchy): simplified admin, mandatory avatar upload unlock, unlimited stock support

• Communication

  • Newsletter automation: weekly digest, match reminders, results, blog notifications
  • Recipient preferences, previews in admin, logs and scheduling
  • Contacts and messages with forms and saved locations for events

• Marketing

  • Sponsors with categories and placements
  • Banners/ads management with presets and display rules

• Navigation & Theming

  • Public navbar hides empty sections (articles, players, activities, videos, gallery)
  • Admin navigation with editable categories; per‑page permissions (Editors on articles/activities/shortlinks)
  • Club theming via Chakra + ClubThemeContext; dark mode and typography controls

• MyUIbrix Visual Editor

  • Drag‑and‑drop homepage builder, inline text editing, style/CSS editor, column layouts
  • Variants (e.g., hero/news/videos), bulletproof style system, viewport simulator
  • State controller, auto‑save, backend preview/validation endpoints, error boundary, safe DOM helpers

• Analytics

  • Umami integration, admin dashboards, admin exclusion and debugging tools

• Maps & Location

  • Google Maps integration, vector maps, map link importer, reusable saved locations

• Security & Performance

  • JWT auth, CSRF, XSS protection, input validation, rate limiting, security headers
  • HTTP timeouts, circuit breakers, DB timeouts, performance indexes, Prometheus metrics

• Admin & Tools

  • 30+ admin pages, global support button with context, docs viewer at /admin/docs
  • Shortlinks system; cache/prefetch tools

Project Structure

fotbal-club/
├── cmd/                      # Entry points / tools
├── internal/                 # Backend (controllers, middleware, models, routes, services)
├── pkg/                      # Reusable backend packages (email, httpclient, etc.)
├── database/                 # SQL migrations and seeds
├── frontend/                 # React app (Chakra UI, React Query, Router)
├── DOCS/                     # Documentation (guides, audits, quick starts)
├── diagrams/                 # Mermaid diagrams (see section below)
├── static/                   # Public static assets
├── templates/                # Email/templates if used
├── uploads/                  # User‑uploaded files (served at /uploads)
├── docker-compose.yml        # Local dev stack
└── go.mod                    # Go module definition

Key Technical Components

Backend Architecture

• RESTful API with modular controllers and services
• Middleware: auth (JWT/optional), rate limiting, CORS, gzip, recovery with request IDs
• Background jobs: FAČR/YouTube/Zonerama prefetch, newsletter automation
• Static file server for /uploads; Prometheus metrics at /metrics

Frontend Architecture

• Component‑based UI with Chakra UI
• Data layer via React Query; React Router for routing
• ClubThemeContext for dynamic colors; responsive design
• PWA‑ready; accessibility best practices

Security Features

• CSRF protection
• XSS prevention
• Rate limiting
• Secure password hashing (bcrypt)
• Input validation and sanitization

Development Setup

Quick start (Docker Compose)

1. Copy .env.example to .env and adjust settings
2. Start the stack: make docker-up
3. Health check: http://localhost:8080/api/v1/health
4. Frontend: http://localhost:3000 (proxies API to backend)
5. Optional seed: set SEED_DATABASE=true in .env and restart

Manual dev (advanced)

• Backend: go mod download && go run main.go
• Frontend: cd frontend && npm install && npm start

Deployment

• Docker images for backend and frontend (Nginx) with environment configuration
• Static uploads served by backend; configure reverse proxy and SSL as needed

API Documentation

• See DOCS/DOCS_API_ROUTES.md for route references
• Admin in‑app docs viewer: /admin/docs
• Health: GET /api/v1/health, Metrics: /metrics

Diagrams

Key Mermaid diagrams live under diagrams/ (open diagrams/index.html to browse rendered versions):

• System: diagrams/system-overall.mmd, diagrams/system-overall-clean.mmd
• Backend: diagrams/backend-routes-overview.mmd, diagrams/backend-middleware-pipeline.mmd, diagrams/backend-packages.mmd, diagrams/backend-jobs.mmd
• Frontend: diagrams/frontend-architecture.mmd, diagrams/frontend-routes.mmd, diagrams/frontend-homepage.mmd, diagrams/frontend-overall.mmd, diagrams/frontend-everything.mmd
• Data: diagrams/db-models.mmd, diagrams/db-er.mmd
• Flows: diagrams/auth-flow.mmd, diagrams/comments-flow.mmd, diagrams/newsletter-flow.mmd, diagrams/shortlinks-flow.mmd, diagrams/upload-flow.mmd, diagrams/gallery-zonerama-flow.mmd, diagrams/scoreboard-flow.mmd
• Admin: diagrams/admin-overall.mmd

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

[Specify License]