[Feat]: Event/Match/Team/Chunk design

[widavies]

Design of how data is structed in events.

For a flexible system, the following should be supported:

• Matches: A series of teams within alliances (not necessarily 6 teams & not necessarily 2 alliances). The match viewer needs to be rethought from the legacy. The tabbed view (where each tab is a match) is clunky, and with multi-paged forms, this will need to be redesigned.
• Chunk (come up with a better name for this): A chunk is a unique scouting data point. It represents a pairing of a team within a match. Each chunk would ideally support multiple forms. At minimum, a chunk might have a qual and/or match form. However, we'd like to support multiple users filling out the same chunk as well.
• Teams: A user should be able to easily view all the matches a team has been in. Teams should also have good TBA integration. Team profiles should include easy access to robot pictures and past data. Even displaying links towards the teams performance is past events would be huge.

Make sure to also track who won the event. Team profiles should have links to TBA & team website.

[github-actions[bot]]

Community Note:

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and developers prioritize this request
• Please do not leave "+1" or other similar comments that do not add relevant new information or questions
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

[aidan-mundy]

Proposed naming scheme:

An (all caps) FRAGMENT is one TEAM in one ALLIANCE of one MATCH in one EVENT that may or may not be in a DISTRICT, but is definitely in a SEASON (2020 competitive season, 2019 preseason, 2020 offseason, etc)

Multiple SAMPLEs (completed FORMs) may be submitted for each FRAGMENT.

[widavies]

What is the difference between a match and a playoff match? Will these be distinct within the system in some way, or just different names for a match?

Naming strategy works great. A FRAGMENT will replace legacy CHECKOUTs. A FRAGMENT contains a series of SAMPLEs. A SAMPLE maps directly to one completed Roblu form (pit, qual, or match). For flexibility, unlimited samples are allowed (of any type), but certain teams may elect to limit this (1 pit, 1 qual, 1 match) or (1 pit, 1 qual, 2 matches), etc either by procedure, or by a configurable limit within event settings. One thing we'll have to consider is merge conflicts.

The reason merge conflicts (or multiple samples rather) matters comes down to analytics. Let's say each match sample contains "METRIC Y". If a user would like to rank teams by how well they performed at "METRIC Y", it's unclear which sample to pull this from (if there are 2 or more). Should we rank the quality of different scouters? Should the most recent sample by used? Should they be averaged together? Can we design analytics to just display both samples for the same data point? During analytics, it would also be relatively easy to filter by scouter or device, which would be one way to handle it. I imagine once we design analytics, we could figure out a lot of really useful ways to present multiple samples and gain additional insight.

[widavies]

Proposed Design V1

Goals:

• Minimize clicking to get between active events
• Support some level of scoping, when an event is selected, it should be easy to navigate to resources within the event
• Multiple active events. Imagine a use case where a team has one event for their scouting data, is contributing to another team's, and is following another team's.

Notes:

• Roblu's events draw a lot of inspiration from git repos. Events track data, can be forked, can be contributed to with pull requests (syncs), etc.
• The event design is designed with public events, forking, sharing, and following in mind. These won't be added for the first release, but by considering them now, it will make it easier to add them later.

UI Design:

• Navigation drawer: contains a "pinned" events list. Events by default are automatically pinned when created, followed, or forked. Events can be pinned/unpinned manually. Think of this as a quick changer to easily flip between events without having to exit an event, then enter a new event. Pinned events can have nicknames. This is very similar to the events list in legacy, but instead of being exhaustive (and the only way to access events), it is just a "recents" list for quick switching. Image
• Navigation drawer: contains a link to the "events page" The events page is the exhaustive list of all events for a team: archived, subscribed/following, created, etc. This page allowing searching, grouping, etc. Image
• When an event is selected, it is considered "active". The app will remember this, i.e. the same event will be selected if the app is closed and reopened.
• When an event is selected, the app opens the event homepage. At a baseline, this homepage should contain navigational links to access picks, assignments, matches, teams, event settings, and later on analytics. To spruce up the homepage, it could also auto generate recommendations of resources it thinks are important. For example, maybe a preview of the most recent match is displayed at the top. Maybe a link to the most recent sync data is previewed at the top. Images
  • The tab based event viewer is inspired by TBA's event viewer in app.
  • Assignments & pull request tabs design is left to their respective issues and isn't discussed here.
  • What other tabs could be useful? Obviously at some point we will add stats. TBA has tabs for rankings, alliances, awards, district points, OPR stats. Should we integrate some of these?
  • Match viewer & team viewer design is left to a different issue. This issue just discusses the overall structure of the event resource.

Data structure design:

