Eurovision-25-backend-old/README.md

Eurovision 25 Backend

This is the backend system for the Eurovision 25 application. It provides the necessary APIs and services to support the frontend, including:

• Voting Management: Handle voting submissions and results.
• Participant Data: Manage information about participating countries and artists.
• Event Scheduling: Provide details about the event schedule and performances.

Endpoints

Admin Endpoints

User Management

• POST /admin/users: Add a user (assign to a group).
• GET /admin/users: List all users (with is_active filter).
• PUT /admin/users/{user_id}: Edit user (e.g., toggle is_active, change group).

Group Management

• POST /admin/groups: Create a group (e.g., "Berlin Household").
• PUT /admin/groups/{group_id}: Edit group (e.g., rename, toggle is_active).

Contest & Song Management

• POST /admin/contests: Create a contest.
• PUT /admin/contests/{contest_id}: Edit contest (title, status).
• POST /admin/contests/{contest_id}/songs: Add a song to the contest.
• PUT /admin/contests/{contest_id}/songs/{song_id}: Edit song details (lyrics, tags).
• PUT /admin/contests/{contest_id}/activate: Start the contest.
• PUT /admin/contests/{contest_id}/close: End the contest (freeze reviews).

---

User Authentication

• POST /login: Authenticate with username/password (returns JWT token).

---

Game Flow Endpoints

Contest Data

• GET /contests/active: Get active contest metadata (status, closure time).
• GET /contests/active/songs: List all songs (with country, artist, lyrics, tags, AI interpretation).

Review Management

• POST /reviews: Submit review for a song (song/wardrobe/stage scores + optional text).
• PUT /reviews/{review_id}: Edit review (blocked if contest is closed).
• GET /reviews/me: Get all reviews submitted by the current user for the active contest.

---

Results & Statistics

Core Results

• GET /scores/groups: Scores aggregated by group.
• GET /scores/unified: Global combined scores.

Detailed Statistics

• GET /stats/categories: Top songs in each category (song, wardrobe, stage) – switchable between group/global via query param ?scope=group|global.
• GET /stats/rankings: Full ranked song list (sorted by total score) – scope filterable.
• GET /stats/consistency: Standard deviation of scores per song (identify divisive entries).
• GET /stats/group-comparison: Compare average scores between groups (e.g., "London vs. Madrid").

---

Name	Operation	URL	Description
Admin Endpoints
Add User	POST	/admin/users	Add a new user (assign to a group).
List Users	GET	/admin/users	List all users (filter by is_active).
Edit User	PUT	/admin/users/{user_id}	Edit user details (e.g., toggle is_active, change group).
Create Group	POST	/admin/groups	Create a new group (e.g., "Berlin Household").
Edit Group	PUT	/admin/groups/{group_id}	Edit group details (e.g., rename, toggle is_active).
Create Contest	POST	/admin/contests	Create a new contest.
Edit Contest	PUT	/admin/contests/{contest_id}	Edit contest details (e.g., title, status).
Add Song	POST	/admin/contests/{contest_id}/songs	Add a song to the contest (includes lyrics, tags, etc.).
Edit Song	PUT	/admin/contests/{contest_id}/songs/{song_id}	Edit song details (e.g., lyrics, tags).
Activate Contest	PUT	/admin/contests/{contest_id}/activate	Start the contest (allow reviews).
Close Contest	PUT	/admin/contests/{contest_id}/close	End the contest (freeze reviews).
User Authentication
Login	POST	/login	Authenticate user (returns JWT token).
Game Flow Endpoints
Get Active Contest	GET	/contests/active	Fetch metadata of the active contest (e.g., status, closure time).
List Songs	GET	/contests/active/songs	List all songs in the active contest (with lyrics, tags, AI interpretation).
Submit Review	POST	/reviews	Submit review for a song (song/wardrobe/stage scores + optional text).
Edit Review	PUT	/reviews/{review_id}	Edit review (blocked if contest is closed).
Get User Reviews	GET	/reviews/me	Fetch all reviews submitted by the current user for the active contest.
Results & Statistics
Extra	GET	/stats/extra	A dictionary of the following: - Song with the highest standard deviation in total scores. - Most common tag among top 25% of songs + example song.

---