A personal CRM needs to know how people are related to each other. Someone is your mother, your brother, your friend, your colleague or your partner. Monica has supported this for years, and from the user's perspective it's a pretty simple feature: you select a person, choose a relationship and you're done.

Unfortunately, designing what happens behind that little dropdown is not simple at all.

Even simple relationships aren't that simple

Let's say Monica is Ross's sister. From Monica's perspective, Ross is her brother. Both statements describe the same relationship, but the words we use depend on which person we're looking at.

The same thing happens everywhere in a family. Rachel is Emma's mother, while Emma is Rachel's daughter. Someone's aunt has a niece or nephew. A grandmother has a granddaughter or grandson.

Other relationships don't work like this. Chandler and Joey are friends. The word is the same regardless of which side you're looking at. Cousins and colleagues can work the same way.

So already we have different behaviours. Sometimes a relationship changes its name depending on which side we're looking at, sometimes it doesn't, and sometimes the word we use depends on the gender of one of the people.

And this is the easy part.

Families are messy

Imagine two people get married and have two children. They divorce. One of them remarries someone who already has children from another relationship, and perhaps they have another child together.

This is not a particularly unusual family, but we now have parents, children, siblings, half-siblings, stepchildren, stepparents, spouses and former spouses.

It also starts raising questions for which I don't think there is always a universal answer. If you get divorced, does your mother-in-law stop being your mother-in-law? Technically, perhaps. But what if you've known her for twenty years and still consider her part of your family? She certainly doesn't stop being the grandmother of your children just because your marriage ended.

Then there are biological parents, adoptive parents, foster parents and guardians. Someone may have several people they consider parents, and those relationships don't necessarily mean the same thing. There are estranged family members, people who consider someone a brother or sister despite having no biological relationship, former partners who remain very close, and parents raising children together who are no longer a couple.

The clean family tree we tend to imagine when thinking about this problem doesn't survive contact with many actual families.

And even when the family structure itself is straightforward, relationships change. Someone who is your partner today may be your ex-partner in five years. That doesn't mean the old relationship should simply disappear. The fact that two people were married for fifteen years remains part of their history even if they're no longer married.

Relationships have a past, which makes representing only their current state problematic as well.

Two people may not agree on their relationship

Family relationships give us at least some facts to work with. Friendship is even less precise.

If Monica considers Rachel a close friend, does Rachel necessarily consider Monica a close friend? We have no idea.

The same problem exists with mentors, acquaintances and plenty of other relationships. Someone might consider another person their mentor even if that person would never use the word themselves. Someone may consider an old friend practically family while the other person sees them as someone they knew years ago.

This matters a lot in Monica because the information isn't meant to describe some objective social graph. It's your information about the people in your life.

When you write that someone is your friend, you're describing the relationship as you understand it. Monica doesn't have the other person's version of the story, and in many cases there probably isn't a single correct answer anyway.

This gets particularly strange when software tries to turn relationships into something measurable. Is someone a better friend because you see them every week? Is a friend you haven't seen in five years less important than a colleague you talk to every day? Obviously, frequency tells us something about a relationship, but it doesn't tell us what that relationship means to someone.

Time doesn't fit nicely either

A colleague can become a friend. A friend can become a partner. A partner can become an ex-partner, and years later the same person might become a friend again.

If Monica records that two people are married and they later divorce, what should happen to the marriage? Removing it would make the current information correct, but would also remove something fairly important about their history.

We could keep dates, except that people often don't know them. I might know that two friends used to be together without having any idea when they started dating or exactly when they separated. Requiring precise dates would make the model cleaner while making the product considerably more annoying to use.

There is also no guarantee that relationships change neatly from one state into another. People don't necessarily wake up one morning and change from "friend" to "partner". Some relationships have a clear beginning, such as a marriage. Many others don't.

The database would very much like us to know when everything started and ended. Most of the time, we don't.

English isn't the model for the entire world

Another problem is that most of the first examples that come to mind are based on English.

English uses "cousin" for a large number of family relationships, but other languages can be much more precise. Mandarin Chinese, for instance, has different words for cousins depending on which side of the family they come from, their gender and sometimes their age. Swedish distinguishes all four grandparents: mormor is your mother's mother, morfar your mother's father, farmor your father's mother and farfar your father's father. English simply gives us "grandmother" and "grandfather."

Korean provides another example. Even something as simple as "older brother" changes depending on who is speaking. A man calls his older brother hyeong, while a woman calls her older brother oppa. The relationship vocabulary contains information that isn't present in the English word "brother."

This matters for Monica because it is translated into many languages and used around the world. We can't design the entire relationship system around the assumption that English contains the canonical list of relationships and that every other language simply needs to translate those words.

This is a problem we've already encountered in Monica, and rebuilding it doesn't magically make it disappear.

Family isn't even the hardest part

At least family relationships tend to have names. The rest of our relationships are much less structured.

"Friend" can describe someone you've known for thirty years and talk to every week, but it can also describe someone you see twice a year and still care about very much. A colleague can be the person sitting next to you every day or someone you worked with fifteen years ago.

And people don't fit into one category at a time. Someone can be your colleague, friend and former roommate. Your business partner can also be your brother. Your neighbour can be the parent of your daughter's best friend.

Sometimes the context itself is what matters. You know someone because you went to school together, played on the same team, lived in the same building or worked on the same project. "Friend" might be technically correct, but it loses the information that explains why this person is part of your life in the first place.

This is where a simple question like "how do you know this person?" starts becoming surprisingly difficult to answer with a single field.

One relationship can imply many others

Suppose Ross is Monica's brother and Ross has a son named Ben. We immediately understand that Monica is Ben's aunt.

