# Loqzone - LLMs.txt
# Complete Route Documentation for LLM Context

## Project Overview
Loqzone is a sports collectibles platform connecting fans with their favorite clubs/athletes.
- Frontend: Next.js application
- Features: Digital colletibles marketplace, club/athletes profiles, passports, achievements

---

## FRONTEND ROUTES (Next.js)

### Home
- `/` - Home page

### Legal Pages
- `/legals/cookies-policy` - Cookies policy
- `/legals/privacy-policy` - Privacy policy
- `/legals/terms-of-services` - Terms of service

---

## Club/Team Routes (CLAIMED & UNCLAIMED)

### Primary Club Route
- `/club/[clubSlug]` - Club profile page
  - Format: `{sanitized_name}-{sanitized_city}` (e.g., `/club/river-plate-buenos-aires`)
  - Supports both CLAIMED and UNCLAIMED clubs
  - CLAIMED clubs: Use username internally, have full marketplace features
  - UNCLAIMED clubs: Use club name internally, limited features, can be claimed
  - Includes JSON-LD structured data (`@type: SportsTeam`) for SEO
  - Dynamic OG/Twitter meta tags and canonical URLs for search engines

### How Club Slugs Are Built
- The slug is generated from `{name}-{city}`, both sanitized:
  1. Lowercased
  2. Unicode diacritics removed (NFD normalization, e.g., `é` → `e`, `ü` → `u`)
  3. Special characters stripped (only word chars, spaces, hyphens kept)
  4. Spaces replaced with hyphens
  5. Consecutive hyphens collapsed
- Frontend (`sanitizeForUrl` in `src/utils/clubSlugUtils.js`) and backend (`normalizeForComparison` in `userService.js`) use the same algorithm
- Slugs are **not stored in the database** — they are generated at runtime by comparing the input slug against all clubs

### How Club URL Resolution Works (Backend)
1. **API endpoint**: `GET /client/club-by-name/:slugName`
2. **Phase 1 — Claimed clubs**: Loads all `User` docs with `role: CLUB`, generates a slug from each club's `name` + `city`, compares against the input slug
3. **Phase 2 — Unclaimed clubs**: If no claimed match, loads all `Club` docs with `claimed: false`, generates slug from `name` + `address.city`, compares
4. **Response includes**: club data, `type` (`claimed` | `unclaimed`), SEO metadata, and JSON-LD structured data

### How Club URLs Work
1. **Claimed Club**: `/club/river-plate-buenos-aires` → Claimed clubs are ones that real-life clubs have ownership over
2. **Unclaimed Club**: `/club/atletico-tucuman-tucuman` → Unclaimed clubs are ones that haven't been picked up by their real-life counterpart
3. **Legacy URL Redirect**: Old 4-segment format `/{sport}/{country}/{city}/{name}` permanently redirects to the new `/club/{name}-{city}` format via `GET /client/club-by-slug/:sport/:country/:city/:name`

### SEO Data Returned per Club
- **Title**: `{name} - {sport} Club in {city}, {country}`
- **Description**: Club info or fallback `{name} is a {sport} club located in {city}, {country}.`
- **Canonical URL**: `/club/{slug}`
- **JSON-LD**: `@type: SportsTeam` with `name`, `sport`, `address`, `geo` (lat/lng), `sameAs` (social links)

---

### Marketplace Routes
- `/market` - General market page
- `/market/[listing_id]` - Market item detail

### Collections & NFTs
- `/collection/[collection_id]` - Collection details
- `/nft-detail/[nft_id]` - NFT detail view
- `/zone/collectible/[collectible_id]` - Collectible in zone
- `/choose-collection` - Choose collection page
- `/create-collection` - Create new collection

---

## User Profile Routes

### Profile Pages
- `/profile/[username]` - User profile by username
- `/zone` - User's personal zone
- `/zone/[user_id]` - User's zone by ID
- `/zone/edit_zone` - Edit zone settings
- `/profile/edit-profile` - Edit profile

### Social Features
- `/followers` - User's followers list
- `/following` - Users following list

### Account Management
- `/settings` - Settings page
- `/settings/notifications` - Notification settings
- `/notifications` - Notifications page

---

### Sponsorship Routes
- `/packages` - Packages listing page
- `/coupons` - Coupons page

---

## Onboarding Routes
- `/onboarding` - Onboarding overview
- `/onboarding/edit/[field]` - Edit onboarding field
- `/onboarding/edit/avatar` - Edit avatar
- `/onboarding/edit/badge` - Edit badge
- `/onboarding/edit/welcome` - Welcome during onboarding
- `/onboarding/edit/ownership-proof` - Ownership proof
- `/lets-start` - Let's start page

---

## Supporter Features
- `/supporter` - Supporter overview
- `/supporter/[item_selected]` - Supporter item
- `/supporter/activate-package` - Activate supporter package
- `/supporter/buy-package` - Buy supporter package

---

## News Management (Club Feature)
- `/news/create` - Create news article
- `/news/drafts` - News drafts
- `/news/edit` - Edit news article
- `/news/template` - News templates
- `/news/external-links` - External links management
- `/news/settings` - News settings

---

## Engagement & Rewards
- `/referrals-program` - Referral program
- `/benefits` - Benefits page
- `/benefits/stats` - Benefits stats
- `/tiers` - Tier information
- `/sponsors` - Sponsors page

---

## Explore & Search
- `/explore` - Explore marketplace
- `/explore/search` - Explore with search
- `/search` - Search page

---

## DYNAMIC ROUTE PARAMETERS

### Frontend Parameters
- `[listing_id]` - NFT listing identifier
- `[nft_id]` - NFT identifier
- `[collection_id]` - Collection identifier
- `[username]` - User's username
- `[user_id]` - User's ID
- `[clubSlug]` - Club identifier (format: `{name}-{city}`)
- `[collectible_id]` - Collectible identifier

---

## KEY CONCEPTS

### Claimed vs Unclaimed Clubs
- **Unclaimed**: Stored in `Clubs` collection, can be claimed by teams
- **Claimed**: Stored as `Users` with role=CLUB, full platform features