DEV Community: Chloe

Free Time Helper - a new project

Chloe — Wed, 28 Dec 2022 00:02:03 +0000

I'm thinking of starting a new project called Free Time Helper. This article has two parts:

What is the project? What are the core use cases?
What are the APIs? What is the core of the architecture?

Use Cases

User-initiated Flow

I don't know what I want to do right now
I ask the system what to do. I tell it how much free time* I have right now.
The system gives a Suggestion, which may either be a Question or an Activity.

* free time: how much time is there between now and the next time I intend to do something else, such as get ready for bed, go to work, leave for an appointment, etc.?

System-initiated Flow:

The system gives a Suggestion

Question

The system asks me a question. For example:
1. What's something that energizes you?
2. What's your best friend's name?
I can either:
1. Send an answer to the system
  1. The system gives a new Suggestion
2. Tell the system "I don't want to answer this question right now"
  1. The system gives a new Suggestion
3. Do nothing
  1. The system does not communicate with me until I initiate contact with it again

Activity

The system suggests an activity. For example:
1. text {best friend}
2. do {thing that energizes you}
3. spend 5 minutes outside
4. listen to your favorite song
5. Read a specific article
I can either:
1. Tell the system I accept the suggestion
  1. I take some time to do the suggested activity
  2. I tell the system I am done with the suggested activity.
  3. The system gives a new Suggestion
2. Tell the system I do not accept the suggestion
  1. The system gives a new Suggestion
3. Do nothing
  1. The system does not communicate with me until I initiate contact with it again

Software Architecture

As usual I will be using the Clean Architecture. As a starting exercise, I've made a diagram showing the interfaces of the innermost ring, the "Entities" or "Enterprise Business Rules" ring. Here, I'm referring to this ring as the "Core" component, since that's more intuitive to me.

To start out with, I tried to imagine the system as having a lot of advanced features, most of which I will probably never get to, and make sure that the interfaces work with all of these. Some advanced features:

Machine learning to estimate how "helpful" (this is intentionally vague) each suggestion will be for each user
A system-initiated communication channel (i.e., notifications) where the system can proactively make suggestions to the user
Extensions, to allow the user to provide additional information about themself to the system automatically, via integrations with other software systems that already have information about them
End to end encryption

Additionally, I thought about different ways the system could be deployed, and tried to make sure the Core component does not depend on any specific one. For example:

The system could be deployed using any database or persistence framework
The system could be deployed using a traditional, separated client-server-database architecture, or it could run entirely on a single machine (e.g., a phone) with the option to have cloud backups. This would allow support for end-to-end encryption.
It could use any (or no) API framework or RPC framework
The user interface could use any communication medium, including a webpage, a mobile phone app, an Alexa skill, a chatbot, a doll that follows you around and talks to you, or a chip in your brain
It could be implemented in any programming language and run on any machine
In fact, it could be implemented as a protocol written in English and put in a binder for a person to follow. They could accept calls over the phone. The user facts storage implementation could be a filing cabinet, the suggestions catalogue could be a binder, the prediction model could be a person who gives an estimate based on their intuition, and notifications could be implemented by another person who calls the user on the phone.

I currently don't see limitations to this architecture, but I'm guessing some will arise as I flesh out the details of the interfaces. For example, what are all the fields in an "action a user took"? What is in a "catalogue entry"?

As a final part of this exercise (for now), I pared down the diagram to contain only interfaces I think are needed for a minimum viable product:

My next goal is to flesh out all the interfaces. What exactly are the fields in all the objects that are passed in and out of the methods and plugins?

As a next step towards this, I think it would be helpful to write out some examples of suggestions (activities and questions), actions a user took, and what the catalogue (set of information that helps us decide what activities a user might be interested in based on their history) might look like.

Pushing testing inward

Chloe — Fri, 16 Dec 2022 20:49:10 +0000

Recently I've been working on rewriting Dandelion to use Clean Architecture.

Right now, the architecture for the parts I've rewritten looks something like this:

There are a lot of arrows, and I'd like to simplify that, but the important part is that they all point inwards. Lower-level (farther out) components depend on higher-level (farther in) components. This is the Dependency Rule.

So far, during my rewrite, I've been testing things as I go using the GraphiQL UI. This has been helpful for making me confident things are working end-to-end, including GraphQL, MongoDB, Express, and Passport.

However, starting yesterday I'm trying to test using Jest tests instead. Right now I'm testing at the "Interface Adapters" area, meaning I'm testing everything inward of this circle. My tests are testing Enterprise Policy (Entities), Application rules (Interactors), and Interface Adapters (Controllers and Presenters.)

Doing this in addition to (if not instead of) GraphiQL testing has a couple advantages:

I'm forced to see where my Mongodb plugin has unneeded complexity