Software can reach the same conclusion. And once it starts doing that, it can keep going.

Parents imply children. Children with the same parents may be siblings. Siblings with children create aunts, uncles, nieces and nephews. Add another generation and you have grandparents and grandchildren. Pretty quickly, a small number of relationships can produce a much larger family graph.

But the fact that software can infer something doesn't necessarily mean it should.

A parent's new spouse isn't automatically a child's parent. Two people who share a parent may technically be half-siblings, but perhaps they don't know each other. The information Monica has may also simply be incomplete. And even if the family relationship is technically correct, it may not be the relationship the people involved would use to describe each other.

Every time the software infers another relationship, it also gets another opportunity to be wrong.

There are more questions than answers

The more we work on this, the more edge cases we find.

Should Monica remember the history of a relationship or only its current state? Can two people have several relationships at the same time? Is "best friend" a different relationship from "friend", or is that something else? What happens when we know someone's mother but don't have their mother as a contact in Monica? How do we describe relationships that matter to us but don't have a convenient name?

Some of these are database problems. Most aren't.

The difficult part is deciding what we mean when we say two people have a relationship, because humans don't use that word with anything close to the precision a database would prefer.

From the interface, all of this may eventually amount to a few words on someone's profile: mother, brother, friend, colleague.

Getting those few words right is one of the hardest problems we're dealing with while rebuilding Monica.

While working on Monica v3, I found myself spending a lot of time looking directly at the database. This is not particularly unusual when building a Laravel application. You create a contact and check what was written. You create a relationship and inspect the related rows. You change a reminder and verify the dates. You run an action, refresh the data, follow a foreign key, and repeat the process many times during the day.

There are already many good ways to do this. Tinker is useful but not simple and quick to use. Applications like TablePlus, DBeaver, phpMyAdmin or Adminer can be super useful, but not for a quick lookup. I use TablePlus regularly, especially when I need to write queries, edit data or inspect the schema in detail. But most of the time, while developing Monica, I did not need a database management tool. I only wanted a quick way to see what was in the database without leaving the application I was already working in.

That was the initial idea behind LaraDB. Install a development dependency, visit /db, and see the database.

composer require --dev monicahq/laradb

What you get is super simple. Tables are displayed on the left, rows on the right, and the page runs inside the Laravel application itself. LaraDB supports SQLite, MySQL and MariaDB, and PostgreSQL.

A browser rather than a database manager

The most important decision we made was to keep LaraDB read-only. It does not have an edit button, a delete button, an insert form or a SQL console. Both routes exposed by the package are GET routes, and the package only issues SELECT statements.

This is partly a safety decision, but it is mostly about scope. There are already mature tools for managing databases, and reproducing a subset of their features inside Laravel would not make LaraDB more useful for the problem we were trying to solve.

The package also avoids accepting arbitrary identifiers or queries from the browser. A requested table must first exist in the schema discovered by the driver. Identifiers are quoted according to the database engine. Values used when following foreign keys are bound as parameters. There is no interface for submitting arbitrary SQL because arbitrary SQL is not part of the package's purpose.

A small tool can remain understandable if it has a very precise job. LaraDB is intended to answer what is currently in the database and how those rows relate to one another. It is not intended to become a replacement for a proper database client.

What we ended up needing

The interface reflects that narrow scope. LaraDB lists the tables in the current schema and displays their rows in a dense table. Column types are shown, primary and foreign keys are identified, NULL values are visually distinct from empty strings, and long values are truncated so that large text or JSON columns do not make the page unusable.

Foreign keys turned out to be one of the more useful features for Monica. If a column references another table, its value can be followed directly. Clicking it opens the referenced table filtered to the corresponding row. This is especially useful in Monica v3 because a growing number of domains are represented through explicit relationships between several tables rather than through large, self-contained records.

The page also exposes some context about the current database and query. Depending on what the database engine makes available, LaraDB can display the engine and version, database name, size, index count and other engine-specific metadata. For the current page, it also shows the SQL statement that produced the result and how long the query took.

There is also a JSON representation of a table. This was inexpensive to add once the database layer was separated from the HTML rendering and has proved useful when inspecting data outside the page itself.

The frontend is intentionally self-contained. The package ships its own CSS and JavaScript and does not depend on the host application's asset pipeline. Installing LaraDB should not require adding Tailwind configuration, an Alpine dependency or another build step to an existing project.

The database abstraction became the real work

Displaying rows in a browser is straightforward. Supporting SQLite, MySQL and PostgreSQL consistently is where most of the interesting work ended up happening.

The engines differ significantly in the way they expose schema and database metadata. Listing tables, describing columns, finding primary keys, resolving foreign keys, counting rows and retrieving database-level information all require different queries depending on the engine. Even details such as identifier quoting need to be handled correctly rather than treated as a generic SQL operation.

LaraDB hides these differences behind a small driver interface. The Laravel layer asks for tables, columns, rows and metadata without needing to know whether the underlying connection is SQLite, MySQL or PostgreSQL.

A simplified part of the contract looks like this:

public function listTables(): array;

public function getColumns(string $table): array;

public function getRowCount(
    string $table,
    ?RowFilter $filter = null,
): int;

public function getRows(
    string $table,
    int $page,
    int $perPage,
    ?RowFilter $filter = null,
): TablePage;

public function getForeignKeys(string $table): array;

Each database driver implements those operations differently, while the rest of LaraDB works with the common result objects returned by the interface.

An interesting consequence of this design is that the core database-reading code does not depend on Laravel at all. It works directly with PDO. Laravel is responsible for package discovery, configuration, routing and rendering, but the actual database inspection can be used separately.

use LaraDb\DriverFactory;

$pdo = new PDO('sqlite:database.sqlite');
$driver = DriverFactory::fromPdo($pdo);