• When a form is completed, it is packaged as a sample. Aside from form data, a sample contains completion time, author, and a UUID uniquely describing the change (following after git, a content hash would probably work well for this).
• Event manifests describe resources within an event. Manifests link metadata to content. Manifests should be quick to load and search.
  • Match manifest: A list of all matches within an event. Each match lists alliances, their respective team numbers, and basic match metadata (start time, location, name, etc.). Does not link to any content. A team number does not have to have an associated team entry in the team manifest.
  • Team manifest: A table of team numbers and associated team metadata (name, location, TBA links, etc.). Does not link to any content.
  • Fragment manifest: A list of fragments. Each fragment has a team id, match id, and a list of one or more samples (sample ids, and some light metadata about the sample: type, author, etc.). If the event has certain sample requirements, say 1 qual, and 2 matches, it is easy to ascertain the status by inspecting the sample metadata list. If the fragment has assignment restrictions, it will list the restriction under the fragment (only device 1, only user A, etc) along with a potential type restriction (qual, match, or either). Fragments may also have a status indicator to indicate if a particular fragment is claimed/in-progress. It's usually better to have a list of immutable events rather than a single status value. So possibly when a user claims a match, they insert a "partial" sample metadata item, and then complete it later.

The fragment manifest must efficiently support querying all fragments with a team id, all fragments with a match id, or a specific fragment for team id and match id.

Some common queries can be achieved as follows:

• Load all teams in a match: For each match in the match manifest, lookup the team from the team manifest.
• Load all matches in a team: For a team in the team manifest, scan the match manifest looking for that team's id. There might be a way to optimize for this.

The advantage of this design is:

• Manifests are very efficient to transfer. Manifests can be efficiently searched.
• Manifests are easier to interact with for merging and syncing by separating metadata important for those tasks for the actual form content that may or may not be needed.

[aidan-mundy]

What is the difference between a match and a playoff match? Will these be distinct within the system in some way, or just different names for a match?

Playoff matches have additional importance and a different set of logic, scoring, and parameters. One thing we will want to do in the future is provide live predictions for event winners and district championship/worlds qualifying teams. Defining a clear separator between Quals and Playoffs makes this an easier logical task to implement in the future because the matches are so different from each other (even down to what certain game elements are worth).

Should we rank the quality of different scouters? Should the most recent sample by used? Should they be averaged together? Can we design analytics to just display both samples for the same data point?

For V1.0 we only need to take the most recent sample. Soon after that we will need to do some planning to implement the added merge features. I think all of these should be options (and probably even more). Take a look at the Citrus Circuits scouting white paper for more ideas. For data structure design, don't worry about merge conflicts. We can handle those with other logic later down the line. Just make sure fields have a way to tell if they were used or not, and a timestamp for the form.

We may want to think about gathering live analytics throughout the match to see exactly when a scout entered data points. When we get into more advanced data analysis, we may be able to correlate scout entry times with OCR scans of the match videos to more accurately resolve discrepancies from the official scoring. I don't think this needs to be at the front of our minds yet, but it is good to think about.

In the manifests and UI we need to account for displaying and handling unknown data. During a competition we need to fight to grab unknown data as soon as it is available. I think this would be best implemented via a central server backend that polls TBA for all event data, and pushes data to the app. If we are pushing data to the app (rather than pulling) it will save data, reduce load on our servers. I think this would be a Roblu Cloud exclusive feature. On-device auto sync should be handled with user-generated TBA API keys, not Roblu owned ones.

Overall I think this is a good writeup

[widavies]

Adding a few more polishing design details:

• When an event is opened that isn't pinned, it will appear in the event selector, but will disappear when closed. Could potentially show like the three most recent & pins as well.
• Each metric will have an attached "edit" time, which records a timestamp when any changes are made.
  • For certain metrics like the boolean that default to "false", it might be unclear if the user forgot to set it, or if "false" was the correct value and the user just left it at default. It might be best to rethink metrics and allow a third state where neither true or false are checked by default so that a timestamp can be recorded. An analogous case could be extended to other metrics that have a default value that may introduce ambiguity into real data, or just not set data.
• For now, a simple event viewer is key. We can build on top of this, and the tab design makes it easy to create tabs for important content and bury less important content within tabs. When looking at the TBA event viewer, they have tabs for rankings, points, awards, and more. I also spent some time considering what to display on match/team cards within their tabs. It may be useful to display team status ("eliminated", "finalists", etc) or to display team OPRs, match point breakdowns, etc. After some consideration, for release V1, let's wait to include any of these things. For V2, we plan to release stats, and we can carefully consider what stats and generated information to display throughout the app based off user feedback.
• The fragment manifest will contain a list of fragments. Each fragment contains the follow metadata:
  • Match id
  • Team id
  • Assignment restriction: A list of assignment lock objects that indicate form type & devices/users that are allowed to scout this fragment.
  • Samples: A list of sample objects. Each sample object has a form type, an author, and a kind. The kind may be full, in which case the sample contains a completed form. The kind may be started, in which a user has claimed that they have started working on the fragment for a particular form type. Later, when the user submits a full sample, the started object can remain, but will be defunct. This started tag is useful when "fragments" are up for grabs & users self-opt to complete them. The started tag is basic a user's claim to complete the fragment.
• Matches should be categorized by their kind, as in TBA (quals, playoffs, etc.)
• Search will search everything, teams, matches, picks, etc.
• Sorting can be added later, as its not super important. For now, sorting matches numerically and sorting teams by number is sufficient.