ClubLogos/backend

🇨🇿 Czech Clubs Logos API - Backend

A Go backend API for serving high-quality, transparent background logos of Czech football & futsal clubs. Logos are mapped by FAČR UUIDs to ensure consistency across projects.

🔧 Tech Stack

• Go 1.21+ - Fast and efficient backend
• Gin - Web framework
• SQLite - Lightweight database
• FAČR API - External club data source

✨ 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 local or cloud storage

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• GCC (for SQLite compilation)

Installation

1. Navigate to the backend directory:

cd backend

2. Install dependencies:

go mod download

3. Run the server:

go run .

The API will start on http://localhost:8080

🐳 Docker

Build and run with Docker:

docker build -t czech-clubs-backend .
docker run -p 8080:8080 -v $(pwd)/logos:/root/logos czech-clubs-backend

Or use Docker Compose (recommended):

From the root directory:

docker-compose up

📂 Project Structure

backend/
├── main.go              # Application entrypoint
├── handlers.go          # API route handlers
├── facr_client.go       # FAČR API client
├── go.mod               # Go dependencies
├── go.sum               # Dependency checksums
├── Dockerfile           # Docker configuration
└── README.md            # This file

🚀 API Endpoints

Health Check

GET /health

Returns server health status.

Search Clubs

GET /clubs/search?q=sparta

Search for clubs by name. Proxies to FAČR API with fallback to demo data.

Response:

[
  {
    "id": "22222222-3333-4444-5555-666666666666",
    "name": "AC Sparta Praha",
    "city": "Praha",
    "type": "football"
  }
]

Get Club Info

GET /clubs/:id

Get detailed club information by UUID.

Upload Logo

POST /logos/:id

Upload a logo for a specific club UUID.

Parameters:

• file (multipart/form-data) - SVG or PNG file

Example with curl:

curl -X POST http://localhost:8080/logos/22222222-3333-4444-5555-666666666666 \
  -F "file=@sparta.svg"

Response:

{
  "success": true,
  "id": "22222222-3333-4444-5555-666666666666",
  "filename": "22222222-3333-4444-5555-666666666666.svg",
  "size": 12345,
  "message": "logo uploaded successfully"
}

Get Logo

GET /logos/:id

Retrieve a logo by UUID. Returns the image file.

Response Headers:

• Content-Type: image/svg+xml or image/png
• Cache-Control: public, max-age=31536000

Get Logo with Metadata

GET /logos/:id/json

Get logo metadata in JSON format.

Response:

{
  "id": "22222222-3333-4444-5555-666666666666",
  "club_name": "AC Sparta Praha",
  "club_city": "Praha",
  "club_type": "football",
  "logo_url": "http://localhost:8080/logos/22222222-3333-4444-5555-666666666666",
  "file_size": 12345,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

📊 Database Schema

logos table

Column	Type	Description
id	TEXT	UUID (Primary Key)
club_name	TEXT	Club name
club_city	TEXT	City
club_type	TEXT	Type (football/futsal)
file_extension	TEXT	.svg or .png
file_size	INTEGER	File size in bytes
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

🔌 External APIs

FAČR Scraper API

• Base URL: https://facr.tdvorak.dev
• Endpoints Used:
  • /club/search?q={query} - Search clubs
  • /club/{id} - Get club details

🔒 Security Features

• UUID format validation
• File type validation (SVG/PNG only)
• CORS enabled for frontend integration
• Input sanitization

🌟 Environment Variables

Variable	Default	Description
PORT	8080	Server port

📝 Example Workflow

1. Search for a club:

curl "http://localhost:8080/clubs/search?q=Slavia"

2. Upload logo for club:

curl -X POST http://localhost:8080/logos/11111111-2222-3333-4444-555555555555 \
  -F "file=@slavia.svg"

3. Get logo:

curl http://localhost:8080/logos/11111111-2222-3333-4444-555555555555 \
  -o slavia.svg

4. Get logo with metadata:

curl http://localhost:8080/logos/11111111-2222-3333-4444-555555555555/json

🔮 Future Enhancements

• ✍️ Admin authentication
• 🎨 Auto background remover integration
• 🔎 Advanced logo search capabilities
• 📦 Cloud storage support (S3, R2, Supabase)
• 🗄️ PostgreSQL support

🤝 Contributing

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

📄 License

This project is part of the Czech Clubs Logos API system.

---

Built with ❤️ for Czech Football