(The following is me being confused and hoping to come to an understanding of what to call my system and applications, and to improve the documentation for the next dev. I intend all criticism constructively, I promise !)
I have worked through the diatomic ions tutorial a few times. And each time I get to the section about naming the system, I feel like I understand, then I read the following:
https://docs.datomic.com/cloud/operation/planning.html#naming
And feel like I don’t understand anymore 
I think there might be a few typos that make that sections super confusing.
Let’s start with this one:
- Multiple systems might serve the same primary database in different development stages. So you might name systems via the convention “[db]-[stage]”, e.g.“inventory-dev”, “inventory-staging” and “inventory-prod”.
My understanding of Datomic Cloud is that 80% of people will have a single system, serving multiple applications, and hosting multiple databases. Some people may choose to have multiple systems, like the isolated production topology. So the statement about multiple systems is confusing to me. Also, “primary database”? I don’t think there is a primary database. Should this say “Primary Application” or “Compute Group”? That doesn’t really make sense either… so hmm.
That statement continues by saying, systems could be named [db]-[stage], which sort of makes sense if you intend to have a single db per system. But that seems contrary to the advice in the following sections, such as this one: https://docs.datomic.com/cloud/operation/planning.html#stages
I think maybe the first sentence is just wrong, and trying to make it make sense, is making the rest of it seem confusing.
Ok, let’s take the next bullet point:
- A system can serve more than one application via different query groups, although one application is often primary. So you might name applications
"[db](-[app])", e.g. “inventory” and “inventory-analytics”.
The first part makes sense, one system, multiple applications/query groups. As for “often primary”, I think this should say, “is primary”. The second part I think is suggesting I name applications the same as DBs, but sometimes append the application name? This is confusing too. Also, the directions for the solo topology have me naming the application the same as the system. Making we immediately wonder if that is bad advice.
So all that being said, here is what I think the advice about naming should be. Please correct/improve what I am saying here.
Items 1 and 4, super good, practical advice. Leave them as is. items 2 an 3 maybe replaced with the following.
- Applications and Compute Groups are synonymous in Datomic Cloud.
- A system is comprised of multiple databases and applications, so it should have a general name. [companyname]-ions is a good name. If you know upfront, that you will be running production in its own system (see below), name it [companyname]-ions-prod.
- A system will contain multiple applications, they can’t be renamed, but they can be added and deleted, except for the primary application. So name the primary application the same as the system. Secondary applications can have any name, since they can effectively be renamed if you need to.
- A system can have multiple databases, and an application can access multiple databases. The databases may be different stages of the same logical database (e.g. “inventory-prod”/“inventory-dev”) or different data altogether (e.g. “cars”/“users”). And of course these two naming conventions might be combined (e.g. “cars-dev”, “users-prod”). Databases can also be one-offs for whatever reason (“Jane’s Dev”/“Testing123”). Database are named in code, so you don’t have to worry about that when setting up a system.
Thanks for reading all of this intrepid forum reader! I would love any feedback, thoughts.
-Lucas