foreach ($driver->listTables() as $table) {
    echo $table->name;
}

Read-only is not the same as harmless

The package being read-only prevents it from corrupting the database, but it does not make exposing the database harmless. A database browser can reveal every row in every table to anyone who is able to reach it, which is obviously a serious concern for an application such as Monica.

For that reason, LaraDB is designed to be installed as a development dependency.

composer require --dev monicahq/laradb

A normal production deployment using composer install --no-dev will not contain the package. LaraDB is also disabled outside the local environment by default, and its routes use the web and auth middleware by default when they are enabled.

Small things that come out of a larger rebuild

When I started the Building Monica series, I expected most of the writing to focus on the large architectural and product decisions behind Monica v3. That will still be the case. But I also want to document some of the smaller tools and ideas that come out of the rebuild, because they are part of the work too.

LaraDB is not a major part of Monica v3, and it is not trying to become a major product by itself. It is simply a small development tool that removed a recurring annoyance for us. The package is useful precisely because its scope is limited, and I would like to keep it that way.

If you work on Laravel applications and often open a database client only to inspect what your code just wrote, LaraDB may be useful to you as well.

composer require --dev monicahq/laradb

Then visit /db.

The source code is available at github.com/monicahq/laradb.

Almost ten years ago, I started building Monica because I was terrible at remembering things about people. I would forget the name of someone's child, what we had talked about the last time we met, or something important they had told me a few months earlier. I wanted a place where I could write these things down, mostly to compensate for my bad memory, so I started using a professional CRM.

It wasn't a great solution. The software was made for salespeople, which I wasn't, and I didn't particularly want to pay for a tool designed to help me make money when all I wanted was to remember things about my friends and family. I looked for something more appropriate and couldn't find it, so I decided to build my own.

That small project eventually became Monica. I put the code on GitHub, posted it on Hacker News, and things went a little crazy from there. It turned out that I wasn't the only person looking for something like this. Alexis eventually joined me as a co-founder, and over the years thousands of people have used Monica, contributed code, translated it, reported bugs and installed it on their own servers. The project now has more than 25,000 stars on GitHub and has become one of the most well-known open source personal CRMs.

I'm very proud of what Monica has become. But after working on it for so long, I've reached a point where the current version is no longer the personal CRM I would build today.

Almost ten years of decisions

When I started Monica, I obviously didn't have ten years of experience thinking about how to represent personal relationships in software. Most decisions were made when a problem appeared. We needed contacts, so I built contacts. We needed relationships, so I added relationships. Then came reminders, activities, gifts, notes, pets, addresses and many other features.

There is nothing particularly wrong with building software this way. It's how Monica grew, and many of those decisions made sense at the time. But after almost ten years, they accumulate. New ideas have to work around decisions made years earlier, and things that once looked like implementation details slowly become constraints on what you can do with the product.

Over time, this has made some parts of Monica harder to change than they should be. More importantly, I've changed my mind about some of the original decisions.

What would I build today?

At some point, I started asking myself a simple question: if Monica didn't exist, and I had to build a personal CRM today with everything I've learned over the last decade, what would it look like?

This quickly led to questions that were much more basic than which features Monica should have. What exactly is a person in Monica? How should relationships between people work? How should Monica represent the user themselves? What happens when something important in someone's life isn't another person, but an animal, an organization or something else entirely? How should reminders work when human relationships don't naturally follow schedules? What should an activity represent? And how much of this should Monica define for you in the first place?

Relationships are a good example. Storing that Monica is Ross's sister doesn't seem particularly complicated. But if Monica is Ross's sister, Ross is also Monica's brother. A parent relationship implies a child relationship. Some relationships have a direction while others don't. Real families include divorces, remarriages, stepchildren, half-siblings, adoption and all sorts of structures that don't fit nicely into a predefined list. Different cultures also describe family relationships differently.

I've spent a lot of time thinking about this for the new version, and I now see relationships as their own domain rather than an attribute attached to a contact. It seems obvious to me now. It wasn't obvious when we designed the first versions of Monica.

Customization is another area where I've changed my mind. Historically, Monica has mostly defined what a contact is and what information can be stored about one, and we've added customization around that structure. For v3, we want to reverse this. Monica will still provide good defaults, because nobody wants to configure fifty things before adding their first contact, but your life shouldn't have to fit the database schema we decided was right for everyone.

Once you start changing things at that level, redesigning a few screens isn't enough. The foundations need to change too.

What I want v3 to be

Monica v3 isn't meant to be the current product with a nicer interface. The interface will change considerably, and I want it to feel much more playful and personal than most of the software we use today, but that's only part of the work.

I want to build a very powerful system for documenting the people and relationships in someone's life. I'm not especially interested in optimizing everything for simplicity if the result is a product that can only represent simple lives. I'd rather have good defaults for people who don't want to configure anything, while giving those who do an enormous amount of control over how their Monica works.

This means treating relationships as first-class concepts and letting people decide what information matters to them. Monica needs to handle much more than a predefined list of fields attached to a contact. The difficult part will be doing all of this without ending up with enterprise software for managing your friends and family, because that would be pretty awful.

There are also things I don't want to change. Privacy and data ownership still matter enormously to Monica. The project will continue to be open source and self-hostable. If you're going to spend years putting some of the most personal information in your life into a piece of software, I think you should have as much control over that information as possible.

I also don't want Monica to decide how important someone is to you. It can help you remember things, organize information and tell you that you haven't spoken to someone in a while. The relationship itself is still yours to maintain.

Starting again with ten years of experience

