docs(minimal-user-flows): atomic requirements. #196
+88
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| {"type":"pages-state","id":1,"at":"before anyone signs in","phase":"—","capabilities":[],"sees":{"anonymous":"the landing page and an empty public hackathon list; a “Log in” button","admin1":"not signed in","user1":"not signed in","user2":"not signed in"}} | ||
| {"type":"action","id":2,"actor":"admin1","title":"logs in to the platform","page":"/ → “Log in” → Keycloak sign-in","provides":"username, password","comment":"Signs in through Keycloak; the session is what identifies them and their role on every step below."} | ||
|
|
||
| # Hackathon Creation | ||
| {"type":"action","id":3,"actor":"admin1","title":"admin creates and publishes the hackathon","page":"/hackathons/create — fill name, dates, visibility, main image","provides":"name, description rich markdown (tables, youtube embeded videos, images), visibility, main image, startsAt, endsAt","comment":"Creates the event and returns the hackathonId every later step targets. Logo is an image url."} | ||
| {"type":"action","id":5,"actor":"admin1","title":"admin confirms the event is published","page":"/my/hackathon/{id}/overview","provides":"hackathonId","comment":"Reads the event back to confirm name, description and image URL were stored."} | ||
| {"type":"pages-state","id":6,"at":"the event is created and public","phase":"none declared yet","capabilities":["(defaults — nothing scheduled yet)"],"sees":{"anonymous":"the public event page — name, description, logo","admin1":"the full manage hub for the new event (config, timeline, participants, teams, prizes)","user1":"(not registered) the public event page","user2":"(not registered) the public event page"}} | ||
|
|
||
| # Hackathon Setup | ||
| {"type":"action","id":7,"actor":"admin1","title":"admin builds the custom registration form","page":"/my/hackathon/{id}/forms — Registration form (add questions)","provides":"Affiliation (text, required); Experience level (select, required); Skills (tags); Why do you want to take part? (textarea, required); Dietary requirements (text); T-shirt size (select); I accept the Code of Conduct (consent, required); I consent to event photography (consent)","comment":"The admin composes a CUSTOM registration questionnaire — each question carries a label, a type (short text, single-choice, tags, or long text) and whether it is required. Here: Affiliation (text, required), Experience level (single-choice), Skills (tags), a free-text Motivation (required), Dietary needs, and T-shirt size (single-choice), plus two consent checkboxes (Code of Conduct required, photos optional). Participants answer exactly these on their registration form."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: a custom registration form. (Needed early) |
||
| {"type":"action","id":8,"actor":"admin1","title":"admin builds the custom submission form","page":"/my/hackathon/{id}/forms — Submission form (add questions)","provides":"Repository URL (url, required); Live demo URL (url); One-paragraph summary (textarea, required); Primary category (select, required); Slides (PDF) — upload or link (file-or-url)","comment":"The admin defines the CUSTOM questionnaire teams answer when they turn work in: Repository URL (required), a Live demo URL, a Summary (long text, required), a Primary category (single-choice, required), and Slides (upload or external link). The submission is validated against exactly these questions."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: a custom submission form. (Needed later)
Member
Author
There was a problem hiding this comment. Hi @sabinem, we need this earlier, as some questions need to be taken from the participants once they are registered. A user should be able to edit these options afterwards (but I didn't include that in this basic flow as I don't consider that a priority) |
||
| {"type":"action","id":9,"actor":"admin1","title":"admin sets the voting policy","page":"/my/hackathon/{id}/voting — Rules","provides":"hackathonId, mechanism, oneBallotPer, ownTeamVoting, organizerVoting, tieBreak","comment":"Sets the rules of the vote up front: mechanism, whether own-team votes count, and how ties break."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: decide voting method and rules. Not all voting methods need to be supported initially, correct? (Needed later)
Member
Author
There was a problem hiding this comment. @sabinem, this is correct; we should give priority to: Multiple categories and a single vote. |
||
| {"type":"action","id":11,"actor":"admin1","title":"admin sets the email templates","page":"/my/hackathon/{id}/email","provides":"hackathonId, templates","comment":"The templates the platform sends at each milestone, written once with placeholders."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: email template. So far email sending has not been implemented on the platform, so is that also a requirement? When and what emails need to go out? (Needed early)
Member
Author
There was a problem hiding this comment. Hi @sabinem, this refers to email templates that are markdown-prepopulated and can be copied and pasted quickly to share a hackathon invitation to users already registered on the platform via an external email client. This is a frontend task. It's low priority, but it saves a lot of time. I'll drop it from the flow. |
||
| {"type":"action","id":12,"actor":"admin1","title":"admin defines the prize table","page":"/my/hackathon/{id}/prizes","provides":"rank, title","comment":"Records the prize table; the admin has the final say on prizes."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: don't publish results before admin approved. (needed later) |
||
| {"type":"action","id":13,"actor":"admin1","title":"admin sets the phases with time windows","page":"/my/hackathon/{id}/??PHASES??","provides":"hackathonId, registrationOpens, registrationCloses, proposalsClose, preferencesClose, submissionsClos","comment":"The clock: when each stage opens and closes. Opened now so registration and proposals can proceed."} | ||
| {"type":"action","id":16,"actor":"admin1","title":"admin adds the Ideation phase","page":"/my/hackathon/{id}/timeline → New phase","provides":"hackathonId, name, startsAt, endsAt, description","comment":"Lays the timeline: each phase is a named window participants see. Ideation is first."} | ||
| {"type":"action","id":17,"actor":"admin1","title":"admin adds the Hacking phase","page":"/my/hackathon/{id}/timeline → New phase","provides":"hackathonId, name, startsAt, endsAt, description","comment":"The build window."} | ||
| {"type":"action","id":18,"actor":"admin1","title":"admin adds the Judging phase","page":"/my/hackathon/{id}/timeline → New phase","provides":"hackathonId, name, startsAt, endsAt, description","comment":"The final window, where voting happens."} | ||
| {"type":"action","id":19,"actor":"admin1","title":"admin schedules voting to open in the Judging phase","page":"/my/hackathon/{id}/timeline/{phaseId}/edit — tick “Vote”","provides":"hackathonId, capability, openInPhaseId","comment":"Linking VOTE to the Judging phase means voting opens automatically when that phase becomes current — not before."} | ||
| {"type":"action","id":20,"actor":"admin1","title":"admin sets the opening capabilities","page":"/my/hackathon/{id}/manage — capability panel","provides":"hackathonId, capabilities","comment":"Register and propose open now; submit, vote and results stay closed until their phases."} | ||
| {"type":"action","id":21,"actor":"admin1","title":"admin declares the Ideation phase current","page":"/my/hackathon/{id}/manage — Now / Next","provides":"hackathonId, phaseId","comment":"Declares which phase is “now” so the hub and participants agree on the current stage."} | ||
| {"type":"pages-state","id":22,"at":"setup complete — registration open, Ideation is current","phase":"Ideation","capabilities":["register","propose_projects","set_team_preferences"],"sees":{"anonymous":"the public event page and the two pre-proposed projects","admin1":"everything, plus the Now/Next box showing Ideation","user1":"the public event page with a Join button (registration is open)","user2":"the public event page with a Join button"}} | ||
|
|
||
| # Projects addition by admin | ||
| {"type":"action","id":23,"actor":"admin1","title":"admin proposes Project1 (preconfigured)","page":"/my/hackathon/{id}/projects/proposals/propose","provides":"hackathonId, trackId, title, description","comment":"The admin pre-proposes Project1 so the event ships with projects ready — participants prefer and join these rather than proposing their own."} | ||
| {"type":"action","id":24,"actor":"admin1","title":"admin approves Project1","page":"/my/hackathon/{id}/projects/proposals → Approve","provides":"projectId","comment":"Approves Project1, making it a real project a team can be built around."} | ||
| {"type":"action","id":25,"actor":"admin1","title":"admin proposes Project2 (preconfigured)","page":"/my/hackathon/{id}/projects/proposals/propose","provides":"hackathonId, trackId, title, description","comment":"The admin pre-proposes Project2, so there are two projects to spread the two users across."} | ||
| {"type":"action","id":26,"actor":"admin1","title":"admin approves Project2","page":"/my/hackathon/{id}/projects/proposals → Approve","provides":"projectId","comment":"Approves Project2."} | ||
|
|
||
| # 1st User registration | ||
| {"type":"action","id":27,"actor":"user1","title":"logs in to the platform","page":"/ → “Log in” → Keycloak sign-in","provides":"username, password","comment":"Signs in through Keycloak; the session is what identifies them and their role on every step below."} | ||
| {"type":"pages-state","id":28,"at":"user1 signs in — a platform account now exists","who":"user1","page":"/manage/users","shows":"a new row in the platform-wide user list (admin only)"} | ||
| {"type":"action","id":29,"actor":"user1","title":"user1 registers","page":"/dashboard → Join","provides":"hackathonId","comment":"user1 registers; waitlisted until the organiser approves."} | ||
| {"type":"pages-state","id":30,"at":"user1 joins the hackathon","who":"user1","page":"/my/hackathon/{id}/participants","shows":"a new row badged “Waitlisted” in Manage participants (the registration list)"} | ||
| {"type":"action","id":31,"actor":"admin1","title":"admin approves user1","page":"/my/hackathon/{id}/participants → Approve","provides":"hackathonId, userId","comment":"The organiser confirms user1 — approval turns a registrant into a full participant."} | ||
| {"type":"pages-state","id":32,"at":"admin approves user1","who":"user1","page":"/my/hackathon/{id}/participants","shows":"user1's row flips from “Waitlisted” to “Confirmed”"} | ||
| {"type":"action","id":33,"actor":"user1","title":"user1 configures their profile (name, skills, avatar image URL)","page":"/account — edit profile","provides":"displayName, affiliation, skills, avatarUrl","comment":"user1 fills their platform profile. The avatar is set from an image URL hosted by an EXTERNAL provider — a link, not an upload; the platform stores only the URL."} | ||
| {"type":"action","id":34,"actor":"user1","title":"user1 submits the registration form (participation)","page":"/register/{id} — the registration form","provides":"hackathonId, responses, consents","comment":"user1 answers the admin's custom registration questions (affiliation, experience, skills, motivation, diet, T-shirt) and ticks the required consent; the answers are stored against their participation."} | ||
|
Comment on lines
+37
to
+38
Collaborator
There was a problem hiding this comment. Requirement: Custom Registration form, set by hackathon owner?
Member
Author
There was a problem hiding this comment. Yes, the admin1 in this case\ |
||
|
|
||
| # 2nd User registration | ||
| {"type":"pages-state","id":35,"at":"user1 submits the registration form","who":"user1","page":"/my/hackathon/{id}/participants → View","shows":"their custom-form answers (affiliation, experience, motivation …) are now on file under their row"} | ||
| {"type":"action","id":36,"actor":"user2","title":"logs in to the platform","page":"/ → “Log in” → Keycloak sign-in","provides":"username, password","comment":"Signs in through Keycloak; the session is what identifies them and their role on every step below."} | ||
| {"type":"pages-state","id":37,"at":"user2 signs in — a platform account now exists","who":"user2","page":"/manage/users","shows":"a new row in the platform-wide user list (admin only)"} | ||
| {"type":"action","id":38,"actor":"user2","title":"user2 registers","page":"/dashboard → Join","provides":"hackathonId","comment":"user2 registers."} | ||
| {"type":"pages-state","id":39,"at":"user2 joins the hackathon","who":"user2","page":"/my/hackathon/{id}/participants","shows":"a second row badged “Waitlisted”"} | ||
| {"type":"action","id":40,"actor":"admin1","title":"admin approves user2","page":"/my/hackathon/{id}/participants → Approve","provides":"hackathonId, userId","comment":"The organiser confirms user2."} | ||
| {"type":"pages-state","id":41,"at":"admin approves user2","who":"user2","page":"/my/hackathon/{id}/participants","shows":"user2's row flips to “Confirmed”"} | ||
| {"type":"action","id":42,"actor":"user2","title":"user2 configures their profile (name, skills, avatar image URL)","page":"/account — edit profile","provides":"displayName, affiliation, skills, avatarUrl","comment":"user2 fills their profile and sets an avatar from an EXTERNAL image URL (a link to a picture hosted elsewhere)."} | ||
| {"type":"action","id":43,"actor":"user2","title":"user2 submits the registration form (participation)","page":"/register/{id} — the registration form","provides":"hackathonId, responses, consents","comment":"user2 answers the same custom questions with their own responses and submits their participation."} | ||
| {"type":"pages-state","id":44,"at":"both users are registered and confirmed participants","phase":"Ideation","capabilities":["register","propose_projects","set_team_preferences"],"sees":{"anonymous":"the public event page (never the member area)","admin1":"the participants roster with two confirmed people and their registration answers","user1":"the member area — overview, projects, teams, and their own profile; may set preferences","user2":"the member area; may set preferences"}} | ||
|
|
||
| # Projects preferences | ||
| {"type":"action","id":45,"actor":"user1","title":"user1 prefers Project1","page":"/my/hackathon/{id}/projects — mark a preferred project","provides":"projectId","comment":"user1 marks the project they want to work on; organisers use preferences for team matching."} | ||
| {"type":"pages-state","id":46,"at":"user1 sets a project preference","who":"user1","page":"/my/hackathon/{id}/projects — preferences export","shows":"user1's preferred project shows in the organiser's preferences export"} | ||
| {"type":"action","id":47,"actor":"user2","title":"user2 prefers Project2","page":"/my/hackathon/{id}/projects — mark a preferred project","provides":"projectId","comment":"user2 marks their preferred project."} | ||
|
|
||
| # Team formation | ||
| {"type":"action","id":48,"actor":"admin1","title":"admin exports preferences for team matching in csv/json","page":"/my/hackathon/{id}/projects — Export preferences","provides":"hackathonId","comment":"The organiser pulls everyone's preferences to inform how teams are formed."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: Team matching csv as export and import (Needed later): to be discussed, whether team matching can happen directly in the platform)
Member
Author
There was a problem hiding this comment. Hi @sabinem, after demoing the team assignment interface, the team found it a bit complex, especially with 100 participants. @hanaCasey and I took the decision to skip this step and allow them to upload a csv/json with columns containing participants' emails or usernames. We can validate these and upload the db. This is based on how the team assignment happens in reality: a big spreadsheet and manual assignment by the hackathon organisers. |
||
| {"type":"action","id":49,"actor":"admin1","title":"admin creates Team1 on Project1","page":"/my/hackathon/{id}/teams/manage → New team","provides":"name, projectId","comment":"Team1 is bound to Project1 — a seat the CSV import will fill."} | ||
| {"type":"action","id":50,"actor":"admin1","title":"admin creates Team2 on Project2","page":"/my/hackathon/{id}/teams/manage → New team","provides":"name, projectId","comment":"Team2 is bound to Project2."} | ||
| {"type":"action","id":51,"actor":"admin1","title":"admin defines team membership from an uploaded CSV","page":"/my/hackathon/{id}/teams/manage → Import → upload CSV → Apply","provides":"upload teams.csv (columns: user_email, project, team)","comment":"The organiser assigns each confirmed participant to a team in bulk: user1 joins Team1, user2 joins Team2. Align the copy strings to the Manage-Teams importer when running for real."} | ||
|
Collaborator
There was a problem hiding this comment. belongs to requirement above on external team formation |
||
| {"type":"pages-state","id":52,"at":"teams are formed","phase":"Ideation","capabilities":["set_team_preferences"],"sees":{"anonymous":"the public event page","admin1":"the teams board with Team1 and Team2 and their members","user1":"their team (Team1) and its page","user2":"their team (Team2)"}} | ||
| {"type":"pages-state","id":53,"at":"teams assigned from the CSV","who":"user1 & user2","page":"/my/hackathon/{id}/teams","shows":"user1 on Team1 and user2 on Team2 in the teams board / people panel"} | ||
|
|
||
| # Hackathon phase | ||
| {"type":"action","id":54,"actor":"admin1","title":"admin advances to the Hacking phase","page":"/my/hackathon/{id}/manage — Now / Next → advance","provides":"hackathonId, phaseId","comment":"Moving the marker into Hacking opens the submissions the phase names."} | ||
|
Collaborator
There was a problem hiding this comment. Currently capabilities are not opened automatically, but the admin has to manually open them. This is also only relevant in a later phase. -> I would keep that as it is for now. No ticket yet. |
||
|
|
||
| # Projects submissions | ||
| {"type":"pages-state","id":55,"at":"Hacking phase — submissions open","phase":"Hacking","capabilities":["create_project_submissions"],"sees":{"anonymous":"the public event page","admin1":"submissions as they arrive","user1":"a “Turn in work” control for Team1","user2":"a “Turn in work” control for Team2"}} | ||
| {"type":"action","id":56,"actor":"user1","title":"user1 turns in Team1's work","page":"/my/hackathon/{id}/submissions","provides":"teamId, projectId, result, form","comment":"user1 submits Team1's work against Project1."} | ||
| {"type":"pages-state","id":57,"at":"user1 turns in Team1's work","who":"Team1","page":"/my/hackathon/{id}/submissions","shows":"Team1's submission appears for organisers to review"} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: Organizers can review submission (later, to be discussed): What does "review" mean?
Member
Author
There was a problem hiding this comment. Hi @sabinem, organisers receive the submissions, but they aren't published directly on the submissions list page. Organisers can hold some submissions for manual revision to ensure that all the content provided is correct (for instance, that all the links are valid and point to the right document) |
||
| {"type":"action","id":58,"actor":"user2","title":"user2 turns in Team2's work","page":"/my/hackathon/{id}/submissions","provides":"teamId, projectId, result, form","comment":"user2 submits Team2's work."} | ||
|
|
||
| # Voting phase | ||
|
Collaborator
There was a problem hiding this comment. Requirement: Voting implementation (Needed later, to be discussed) |
||
| {"type":"action","id":59,"actor":"admin1","title":"admin advances to the Judging phase","page":"/my/hackathon/{id}/manage — Now / Next → advance","provides":"hackathonId, phaseId","comment":"Advancing to Judging opens the VOTE capability, which was linked to this phase in setup."} | ||
| {"type":"action","id":60,"actor":"admin1","title":"admin opens voting","page":"/my/hackathon/{id}/voting → Open voting","provides":"hackathonId, votingEnabled","comment":"Voting needs BOTH this master switch and the VOTE capability the Judging phase opened; the organiser flips it here."} | ||
| {"type":"pages-state","id":61,"at":"Judging phase — voting open","phase":"Judging","capabilities":["vote"],"sees":{"anonymous":"the public event page","admin1":"the tally as ballots arrive (organisers do not vote)","user1":"a ballot to cast (not for their own team)","user2":"a ballot to cast"}} | ||
| {"type":"action","id":62,"actor":"admin1","title":"admin creates a vote category","page":"/my/hackathon/{id}/voting → Add category","provides":"hackathonId, name, description, votingMethod, voterType","comment":"A category is what ballots are cast in; opening voting needs at least one."} | ||
| {"type":"action","id":63,"actor":"user1","title":"user1 casts a ballot (for Team2)","page":"/my/hackathon/{id}/voting → cast a ballot","provides":"singleChoice","comment":"user1 votes for the other team's submission — own-team voting is off in this event's policy."} | ||
| {"type":"pages-state","id":64,"at":"user1 casts a ballot","who":"user1","page":"/my/hackathon/{id}/voting — tally (organiser-only)","shows":"user1's ballot is counted in the tally; ballots are organiser-only to read"} | ||
| {"type":"action","id":65,"actor":"user2","title":"user2 casts a ballot (for Team1)","page":"/my/hackathon/{id}/voting → cast a ballot","provides":"singleChoice","comment":"user2 votes for the other team."} | ||
|
|
||
| # Winners assignation | ||
| {"type":"action","id":66,"actor":"admin1","title":"admin records the winner","page":"/my/hackathon/{id}/voting → record placement","provides":"categoryId, submissionId, position, title","comment":"The admin places the winner from the tally — results are advisory until the admin records them (the admin has the final voice)."} | ||
|
Collaborator
There was a problem hiding this comment. Requirement: Admin makes the final decision who wins and the results are not published automatically after computation? (Needed later, to be discussed)
Member
Author
There was a problem hiding this comment. HI @sabinem, exactly, we keep the final voting publication to an admin action. |
||
| {"type":"action","id":67,"actor":"admin1","title":"admin publishes the results","page":"/my/hackathon/{id}/manage — capability panel (View results)","provides":"hackathonId, capabilities","comment":"Turning on VIEW_RESULTS is what publishes the placements to participants."} | ||
| {"type":"pages-state","id":68,"at":"results published","phase":"Judging","capabilities":["vote","view_results"],"sees":{"anonymous":"the public event page (and published winners, if surfaced there)","admin1":"the recorded placements","user1":"the published winner on the results page","user2":"the published winner"}} | ||
| {"type":"action","id":69,"actor":"user1","title":"user1 views the published results","page":"/my/hackathon/{id}/voting — Results","provides":"categoryId","comment":"user1 sees the published winner. The event is complete."} | ||
| {"type":"action","id":70,"actor":"user2","title":"user2 views the published results","page":"/my/hackathon/{id}/voting — Results","provides":"categoryId","comment":"user2 sees the published winner. The event is complete."} | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Comment: Capabilities and Phases are implemented are not tightly coupled on the platform, and we will keep it that way:
This seemed more adapted to the needs of a hackathon.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sabinem, After discussing with Valerio and Thibaut, they do not require granular access to the capabilities. They will define the phase beforehand and associate some capabilities beforehand. Then they asked for manual activation of phases.
I think this could help avoid many bugs related to capability activation overwriting phases, or vice versa, and simplify the flow.