MyClub/DOCS/CONTACT_MANAGEMENT_IMPLEMENTATION.md

Contact Management & Map Integration - Implementation Summary

Overview

Complete contact management system with admin interface, map integration on homepage, and setup wizard location configuration.

What Was Implemented

1. Backend API Service (Already Existed ✅)

• File: internal/controllers/contact_info_controller.go
• File: internal/routes/contact_info_routes.go
• Models: ContactCategory and Contact in internal/models/models.go
• Migration: database/migrations/000006_create_contact_tables.up.sql

Endpoints:

• Public:

  • GET /api/v1/contacts - Get all active contacts grouped by category
  • GET /api/v1/contacts/categories - Get all active categories

• Admin (require authentication + admin role):

  • GET /admin/contacts/categories - List all categories
  • POST /admin/contacts/categories - Create category
  • PUT /admin/contacts/categories/:id - Update category
  • DELETE /admin/contacts/categories/:id - Delete category
  • GET /admin/contacts - List all contacts
  • POST /admin/contacts - Create contact
  • PUT /admin/contacts/:id - Update contact
  • DELETE /admin/contacts/:id - Delete contact

2. Frontend Service Layer (NEW ✅)

• File: frontend/src/services/contactInfo.ts
• TypeScript interfaces for Contact, ContactCategory, and GroupedContacts
• Functions to interact with all contact API endpoints

3. Admin Contact Management Page (NEW ✅)

• File: frontend/src/pages/admin/ContactsAdminPage.tsx
• Full CRUD interface for contacts and categories
• Tab-based UI with separate views for contacts and categories
• Modal dialogs for create/edit operations
• Image upload support for contact photos
• Display order management
• Active/inactive status toggle
• Category assignment for contacts
• Delete confirmation dialogs with validation

4. Map Component (NEW ✅)

• File: frontend/src/components/home/ContactMap.tsx
• Uses Leaflet.js (open source mapping library)
• Dynamically loads Leaflet CSS and JavaScript
• Supports multiple map styles:
  • default: OpenStreetMap
  • dark: CartoDB Dark Matter
  • satellite: Esri World Imagery
  • custom: Custom tile URL
• Features:
  • Custom markers with popups
  • Scroll wheel zoom (enabled on click)
  • Responsive design
  • Error handling

5. Homepage Contacts Section (NEW ✅)

• File: frontend/src/components/home/ContactsSection.tsx
• Displays contact information with optional map
• Groups contacts by category using accordion UI
• Shows address, phone, and email with icons
• Responsive grid layout for contact cards
• Only renders if data exists
• Integrates map based on settings configuration

6. Setup Wizard Enhancement (NEW ✅)

• File: frontend/src/pages/SetupPage.tsx
• Added location configuration section:
  • Address fields (street, city, ZIP, country)
  • GPS coordinates (latitude, longitude)
  • Helpful placeholder text with examples
• Backend support in internal/controllers/base_controller.go:
  • Added location fields to SetupInitialize handler
  • Saves location data to settings during initial setup

7. Routing & Navigation (NEW ✅)

• Route: Added /admin/kontakty route in frontend/src/App.tsx
• Navigation: Added "Kontakty" menu item in admin sidebar
• Icon: Uses FaAddressBook icon from react-icons
• Positioned in sidebar under "Zprávy" (Messages) section

8. Settings Model Extension (Already Existed ✅)

Settings table includes location/map fields:

• contact_address, contact_city, contact_zip, contact_country
• contact_phone, contact_email
• location_latitude, location_longitude (DECIMAL)
• map_zoom_level (INT, default: 15)
• map_style (VARCHAR)
• show_map_on_homepage (BOOLEAN)

Database Schema

contact_categories

CREATE TABLE contact_categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE,
    description TEXT,
    display_order INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);

contacts

CREATE TABLE contacts (
    id SERIAL PRIMARY KEY,
    category_id INT REFERENCES contact_categories(id) ON DELETE SET NULL,
    name VARCHAR(255) NOT NULL,
    position VARCHAR(255),
    email VARCHAR(255),
    phone VARCHAR(100),
    image_url VARCHAR(500),
    description TEXT,
    display_order INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);