"Starting again" isn't entirely accurate, of course. When I created Monica in 2017, I had an idea and a problem I wanted to solve. This time we have almost ten years of experience working on that problem, thousands of conversations with users, contributions from people around the world, two generations of the product and a fairly long list of things we wouldn't do the same way again.

As we work on v3, I want to document more of this publicly. There are a surprising number of difficult problems behind something that looks fairly simple from the outside, especially when you start thinking seriously about relationships, reminders, customization and how to represent something as messy as a human life in a database. I'll write about those problems, but also about the technical and design decisions we're making and the things we try that don't end up working.

That's what Building Monica will be about. I don't know how often I'll publish an article, and I don't want to invent a publishing schedule just for the sake of having one. I'll write when we have something interesting to talk about.

In 2017, I built Monica based on what I understood about the problem at the time. Almost ten years later, I understand that problem very differently. That's why we're rebuilding it.

Alexis and I have been thinking about a new version for a very long time. Longer than we initially expected, obviously. Rebuilding an application from scratch while having full-time jobs, families and lives outside of Monica turns out to take a bit of time. Who knew?

But today, we can finally say this: we will launch the new version of Monica before the end of 2026.

This new version is the Monica we've wanted to build for years. It will be faster, more flexible, easier to use and built on a much stronger foundation.

Monica will still help you remember the people who matter to you. It will still be private. It will still be open source. And you will still be able to install it on your own server for free.

We're incredibly excited. Monica has been part of our lives for almost ten years now, and this feels like the beginning of a completely new chapter for the project.

There is a lot of work to do.

But it's coming. For real this time.

Thank you for your patience, your messages and your support over all these years. We can't wait to show you what we've built.

Monica was born 7 years ago with the goal of being a personal CRM. This new version is about documenting your life, including what your contacts are doing, but not only.

What does beta mean? It's like having a bunch of mischievous little bugs hiding in our software, playing hide-and-seek with us. We're pretty sure they're there, but we have no idea which ones or where they're hiding! So, we need all the brave souls out there to join our bug-hunting squad and help us flush them out before we release it to the public.

Chandler is a complete reimagining of Monica, built from the ground up. We eliminated the extensive technical debt we had accrued over the years and added or improved many new features. Despite the fact that we did not promote Chandler, we’ve had a lot of users who tested Chandler already and found some bugs that we’ve fixed, but we haven’t tested this software at scale. So please, create an account, and have fun.

The version available on the beta server can be considered stable. We will not reset the database. We’ll backup your data daily, and we will keep the data once we’ll launch the final version officially.

Chandler comes with some limitations:

• You can’t use your current Monica login,
• You can’t import your data,
• There is no mass import of contacts available,
• We don’t have an API yet.

We have plenty of new features, a new layout, and the highly requested dark mode.

On a personal note, the feature I’m most proud of is the ability to customize almost everything in Chandler: from the layout, to the modules you can enable, to the data you can enter about your life.

Chandler is still open source and can be installed on your server for free, if you know how to use Docker or the command line. You can still modify the code if you so desire. Monica is, and always will be, open source. This is the way.

