I'm trying to design a new microservice architecture that will eventually replace our current two monolithic APIs (we develop a desktop payroll software that uses our API to send payroll documents to employees or have them sign contracts, and more features and front-ends to come).
There is a lot of complexity regarding users relationships and I'd like to future-proof my design as much as possible.
Please excuse me if I'm not clear enough, I'm not a native English speaker and there are a lot of fine details :)
I will give many details below in case you're interested, but here is a summary:
- I have many types of actors who are tied with chained, business logic relationships (ex:
Organization > Company > Employee).
- Most of (maybe all in the future) these actors are candidates for being linked to a web user account. And a user account should be able to act like multiple actors (ex: an account
Xcould act as a
Company A, an
Employee from Company Aand an
Employee from Company B).
And I hesitate between at least 2 solutions:
1) Creating a microservice per actor type
- This could make sense because each actor have its own business logic (properties, actions).
- But I'm afraid it will generate a lot of inter-services requests for basic actions (ex:
DocumentServicemust check if the user account has rights to send
Employee, and this permission is defined as a
- Moreover, each microservice should be aware of others business logic, which greatly defeats the microservice philosophy in my opinion.
2) Creating a generic UserManagement service
- This could also make sense because I feel "actors and users relationships" could be seen as a business logic in itself, and all these actors are tightly coupled.
- My main fear with this option is that this service could become bigger and bigger as we bring features to the web. But then again I could create new microservices for these features and keep using my UserManagementService as a sort of RBAC provider.
What sounds more like a future-proof, best practice to you?
Do you have any advice or thoughts?
Currently, these are the different types of actors in our system:
Please note these edge (but nonetheless common) cases:
Customercould be an accounting firm and manage payrolls for multiple
Customercould be managing its
Companyalone, so all these actors could be one single person. And the Customer could be one of their own
Employees, being artists for the most part, often work for several
Companies(which could be managed by different
This is basically how our software works (locally, without APIs):
Customerpays for their licence.
Customerprovides licence key to create an
Organization(can create multiple ones).
Organization, with different access levels (which determines which companies/employees one can read/write).
Organizationto manage their payroll.
Employeesattached to a single
SoftwareUserscan generate payslips for
Then, these are the web-based features that are implemented by our current APIs:
SoftwareUsercan invite an
Employeeto create their web account (on behalf of their attached
SoftwareUsercan send PDF
Employee's account (on behalf of their attached
SoftwareUsercan create a
Campainto have an
Employeesign a contract online (on behalf of their attached
As for future features, there will be:
Customercan pay for their licence online and view some data (remaining payroll volume, consumed phone support time, etc...).
Companies(who are not using the software if the
Customeris an accountant firm) can view
Employeesrelated to them, signed
Documentsgenerated on their behalf.
SoftwareUserswho don't have access to the desktop software can enter data to populate payslips (this "feature" is expected to grow in the next years as we will progressively bring all the software's features to the web).
Finally, this system needs to be flexible, considering the following use cases:
Companiescould be transferred to other
Organizations(ex: a company could ask its accountant to provide its data if they wanted to manage their payroll itself).
- The same principle applies to each actor type.
Accountcreation invitations (with
Documentsattached) could be sent to wrong email addresses, so we must be able to transfer an
Employeeto a different account.
These are the reason I was planning this for relationships and authentication:
- For relationships, each actor will only know its parent ID and its linked
Account(s)ID(s): this will enable to easily switch owners (a required feature).
- For authentication, I'm planning to use JWTs with only the
AccountID as payload.
I took your comments into consideration and talked with some teammates, here is a new option:
3) With a PermissionService
Accountsare not linked to "actors" anymore. Instead, they are linked to multiple
Permissionsthat each specifies who has access to which resource, and possibly additional claims (ex:
This gives the possibility to provide either "account tokens" (with only the account ID), or "permission tokens" (with also the target ID and claims), depending on whether we enable SSO or need restricted service accounts.
As for the
ActorService(not sure if the name fits well), its purpose is to hold the business logic regarding "actors relationships" as well as their properties (some of which were added on the diagram to illustrate their business value).
I'm still not 100% sure about this design, so every comment is welcome.