add api description

[raphael-frank]

I added descriptions to all API endpoints. They consist of a short summary followed by a list of what this endpoint returns based on the permission/role of the caller.
Note that these permissions are additive so for example if you are a member of a team and a director of a different sport you get some permissions from that sport and the different team in the same response. The web client will be responsible for filtering out the information it truly needs or it could just call the detail endpoints that only return one object per request.

Closes #7.

[raphael-frank]

@FadyGergesRezk @f-s-h In the future, we might change the letter service and report service endpoints so that one can limit the scope so for example only send mail to team and for report only generate report in context of a certain team. For now, this is not too relevant.

[FadyGergesRezk]

I have 3 points regarding this that need some clarification:

1. Should member creation set a Keycloak credential directly, or go through Keycloak's admin API?
2. for get all members i think relying on the client to filter wont really work as a privacy thing since the full response is still visible in devtools no matter what the ui shows. so any trainee could just read every member's data... shouldnt the filtering be server side here like getMemberDetails already does?
3. theres members/{member_id} but the client doesnt have its own member id, only the email from the token... could we either get the member id as a claim in the token or let me resolve myself by email so i dont have to pull the whole list just to find my own id

[FadyGergesRezk]

quick follow up on 3 — since the team/feedback/transaction reference fields are all member UUIDs in the db (not emails), resolving by email still leaves me needing my own UUID to match against them, so the token claim is probably the real fix

[raphael-frank]

Regarding the points:

1. Member creation should create the keycloak client directly and for this a password will be parsed. Since we dont want unauthorized creation of new users, only admins can create new users.
2. Its by design that everyone can see the member summary of every member (so first/last name and mail address), but details only for members they are supposed to. I think privacy-wise its okay, imagine github (everybody can see those three fields). For example, you might want to display the name of the director of a sport or the trainers of a team you might want to join and for that you have to resolve the member id to its name.
3. Yes I think we definitely want to have ones own client id in the token and not just the mail.

[raphael-frank]

follow up on 3: it is currently possible to receive the own member id as a token claim. Since we set the member id to be the uuid of the keycloak user on creation, you can just use the following code:
const memberId = keycloak.tokenParsed?.sub where the sub claim is the keycloak user uuid.

[FadyGergesRezk]

I propose adding a GET /members/me and PATCH /members/me for personal profile management, and a GET /members/me/dashboard that returns role-specific data (trainee, coach, director, admin). The backend will determine the role from the authenticated user, providing each user their relevant dashboard view.

[FadyGergesRezk]

I also have a question. I have noticed that some entities mention other entities but use only strings. For example, when you get feedback, it mentions the relevant event as a string. But we can have the same event name for 2 different sports, shouldn't we use IDs for that or what?

[FadyGergesRezk]

for the organization endpoints i have two things:

1. could GET /organization/sports return the teams nested inside each sport instead of us having to call /sports and /teams separately and join them on the client by sport name? something like each sport carrying a teams: [...] array. happy for it to be a thin team summary (id, name, address, member counts) and keep GET /teams/{id} for the full roster — same pattern as EventSummary vs Event. right now to render "sports and the teams in them" i pull both lists and group them myself.

2. related to my earlier ID question — Sport is keyed by name (the path is /sports/{sport_name} and Team.sport is the sport name string), but every other entity (team, member, event...) uses a uuid. shouldn't sport have an id too? the problem is if a director renames a sport via PATCH, every Team.sport still points at the old name and silently breaks, because the reference is a mutable string. with an id PK the name becomes just an editable field. this would mean Team.sport becomes a sport id instead of a name, and sports_linked on events probably too.

[FadyGergesRezk]

following up on the nested-teams point — when a team comes back, trainers/trainees are just array of string. for the roster i need to do two things at once: show the member's name, and match the id against my own sub (and against other uuid refs) to know which trainee is me / whether i'm on the team. a flat list can only be one of those.

could these be MemberSummary objects instead — { id, first_name, last_name, email } — like the member summaries we already get elsewhere? that gives names for display and ids for filtering in one shot, instead of me resolving every id separately. and since you already said member summaries are visible to everyone by design, this doesn't expose anything new — the full member details stay behind getMemberDetails.

[FadyGergesRezk]

two things on the feedback schema:

1. member, event and creator are typed as plain string — so it's not clear if they hold ids or names (swagger shows "string"). could they be format: uuid like id already is? i need member especially to be the id so i can match feedback against the team roster and my own sub — a name wouldn't be matchable (two trainees could share a name).

2. could Feedback gain an optional rating (0–10)? each entry is already per-event + per-trainee, so alongside the written notes the coach could also score the trainee's performance for that session. keeping it optional means existing text-only feedback still works. it'd live on Feedback, not the event.

[FadyGergesRezk]

on events — i'm planning to show a member whether they missed a past session, computed simply as: event is in the past and their id isn't in attendees. for that to be correct i need to confirm what attendees actually means — is it the list of who actually attended (maintained by the coach after the session), or is it an RSVP/expected list?

if it's "who attended", the missed check works as-is (and members don't need any RSVP/write — it's read-only for them). if it's really an RSVP list, then "not in attendees" doesn't mean missed, so i'd handle it differently. just need the semantics pinned down — no schema change either way.

[raphael-frank]

I also have a question. I have noticed that some entities mention other entities but use only strings. For example, when you get feedback, it mentions the relevant event as a string. But we can have the same event name for 2 different sports, shouldn't we use IDs for that or what?

It references the primary key which is the ID. I will add the format specifier to all uuid cross references for consistency.