For now, Monica is free on our hosted instance (https://beta.monicahq.com), but we will have the same pricing as the current version as soon as we consider the product stable.

I'm incredibly proud of what we've achieved in the past eight years. Back then, I was scared to make my code public because I knew it was of poor quality. Surprisingly, people didn't seem to care. Now, our codebase is still open to the public, and we're no longer concerned about people judging it. The app is still a Laravel application, with VueJS on the front end, using InertiaJS between the front and the back. It’s a super simple stack. We strive to keep our codebase as simple as possible to facilitate maintenance, evolution, and finding developers to assist us.

We will soon migrate our official Docker image to Chandler. We have had over 25 million downloads of the image, which makes us humble.

On behalf of the entire Monica team, thanks for sticking with us all this time. The « entire Monica team » is basically two friends, Alexis and I, who are really passionate about providing cool tools for people to improve their lives. Monica is still a side project for us, we have full time jobs « on the side ». While some people play computer games or watch Netflix, we « play » in Monica’s codebase. And we love it.

I’m super tempted to call it a “faster, newer, better version”, because it is, but I’m not good at marketing, so I’ll just say that it’s a new version and I’ll answer the questions you might have below.

What do we mean by new version?

A complete rewrite, from scratch, of Monica.

Are you insane?

Yes, but also, Monica is an old code base now. Old in the sense that it’s 7 years old and it has been touched by hundred of contributors. There are some concepts in the code that we let through, because we either didn’t know any better back then or because we didn’t want to piss off contributors, that we don’t want anymore. The project has way too many dependencies, and maintaining the code has become harder than it was before. Changing something is riskier, and takes more time. Also, we’ve seen how people use Monica, what they want to do with it, and the current code limits us way too much if we want to support what people want to use Monica for. Finally, Monica is still a side project for us. We are extremely passionate about it, and we want to also have fun building it. And the current version wasn’t that fun.

What do you mean by rewrite?

We mean that we’ve started from an empty code base, and we started from there. Previously, it was a Laravel app (so, PHP), with Blade views and some Vue here and there. Now, it’s still a Laravel app (so, still PHP), with Vue 3 entirely. We’ve simplified a lot of stuff, we’ve made some stuff more flexible and therefore a bit more complex, but we believe we can support the future of Monica with it.

This also means we have a brand new data structure, supported by a new database schema.

Will the new version be called Monica?

Right now, the new Monica's code name is Chandler. We won’t keep this name though–the official name of the new Monica will be Monica. For the sake of clarity, we'll call the new version Chandler throughout the rest of the article.

You choose PHP despite \?

PHP is a great language. It’s not the PHP 4 or 5 era anymore. Also, it’s a very simple language –this means that there are a lot of people in the world that read and understand PHP. Choosing PHP means it’s easier to contribute to the project, easier to debug, easier to maintain and easier for us to find people to help us, if needs arise in the future. Finally, the PHP ecosystem is just great, with Laravel paving the way for one of the best Developer Experience I know.

What features will Chandler contain?

At launch, we want to match 100% (or almost) the feature set that Monica v1 offers. Even if we match features, we wanted to either simplify them (tasks for instance), or make them more robust (reminders, for example).

Once this is done, we have so many ideas for what Monica should become that it’s overwhelming. Basically, Monica was born as the first personal CRM (or PRM–personal relationship manager) out there. So we branded it that way. But after years of working on it and talking to people and reading the thousands of emails you’ve sent us, we realized that Monica really is a way to document your life, whatever that means for you. So, Monica will be about documenting your life, and giving you tools to help you document it the way you want it.

We read everywhere that products should be opinionated, and have a strong personality so people use your tools the way you want them to use it. This was the direction of v1. Now we want to change that statement. We want people to use and configure Monica the way they want. Who are we to tell you that you should use only 3 pronouns for your contacts, or tell you which relationship types you should have? Chandler will be completely customizable, from what you see in the UI, to the type of data you can enter. Marketing people would say "Chandler is all about you” and it’s true, in a sense. The drawback: from a technical point of view, it’s harder to manage, but this one is on us.

When will it be ready? Can I try it?

It’ll be ready when it’s ready. Remember, we don’t work full time on this, at all. Alexis and I have both demanding day jobs, and we have families, and friends, and Monica (and OfficeLife, as well).

HOWEVER.

We have done a lot already. Some big features that you know and love are still missing from the new version: life events, activities, gifts and CalDav/CardDav, to name a few. Life events, in particular, is really big because we want to completely rethink the concept and make it really useful. Also, and this is a huge “also”, right now, we don’t have an API yet. Since this is a new code base, we can’t simply copy and paste your existing v1 contacts and expect them to show in v2. So, if we were to release something now, you couldn’t import your data. And we think this is a problem.

THAT BEING SAID.

We still need testers to help us find bugs, even though we don’t do bugs here (lol). We need people to help fix docs spelling errors. So what we could do, is launch Chandler in a very alpha state, free for all until it’s not alpha anymore.

Is it still open source? Can I use it for free?

Yes, it’s still open source, with the same license as before. That means Monica is free, of course, unless you use the version that we host, that eventually will cost something, like the current version. Yes, you can install it wherever you like, on your own server. Since Chandler is not the same code base, we haven’t the same rich ecosystem that we had before and all those many different ways to install it everywhere, but we’ll get there. Yes, you can still contribute to the code, fix bugs, add features – even though we still have the right to refuse your pull requests if we think we don’t want to support what you want us to support.

What is the future of Monica v1?

We’ll support v1 until Chandler is out of alpha/beta. Then, it’ll be deprecated but people who have hosted it will be able to continue use it if they want. The v1 version we host ourselves will not be supported after this.

Can you contribute to the code base already?

The repository is already available on Github, but we are far from being as mature as the current main repo. That means we are not yet ready to support contributions from everyone, as things change almost every day, but if you accept this, go ahead.

What's next?

First of all, thank you so much for having read this blog post entirely. We are super grateful for our community, how you are still passionate about this little tool that we have fun building. Alexis and I are still super motivated about this tool, and we thank you for caring with us. We'll keep in touch.

There is another reason why we want to change our current approach. Monica is first and foremost an open-source product. We have a huge community. Many of you host Monica on your servers. Because we also host the product ourselves so we can monetize it, we currently have included all the code required to manage subscriptions in the main codebase. That’s a lot of code. We deal with subscribing, editing, and deleting a subscription, with all the permissions around it, and so on. It’s not ideal.

We’ve decided to remove all the billing code from the main codebase, and create a new portal, called the Subscription portal, to manage your Monica subscriptions. You will have to create an account on this website and purchase a license key that you will need to paste into your Monica account. Nothing else is required.

If you currently have a subscription, we’ll allow you to easily transition your account to the new one. Further instructions will follow by email for each one of you.

We plan to transition to this new customer portal in the upcoming weeks.

Like everything we do at Monica, our customer portal is completely open-source and the code is available on Github. And once the customer portal will be live, the main Monica codebase will be completely free of the notion of billing.

Version 2.16 contains 226 changes, most of them being bug fixes or improvements on the codebase. But we also have a bunch of new features, explained below.

New way of adding activities

You can now add activities inline, instead of going to a new page to do so. Like the Call feature, you can now indicate the emotions you felt during an activity.

Enhance API settings page

Most of what you can do with Monica can be achieved through the API. It is extremely important for us to let people manipulate their data at will. This is why it was time to enhance the API settings page a little bit, by giving it more love.

Also, we've added many new API methods to continue our openness to other systems.

Lots of changes under the hood

We've also completely changed how data is stored by adding foreign keys to every table in the database. While this will have no impact on the end-user experience, it’s pretty major for us developers as it will allow us more control and flexibility overall. This was a huge change for us and the pull requests took almost 11 months to get merged.

We've also completely changed how the export process of data is handled and it should work flawlessly from now on (or as they say: 60% of the time, it works every time).

What happened in 2019?

In 2019, we kind of slowed down a little bit in terms of annual releases. Also, the activity on this blog has been nonexistant. However, this didn't affect the number of signups, or the number of downloads, or the love of people on the Internet for this project.

Basically, Monica has never been stronger. We have nearly 5 million downloads of our official docker image. We have tens of thousands of users on our hosted version. Monica keeps popping on Hacker News and our issue tracker on GitHub is as active as ever. Also, we've merged 875 pull requests in 2019.

So why this silence? This is mainly because of me (Regis). I've started Monica almost four years ago now. Having a popular project is a lot of fun, but it also takes a lot of energy and motivation. Especially since Monica is still a side project for both me and Alexis. But this year, Monica was too much for me to handle, and I’m usually the one writing on this blog, or on social media. I had a side-project burnout, if you will. Alexis has taken a lot of work on his shoulders to maintain and evolve the product, but I couldn't work on it as much as before, and I couldn't post any news about the project. I had to do something else, clear my head and come back only when I'd be ready. Now I am, and I’m more than motivated to get back to work and have fun again.

Monica in 2020

Four years ago, Monica was one of the first popular personal CRMs. Fast forward to today, and the competition is now bigger than ever (a dozen, last time I checked). But I do believe that we have an advantage that can not be overtaken by our competitors: we are open source, and we have no charges, no costs or almost, and we are not greedy. Everything we do, we do it for the community first. The more Monica instances there are out there, the happier we are: this means we don't have any control over our users' data.

In 2020:

• We want to continue our work of openness and transparency. That means more ways to export or import data in a standard format.
• We want to provide webhooks so external systems can be aware when data changes in your account (if you so desire, of course).
• I believe Monica is currently the best tool out there to document your personal contacts. You can log anything, really. Now that we have a very strong foundation, I believe it’s time for us to expand on that. It’s time we let you do something more with your contacts, by creating groups (or families), events, opportunities, etc... We will focus on simple concepts that will be gradually added to the platform, that will provide the most flexibility for you.

Monica is a tool for you. Please keep sharing ideas, keep sending me emails about what we should do next. We are here for you.

Also, happy new year 😀

Photo upload

You can now upload photos on a contact’s profile page. The number of photos you can store depends on your account’s storage limit, which is 512 Mb on https://monicahq.com (and is configurable per instance). The ability to upload photos unlocks a lot of possibilities in the future.

Recovery codes

Security is so important, especially in a tool like Monica which stores many intimate details. Monica already supports two-factor authentication (also known as 2FA) and U2F to help you secure your account. Starting with Monica 2.11, you can now generate recovery codes to unlock your account in the case you’ve lost the ability to login with 2FA. Beware though - as those codes can help access your account, make sure you keep them in a very secure place.

Phone calls

Phone calls have had a lot of love in this release. First of all, we’ve redesigned the flow to record them. Then we’ve (finally) added the possibility to edit a phone call that was made in the past. And as a bonus, you can now indicate who initiated the call.

Emotions

Wouldn’t it be awesome to be able to tell how you felt when something happened, in a very precise manner? Monica 2.11 introduces the notion of emotions, based on the work of Dr. Phillip Shaver. In his work, emotions are sorted into 3 main categories:

• Primary emotions (love, joy, surprise, anger, sadness, and fear),
• Secondary emotions (Love -> Affection, Lust, Longing),
• Tertiary emotions (Love -> Affection -> Adoration, Love, Fondness, Attraction).

We’ve added those concepts in Monica, starting with phone calls. There is a new drop-down menu that lets you choose as many emotions you want, in order to represent very precisely what you felt during a call. We plan to add emotions to other key elements as well, like activities.

Weather

When you are talking with a friend that lives in another area than you, chances are you will eventually talk about the weather. Monica will help you here, by showing the current weather of the place your friend lives in. This information comes from the first address found on the contact profile page. That also means that if no address is currently set, no weather information will be shown.

Weather data is pulled from Darksky and is refreshed every 6 hours. The only information that is shared with Darksky is the latitude/longitude, and nothing else. For instance owners, Darksky has a free plan that lets you make 1,000 calls per day for free, which should be plenty enough.

GPS coordinates

Speaking of latitude and longitude, we had to find a mechanism to get those two pieces of information for each address entered in Monica if we wanted to display the weather data. Monica 2.11 now has the ability to automatically geocode any address to find their latitude and longitude coordinates.

When you enter an address, and if the service is configured at your instance level, we’ll automatically try to geocode it - unless you provide the latitude/longitude for a given place yourself.

Geocoding is done by LocationIQ, a great and independent company that offers a very generous free plan of 10,000 calls per day for free. We don’t share any information with LocationIQ other than the address in order to fetch coordinates.

Tasks

On your dashboard, you can now add tasks that are not linked to any contacts.

Enhancements

We refactored a lot of how things are written internally. This is to continue our quest of having the most stable platform possible. Also, we've continued to increase the code coverage (i.e. the fact that our code is actually tested automatically). We are now at 66% code coverage for the entire codebase.

We hope you will like 2.11 as much as we do.

While Theo has done an amazing job on the first version of those apps, the development has stopped at the beginning of this summer while the development of Monica, the platform, has moved forward. We are now in a situation where the mobile app is not on par with the platform and worse, we will break things in the API that the mobile app won't support.

I still strongly believe that the growth and adoption of Monica will be through a mobile app.

I would like to promise wonderful things and announce that you'll have a new app in 2 months - but in reality, I don't know how much time it will take. Since Monica is still at the side project stage, it might take 6 months, or 2 years. But one day we'll have a great mobile application, as good as the web version (if not better).

Thanks for your patience.

Tag autocompletion

Tags are a great way to categorize people. With 2.10.0, finally, we support tag autocompletion. Go to a contact and edit the tags in the header - as you type, a menu will appear showing your tags. A small change for Monica - a big help for users. A technical note: this feature has been entirely developed with VueJS, without other dependancy. We are moving away from JQuery and over the course of the next months, we'll sunset JQuery entirely.

New header

Speaking of the header, as we were changing how tags work, we've taken this opportunity to redesign the header of a contact profile. This will let us add much more useful information in the future. It's also easier to read.

Documents

You can now attach documents to a contact. There is a configurable limit per instance on how much storage an account can use. On our hosted version, the limit is 512Mb per paid account (storage is cheap - but not when you host ten of thousands of accounts).

There is also a new tab in your Settings page called Storage that shows your current account usage and your account limit.

Archive a contact

Sometimes you want to add a contact but not have him appear on the contact list. Archiving a contact lets you do that. You can access this feature from the bottom left of the contact profile.

Other improvements

• We've fixed a lot of bugs.
• We've improved how we support S3 to store assets (images, documents,...)
• We've dramatically increased our test coverage. 6 months ago we were at 25% test coverage. With our continuous effort of increasing them, we are now at 65%. This gives us much more confidence that we don't break things as we move forward.
• We now automatically set the currency and the timezone for new users, based on their location.
• We've rewritten how we import/export vCard.
• We also now parse FN properties correctly when we import vCards.

Have fun with version 2.10!

Life events is now a new tab in the Profile page of a contact.

You have access to 45+ life events that you can document. You can also set a reminder for each one of these events.

Note that you can add an event without knowing the month or the day it happened.

Once a life event is added, it will appear on a timeline that will be improved in an upcoming release.

I hope you will like this feature and have fun with it.

With our latest update, you can now log a conversation that you have had with someone on social media, by SMS or using Telegram, for instance. The interface we've chosen for this mimics the user interface used by popular chatting tools.

When you log a conversation, you can indicate the mean of communication you've had this conversation with. This list of means is pulled from the contact field types defined in your Settings page.

We hope that you will make good use of this new feature.

Here are some of the most important changes:

• Remove automatic birthday reminder creation when editing a contact: this was something that irritated a lot of users. From now on, when you add/edit a contact and specify a birthdate, we don't automatically create a reminder for this event.
• Debts across all your contacts are now showed on the dashboard.
• We've added GDPR compliance. This is a new European law that forces us to confirm your email address on signup. I wanted to avoid it, but we don't have the choice legally.
• We've improved the import of contacts through CSV. The process should work better now.
• We've added a new kind of relationship between contact: ex-wife/husband.
• There is a new filter in the contact list that lets you see contacts who are not associated with a tag.
• We finally support nicknames for your contacts! You can also choose how you want to display the names in your account.
• Add Yubikey support - this is another security feature for those who want an extra layer of protection.

On another note, it's been more than a year now that Monica has been launched on Hacker News. The growth has been pretty incredible, especially regarding the community on GitHub. We have now more than 110 contributors who help build Monica, which is awesome. That being said, there is a drawback to this: we've been shipping new features a lot, and because of this pace, we haven't been careful enough in the last months. Monica is not as stable as it should be. Nothing dramatic or critical, but the last two releases have seen some stupid bugs that we could have prevented, and we will put measures in place to increase the chances that this doesn't happen again. It's especially important to ship bug free releases as Monica is still a side project, and the worst that can happen is noticing something is very wrong on the platform while you are at work, and having to wait to find the time to actually fix and deploy to production (usually when we come back home and have to deal with kids etc...). On a daily basis, trust me, it's the kind of worries you don't want to have.

All this to say that we will try to focus on quality in general.

Please continue to send your feedback via email or through an issue on GitHub. We read every message and your opinion is important to us (really).

I understand why. A mobile app for Monica makes so much sense. You want to have the information immediately available wherever you are, at the right moment. Not when you are at home in front of your desktop.

We started working on the mobile application 6 months ago. It’s a long time. However, I don't think most people realize the work that needs to be done to ship a mobile application. Especially when 99.9% of the code is made by one person (the awesome @mokto). Who has a daily job. Who is not paid to work on it.

In those months, we've put a lot of efforts to create all the things the mobile application would need. The API has changed a lot to allow some features. We've stabilized the backend to make sure it will work flawlessly. We've also spent a lot of time setting up everything the right way on the mobile app repository on GitHub, that will allow us to move faster in the future (here we are talking about a great CI, unit tests, auto publishing in the stores,...).

And six months later we are proud to announce that the first version of the mobile application is available on iOS and Android.

There is one caveat though: this first version is read-only. That means you can't add or edit something. We want to have a great application, but we want to move slowly and make sure it's working well. As soon as we are confident this version works for everyone, we'll add features that will let you completely manipulate your data as you want (hint: we’ve already started working on a new version).

Apart from this, this mobile app has everything you come to expect from us:

• A simple and friendly user interface.
• You can connect to our hosted version of Monica, or login to your own instance.
• The code is open source. You can read the code, submit issues, contribute to the code. Everything we do is open and transparent, and we believe that only collaboration can lead to the best product.
• Open source means you can build and run the mobile application without having to go through the official Apple and Google stores - which is kind of amazing, in my opinion.
• We don't display ads, we don't resell your data.
• We don't have any tracking whatsoever in our code.
• The app is free. No strings attached.

How can you help?

We need people who want to test the application and tell us if there are bugs, basically. Also, we'd like your opinion on what we should build next, or how we could make the app better (in terms of user experience or in terms of layout).

What's next?

In the coming days we'll improve the documentation on the official GitHub repository, in order to make it super easy for developers who want to help to join the project.

In the coming months we'll add the possibility to modify your data within the mobile application. The end goal is that everything you can do on the web, you can do on mobile (with the exception of exporting your data, because how would you store a file on iOS for instance...). This is why we are now building features in the API first, then in the UI (both web and mobile).

As a conclusion, I'd say that I'm very proud of what we've accomplished so far, and even prouder by the community who help us every single day. Your feedback and your help make Monica possible.

The feature sends an email that is sent every few days - it's not affected by the last time you've interacted with someone or recorded an activity.

Version 2.1.0 also brings the support for markdown in the Journal and on the Notes. We've also fixed many bugs and continued our work on improving our Docker and Vagrant images.

Thanks for all the emails you send and issues you fill on GitHub. That helps greatly in knowing what we should work on next (although we have a good idea of what we want to do).

Redesign of relationships

Monica has always let you link contacts together. However this relation was limited to parent->child relationships, or love relationships. This wasn't the most flexible system. Starting now, you can now link contacts with many different relationship types, like uncle/nephew, coworker, mentor/protege, etc... The complete list of the possible relationships is defined here.

We've also tried to respect genders when we can. For instance, if contacts are women, we'll say "aunt" instead of "uncle", and so on. This is a real challenge for contacts who have a custom gender though. We do not support this case yet, but we are working on finding a good solution to manage this specific case.

This change was the biggest change we've made to Monica yet. Despite an extensive testing period, we had some bumps in the road while deploying this new feature, and I hope things are more stable now.

Ability to define which feature you want to activate on a contact sheet

We now have an option to customize which feature you want to use with your contacts. Under the Personalization tab in the Settings panel, you can now toggle features you care about. If you don't want to display the Gifts section, for instance, you can now hide it.

Journal entry date

You can now specify a date for a journal entry - allowing you to have more control over your journal.

Right to left languages

We now support right to left languages, starting with Hebrew. We'd like to thank our amazing community of translators for making this happen and their contributions to the translation process in general.

Markdown in activity comments

Markdown is a fantastic formatting tool. We were using it on a Call note, now we also use it in an activity's comment.

Final note

We are very lucky to have a great community around this project. I'd like to thank every contributor (above 100 now) who've helped by contributing to the code, every translator for their insane effort in translating the thousands of words we have in the app, every subscriber and donator for their monetary contributions. Everything helps. In a world who finally realizes how big social media platforms destroy the privacy of users and affect relationships between people, we need independent, open source projects like Monica to restore our faith in how great human relationships can be.

Version 2.0.0 is already available as a download, and is live on our hosted version.

A product should be opinionated and follow its own vision, at the risk of pushing back potential users. Why would people sign up for your product if it doesn’t have an unique voice or ways of doing things? My vision includes a simple, powerful product with the least amount of settings possible.

How on earth then have we added a Personalization tab under Settings?

I intend to allow personalization for things that I can’t control or decide myself. Monica is not a business tool. It’s supposed to mimic real lives of people and adapt to the unique situation of everyone. One of the mistakes I made early on was about genders for instance: I only allowed at first two genders, male and female. This was my own reality - but it wasn’t the reality of many, many people out there. Instead of deciding for my users, we’ve added the flexibility to define your own genders, that match your reality, not ours. I intend to do that for every concept that represent important aspects of our lives.

Note that settings won't include to personalize the number of elements to display on a page or any insignificant details like that. They just don't matter.

I hope that this clarifies a little bit where we are going with the personalization of the product in general.

Good product design: value for users > ease of use > speed > design

I’d like to explain my reasonings behind it.

What is product design? It’s the combination of what a product does, and how it does it.

Product designers have more responsibility than simply choosing how things should look or behave. They build the way users interact with the product. They need to take into account a large amount of criteria to do their job effectively. However, it’s worth asking the question of which criteria should be prioritized over others in the design process, if you can’t afford to cover the whole spectrum of what constitutes a good product design practice.

The most important thing a product (or feature) should do is bring value to the user. Any other consideration comes second. Your product can be slow, ugly, not easy to use, buggy - if your work is going to help users solve a specific problem they suffer with, they will endure anything to use it. You can’t say the same thing for a beautiful product that does not bring any value - no one will use it.

Once you are sure that the product or the feature brings value, you can put your energy on creating a great user experience. This doesn’t mean making it beautiful, or even pretty. Just really simple to use, or really easy to understand. Users will come to your product because you’ve promised them something - this can be summed up by either making their lives easier, or their jobs simpler. They will want to take advantage of your solution as quickly as possible and will value less your product if they can’t do what you are asking them to do in a simple way, or if it’s so complex that it makes them feel stupid.

Once your product brings enough value and is simple to use, you will want to focus on speed. Great products are fast. They don't waste the precious time of their users. The faster a product is, the more confident you feel about it. Most of the teams I’ve worked with think a feature is shipped once the code is done and the quality assurance passes. However a feature should not be considered as complete if it’s not as fast as it could be. Your product is the sum of your features. If you start to introduce slow features here and there, the whole will suffer eventually. Users devaluate slow products.

Finally, once a product brings enough value, is easy to use and is fast, you can make it pretty if you have time left or enough money to afford this process. But it’s not necessary per se. I would go as far as saying that if something brings enough value to the user, design is irrelevant. How things look is cherry on the cake. Design in itself shouldn’t be your main differentiator. It will help to differentiate a little bit your product from its competitors when you’ll become successful and many copycats will do exactly what you do exactly the same way. That being said, if your main differentiator is just a matter of design, you have other problems to solve first. Design is a trend that change often and quickly. What’s seen as beautiful today will be less valued tomorrow, just because.

Every day, I use Monica. And every day, I wished it had a better design, a better UX and it was faster. But I don't prioritize those aspects at all - and while it pains me a lot, I prefer creating value as much as possible first and foremost. When Monica will reach a state where we can afford taking some time to make things better, that means we would have created a product that brings tremendous value, that is extremely easy to use and fast enough for everyone. We are not there yet.

To sum up, what would you like your users to say about your work? Is it “Ok, it’s not pretty, but it’s so useful that I don't mind”, or “Ok, it’s beautiful, but I don't see why this product even exists”.