For the tests, I'm writing an in-memory "database" plugin and using that instead of the Mongodb plugin. To get the tests passing, the plugin needs to be able to achieve the same things the Mongodb plugin achieves.

They're both using an abstract plugin interface, which is a great start for separating database/persistence/storage code from enterprise/application code. However, as I write the new in-memory plugin, I've noticed that the Mongodb plugin does some things that aren't strictly necessary for persistence or performance, such as privacy checks.

There also are a lot of type-switching factories in my code. There are several different types of history events that can exist on an aid request -- it was created, someone commented, someone started working on it, the recipient name was changed, etc. Since history events can be represented in multiple different contexts, e.g., pre-commit, post-commit, application code, DB-specific code, there are multiple places where all of these different types of history events are implemented as several different classes implementing the same interface.

Maybe I will find a better solution to this eventually. However, the takeaway for this post is that the Mongodb plugin has a couple of different type-switch factories to convert subclasses of one interface into subclasses of another interface, and now I'm having to re-implement that in my in-memory DB plugin. Going through the process of writing a test plugin is making me see where there's an opportunity for code simplification.

I'm forced to revisit the interface between GraphQL and the controllers.

The test code I'm writing is similar to the GraphQL resolver code, in that it calls controllers and then examines the values in the presenters that are returned.

When writing tests, I like to make the interfaces between the test code and the application code as simple and clear as possible. I also like to keep logic out of the test code where possible.

I'm currently having to implement a lot of logic in test code and sometimes bypass the controller interfaces. This is showing me opportunities for improving these interfaces.

There's a clear path to improving the interfaces of the controllers: Do whatever makes the tests simpler.

It's easier to think about what use cases I want to support

There are a lot of new features I want to support in the app. However, it can be overwhelming to think about supporting them through all the parts of the codebase, including entities, interactors, controllers, Mongodb, GraphQL, UI design, and UI implementation.

Now, thinking of the tests as another "client" of the application, I don't have to support all those parts. I just have to support entities, interactors, and controllers. And mock plugins for the framework/DB adapters.

With this simplified scope, it's a lot easier to think through the interfaces and requirements for the next few things I want to do, such as:

Allow people to create their own accounts
Allow people to create their own sharing groups
Allow people to add other people to their sharing groups

And, as a final bonus (this is one of the main purposes of Clean Architecture), after implementing these new use cases with the tests as the client, I can be confident these inner rings of the architecture will still continue to work well even if I switch to a different database, API framework, or execution environment.

As I progress, I'd like to think about moving my tests even further inwards -- unit testing some of the modules within the Entities directly, and then move out to testing the Use Cases directly, without going through the controllers. This might allow me to develop new use cases and/or controllers more easily and confidently, since the interfaces of these inner layers will be cleaner, more complete, and better tested. However, it's also possible the level of overhead (in terms of code maintenance) required for this much testing will be excessive. We'll find out as we go!

What is Dandelion?

Chloe — Fri, 16 Dec 2022 00:34:46 +0000

I'm going to write a series of posts about a project I'm working on called Dandelion.

The purpose of this post is to give an overview of what Dandelion is so I can reference it as context in other posts.

Dandelion is:

A mobile web application for collaboratively helping people who need things.

Specifically, it was originally developed for a group of people (volunteers) who visit people who are living outside (residents) and offer help. Residents ask for things like batteries, tents, boots, propane stoves, etc.

When a resident tells a volunteer that they need something, the volunteer can record the request on Dandelion. Currently, in the code, we refer to this recorded request as an AidRequest. Volunteer can mark themselves as working on an aid request, mark it as complete, comment on it, tag other volunteers, and more. In a future post, I'll describe the features in more detail.

The app hasn't been used by actual volunteers since about October 2022, and I'm not actively promoting it for real-life use as of 12/15/22. In the future, when the app supports more features, this may change.

For now, I'm using the app as a pet software project to which I can apply new concepts that I learn.

Here's a non-exhaustive list of things I'm considering learning by applying them to Dandelion:

Clean Architecture
Different authentication methods, e.g., sign in with Google, email a magic link
Multi-Factor Authentication
Protection from DDOS
Protection from XSS
Serving static assets through a CDN
Using spritesheets
Adapting the app to be open to the public, rather than allowlist-only
Unit testing under Clean Architecture, using a test API
React testing
Using different kinds of databases (it currently only supports MongoDB)

I don't know if anyone is going to read this, but if you do, feel free to comment other things I could try learning with this project :)

In my next post, I'll describe the existing features of Dandelion and some features I want to add to it next. After that, I'll dive into my current project, which is refactoring the backend to use Clean Architecture.

All my posts will be on GitHub and my DEV page. The source code for this post is on GitHub here.

The source code for Dandelion is on GitHub here.

Demo Video: