We'll try to make the app as simple as possible but also not too simple so you'll see how larger apps should be created.

Entities and basic operations

We should start with entities or user flows. The order depends on the expected app size, your domain knowledge and other factors.

In our case, it's easier to identify and describe WHAT we want to change (clients, projects, time entries, ..) than HOW we want to change them. We would probably start with user flows (HOW) when we already know complex business processes and we need to "support" them by our entities.


  • Everybody can register a new account.
  • Logged users can delete their accounts.
  • Logged users can change their names, emails and passwords.


  • Users can create new clients - all clients would have only one property - a name.
  • Users can modify clients.
  • Users can delete clients. It would also delete all dependent entities.


  • Users can create new projects - all projects would have only one property - a name.
  • Users can modify clients.
  • Users can delete projects. It would also delete all dependent entities.
  • Each project has to be associated with the one client.

Time Entries

  • Users can create a new time entry only by start/stop mechanism.
  • Users can modify time entries.
  • Users can delete time entries.
  • Each time entry has to be associated with the one project.
  • Each time entry has these properties:
    • When it has been started.
    • When it has been stopped (optional). Only one time entry may have undefined stopped timestamp.
    • A title.

Time Block

  • Users can create new time blocks.
  • Users can modify time blocks.
  • Users can delete time blocks. It would also delete all dependent entities.
  • Each time block has to be associated with the one client.
  • Each time block has these properties:
    • Duration.
    • Is it billable?
    • Has it been paid? (If it's billable).


  • Users can create one invoice for each time block.
  • Users can delete invoices.
  • Users can modify invoices.
  • Each invoice has these properties:
    • Custom id (optional) - e.g. invoice variable symbol.
    • Link to the invoice (optional) - e.g. https://an_invoice_service/invoices/xx.pdf.

Entity Diagram

PlantUML code | SVG generated by plantuml-editor.kkeisuke.com


These entities may or may not be represented in our code or database the same way:

  • Time Entry may be represented in the code by two structs: IncompleteTimeEntry and CompleteTimeEntry.
  • Time Entry could be just an anonymous list item in a Project field while you are saving it to your storage.

The entity list above is just a part of the first modeling phase and it should be simple/non-technical enough to discuss it with your clients.

P.S. I don't want to introduce any terminologies defined by DDD, databases, or ORMs. Let's keep it simple and pragmatic. For instance, Model is always a Seed Model, not domain model or persistence model or anything else. Similarly, each Entity above could be either entity or value object in the context of DDD.

Basic User Flows

Let's describe only the basic user flows to get and idea how the user would use the app. The main goal is to create a foundation for our future sitemap and GUI design. Also user flows may help to discover major problems with our entities - especially if we forget to define some of them.

Registration / Login

  1. User clicks the button Register / Login.
  2. User is redirected to hosted Registration / Login page by 3rd party identity provider.
  3. User enters email address, name and password.
  4. User clicks the confirmation button.
  5. User is redirected to the Time Tracker page.


  1. User clicks the button Logout.
  2. User is logged out and redirected to the Home page.

Manage Clients & Projects

  1. User clicks the button Clients & Projects.
  2. The page Clients & Project appears.
  3. A list with Clients and Projects appears. Each Client has his Projects listed below itself.
  4. All Clients and Projects are editable in-place.
  5. There isn't a "save button". Everything is saved on blur or on action button click. Removing should be confirmed through the modal dialog box.

Add Time Entry

  1. User clicks the button Time Tracker.
  2. The Time Tracker page appears.
  3. User clicks the Start button beside the chosen Project.
  4. A new Time Entry with the enabled timer is prepended below the chosen Project.
  5. User observes changing timer within the new Time Entry (probably represented as 00:00:00).
  6. User can edit Time Entry properties like title in-place.

Add Time Block

  1. User clicks Time Blocks.
  2. The Time Blocks page appears.
  3. A list with Clients, time statistics and Time Blocks appears.
  4. User clicks Add Time Block button.
  5. The default Time Block with the duration 20h is created.
  6. User can edit the duration, mark the Time Block as billable and paid or attach the Invoice.

We may add more user flows, but I think it's enough and we can move to the next steps. Let's define technical requirements in the next chapter.