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]