Usage Guide

Initial Setup

1. During setup wizard, fill in the "Lokalita a kontakt" section:
   • Enter club address (optional)
   • Enter GPS coordinates for map (optional)
   • All fields can be edited later in admin

Admin Management

1. Navigate to Admin Panel → Kontakty

2. Categories Tab:

   • Create categories (e.g., "Management", "Coaches", "Office")
   • Set display order and active status
   • Edit or delete categories

3. Contacts Tab:

   • Add contact persons
   • Upload photos
   • Assign to categories
   • Set position, email, phone
   • Add optional description
   • Manage display order

Homepage Display

The contacts section appears automatically on the homepage when:

• Contact information exists (address, phone, email), OR
• Contacts have been added, OR
• Map location is configured and show_map_on_homepage is enabled

Map Configuration

In admin settings (/admin/nastaveni), you can configure:

• Location: Latitude, Longitude, Zoom Level
• Map Style: default, dark, satellite, or custom tile URL
• Display: Toggle show_map_on_homepage
• Contact Info: Address, city, ZIP, country, phone, email

Features

Contact Management

• ✅ Category-based organization
• ✅ Photo uploads for each contact
• ✅ Position/role labels
• ✅ Email and phone with clickable links
• ✅ Optional descriptions
• ✅ Display order customization
• ✅ Active/inactive status

Map Integration

• ✅ Open source (Leaflet.js + OpenStreetMap)
• ✅ No API keys required for basic functionality
• ✅ Multiple map style options
• ✅ Custom markers with popups
• ✅ Responsive and mobile-friendly
• ✅ Configurable zoom level

Admin UX

• ✅ Intuitive tab-based interface
• ✅ Modal dialogs for forms
• ✅ Inline image preview
• ✅ Delete confirmations
• ✅ Validation and error handling
• ✅ Loading states

Files Created/Modified

Created Files

1. frontend/src/services/contactInfo.ts - API service
2. frontend/src/pages/admin/ContactsAdminPage.tsx - Admin UI
3. frontend/src/components/home/ContactMap.tsx - Map component
4. frontend/src/components/home/ContactsSection.tsx - Homepage section
5. CONTACT_MANAGEMENT_IMPLEMENTATION.md - This document

Modified Files

1. frontend/src/App.tsx - Added route and import
2. frontend/src/pages/HomePage.tsx - Added ContactsSection
3. frontend/src/pages/SetupPage.tsx - Added location fields
4. frontend/src/services/setup.ts - Added location types
5. frontend/src/services/api.ts - Added uploadImage function
6. frontend/src/components/admin/AdminSidebar.tsx - Added navigation
7. internal/controllers/base_controller.go - Added location handling

Testing Checklist

• Run migrations to create contact tables
• Access /admin/kontakty - verify page loads
• Create contact categories
• Add contacts with photos
• Verify contacts appear on homepage
• Configure map location in setup or settings
• Verify map displays correctly
• Test different map styles
• Test on mobile devices
• Verify email/phone links work
• Test category assignment and filtering

Next Steps (Optional Enhancements)

From the original CONTACT_MANAGEMENT.md:

• Contact form directly on contact page
• vCard download for contacts
• Office hours/availability scheduling
• Multiple locations/maps support
• Department-specific contact forms
• Social media links per contact
• Search/filter functionality
• Map clustering for multiple locations

Security Notes

• Admin endpoints protected by JWT + admin role middleware
• Public endpoints only expose active contacts
• Image uploads validated for file type
• SQL injection protected via ORM (GORM)
• XSS protection via React's automatic escaping

Dependencies

Frontend:

• Leaflet.js 1.9.4 (loaded dynamically, no npm install needed)
• @chakra-ui/react (already in project)
• react-icons/fa (already in project)

Backend:

• No new dependencies (uses existing GORM, Gin)

Support

Map uses OpenStreetMap tiles (free, no API key required). For production:

• Consider using a CDN for Leaflet assets
• Monitor tile server usage (OSM has usage policies)
• Can switch to alternative tile providers if needed
• Custom tile servers can be configured via map_style setting

---

Implementation Date: 2025-10-05 Status: ✅ Complete and Ready for Testing