ClubLogos/README.md

🇨🇿 Czech Clubs Logos API

A fullstack project for serving high-quality, transparent background logos of Czech football & futsal clubs. Logos are mapped by FAČR UUIDs (from facr.tdvorak.dev) to ensure consistency across projects.

Quick Start • Documentation • API Examples • Deployment

✨ Features

• ⚽ Fetch Czech clubs metadata from FAČR Scraper API
• 🖼️ Upload & store full-quality transparent logos (SVG/PNG)
• 🔄 Reuse FAČR UUID as a unique identifier
• 🌐 Serve logos through a simple CDN-style API
• 📝 Optional metadata (club name, city, colors, competition)
• 📦 Self-hosted with Go backend + CDN storage
• 🌙 Beautiful dark mode frontend
• 🎭 Smooth GSAP animations
• 🐳 Docker support for easy deployment

🔧 Tech Stack

Backend

• Go 1.21+ with Gin framework
• SQLite for metadata storage
• FAČR API integration

Frontend

• Vite - Lightning-fast build tool
• Tailwind CSS - Modern styling
• GSAP - Professional animations
• Vanilla JavaScript - Fast and lightweight

DevOps

• Docker & Docker Compose
• Nginx for frontend serving

🚀 Quick Start

Option 1: Docker Compose (Recommended)

The easiest way to run the entire stack:

# Clone the repository
git clone <repository-url>
cd ClubLogos

# Start both frontend and backend
docker-compose up

Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080

Option 2: Local Development

Backend

cd backend
go mod download
go run .

Backend will run on http://localhost:8080

Frontend

cd frontend
npm install
npm run dev

Frontend will run on http://localhost:3000

📂 Project Structure

czech-clubs-logos-api/
│
├── backend/                   # Go backend
│   ├── main.go                # API entrypoint
│   ├── handlers.go            # Route handlers
│   ├── facr_client.go         # FAČR API client
│   ├── go.mod                 # Go dependencies
│   ├── Dockerfile             # Backend Docker config
│   └── README.md              # Backend documentation
│
├── frontend/                  # Vite + Tailwind frontend
│   ├── src/
│   │   ├── main.js            # JavaScript logic & GSAP
│   │   └── style.css          # Tailwind styles
│   ├── index.html             # Main HTML
│   ├── vite.config.js         # Vite configuration
│   ├── tailwind.config.js     # Tailwind configuration
│   ├── nginx.conf             # Nginx config for Docker
│   ├── Dockerfile             # Frontend Docker config
│   └── README.md              # Frontend documentation
│
├── data/                      # Persistent data (created by Docker)
│   ├── logos/                 # Uploaded logos
│   └── db/                    # SQLite database
│
├── docker-compose.yml         # Full stack orchestration
├── vision.md                  # Project vision document
└── README.md                  # This file

🚀 API Endpoints

Club Search

GET /clubs/search?q=sparta

Search for clubs by name.

Get Club Info

GET /clubs/:id

Get detailed club information.

Upload Logo

POST /logos/:id
FormData: file=@logo.svg

Upload a club logo.

Get Logo

GET /logos/:id

Retrieve a logo file.

Get Logo Metadata

GET /logos/:id/json

Get logo with metadata in JSON format.

📊 Example Workflow

1. Search for a club:

   • Open the frontend at http://localhost:3000
   • Click "🔍 Search Clubs"
   • Type "Sparta" or "Slavia"
   • Copy the UUID

2. Upload a logo:

   • Click "⬆️ Upload Logo"
   • Paste the UUID
   • Drag & drop or browse for a logo file (SVG/PNG)
   • Click "Upload Logo"

3. Access the logo:

   • Navigate to http://localhost:8080/logos/{UUID}
   • Or use the API endpoint in your projects

🐳 Docker Configuration

Build Images

# Build backend
cd backend
docker build -t czech-clubs-backend .

# Build frontend
cd frontend
docker build -t czech-clubs-frontend .

Run with Docker Compose

docker-compose up -d

Stop Services

docker-compose down

View Logs

docker-compose logs -f

🔧 Configuration

Backend Configuration

Edit environment variables in docker-compose.yml:

environment:
  - PORT=8080

Frontend Configuration

Update the API endpoint in frontend/src/main.js:

const API_BASE_URL = 'http://localhost:8080'

📦 Data Persistence

When using Docker Compose, data is persisted in the ./data directory:

• ./data/logos/ - Uploaded logo files
• ./data/db/ - SQLite database

🌟 Features in Detail

Frontend Features

• 🌙 Dark mode optimized UI
• 🎭 GSAP scroll-triggered animations
• 🔍 Real-time search with debouncing
• ⬆️ Drag & drop file upload
• 📋 One-click UUID copying
• 📱 Fully responsive design
• ⚡ Lightning-fast Vite build

Backend Features

• 🚀 High-performance Go API
• 💾 SQLite for lightweight storage
• 🔌 FAČR API integration
• 🔒 UUID validation
• 📁 File type validation
• 🌐 CORS enabled
• 💨 Efficient caching headers

🔮 Future Ideas

• ✍️ Web admin panel with authentication
• 🎨 Auto background remover (e.g., remove.bg API)
• 🔎 Logo search by club name
• 📦 NPM package (@czech-football/logos)
• 🗄️ PostgreSQL support
• ☁️ Cloud storage (S3, R2, Supabase)
• 🔐 API key authentication

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📚 Documentation

Document	Description
QUICKSTART.md	Get started in 5 minutes
API_EXAMPLES.md	Code examples in multiple languages
DEPLOYMENT.md	Production deployment guide
CONTRIBUTING.md	How to contribute
CHANGELOG.md	Version history
PROJECT_SUMMARY.md	Complete project overview

📄 License

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

🙏 Credits

• FAČR Scraper API - Club data source: facr.tdvorak.dev
• Built with ❤️ for Czech Football

🌟 Show Your Support

If this project helps you, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 🤝 Contributing code

---

👉 This way, you'll have a FAČR-aware logo CDN that anyone can integrate into websites, apps, or your SportCreative projects.

Made with ❤️ • Report Bug • Request Feature