The best way to describe an application is through its user stories. User stories are very simple descriptions of all the interactions a user can have with an application and is the first high-level document that is usually written when a project starts.

The level of detail for each interaction is at first very simple, then gets revisited every time a new particular case appears. User stories are also helpful to detect when it's worth splitting a feature into its microservice: a story that stands on its own could be a good candidate.

For Runnerly, we can start with this small set:

• As a user, I can create an account on Runnerly with my email and activate it through a confirmation link I receive in my mailbox.
• As a user, I can connect to Runnerly and link my profile to my Strava account.
• As a connected user, I can see my last 10 runs appear in the dashboard.
• As a connected user, I can add a race I want to participate in. Other users can see the race as well in their dashboard.
• As a registered user, I receive a monthly report by email that describes how I am doing.
• As a connected user, I can select a training plan for a race I am planning to do, and see a training schedule on the dashboard. A training plan is a simple list of runs that are not done yet.

There are already a few components emerging from this set of user stories. In no particular order, these are:

• The app needs a registration mechanism that will add the user to our database and make sure they own the email used for registration.
• The app will authenticate users with a password.
• To pull data out of Strava, a strava user token needs to be stored in the user profile and used to call the service.
• Besides runs, the database needs to store races and training plans.
• Training programs are a list of runs to be performed at specific dates to be as performant as possible for a given race. Creating a good training plan requires information about the user, such as their age, sex, weight, and fitness level.
• Monthly reports are built by querying the database and generating a summary sent by email.

These descriptions are enough to get us started. The next section describes how the application can be designed and coded.