diff --git a/README.md b/README.md index e69de29..ac33159 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,96 @@ +# 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.
| + +--- \ No newline at end of file