📝(dimai) update docs on dimail

update README and docs describing interoperability between people and dimail

Co-authored-by: Laurent Bossavit <[email protected]>

README.md

@@ -1,12 +1,12 @@
 # People
 
-People is an application to handle users and teams. 
+People is an application to handle users and teams, and distribute permissions accross [La Suite](https://lasuite.numerique.gouv.fr/).
 
-As of today, this project is **not yet ready for production**. Expect breaking changes.
-
-People is built on top of [Django Rest
+It is built on top of [Django Rest
 Framework](https://www.django-rest-framework.org/).
 
+All interoperabilities will be described in `docs/interoperability`.
+
 ## Getting started
 
 ### Prerequisite
@@ -25,7 +25,7 @@ $ docker compose -v
 > ⚠️ You may need to run the following commands with `sudo` but this can be
 > avoided by assigning your user to the `docker` group.
 
-### Project bootstrap
+### Bootstrap project
 
 The easiest way to start working on the project is to use GNU Make:
 
@@ -38,21 +38,15 @@ database migrations and compile translations. It's a good idea to use this
 command each time you are pulling code from the project repository to avoid
 dependency-related or migration-related issues.
 
-Your Docker services should now be up and running 🎉
+Your Docker services should now be up and running! 🎉
 
 Note that if you need to run them afterward, you can use the eponym Make rule:
 
 ```bash
 $ make run
 ```
 
-### Adding content
-
-You can create a basic demo site by running:
-
-    $ make demo
-
-Finally, you can check all available Make rules using:
+You can check all available Make rules using:
 
 ```bash
 $ make help
@@ -71,6 +65,23 @@ $ make superuser
 
 You can then login with sub `admin` and password `admin`.
 
+### Adding demo content
+
+You can create a basic demo site by running:
+
+```bash
+$ make demo
+```
+
+### Setting dimail database 
+
+To ease local development when working on interoperability between people and dimail, we embark dimail-api in a container running in "fake" mode. 
+
+To populate dimail local database with users/domains/permissions needed for basic development:
+- log in with "people" user
+- run `make dimail-setup-db`
+
+
 ### Run frontend
 
 Run the front with:
@@ -79,14 +90,10 @@ Run the front with:
 $ make run-front-desk
 ```
 
-Then access at
-[http://localhost:3000](http://localhost:3000)
-
+Then access [http://localhost:3000](http://localhost:3000) with :
 user: people
-
 password: people
 
-
 ## Contributing
 
 This project is intended to be community-driven, so please, do not hesitate to

docs/interoperability/dimail.md

@@ -0,0 +1,35 @@
+# dimail 
+
+## What is dimail ? 
+
+The mailing solution provided in La Suite is [Open-XChange](https://www.open-xchange.com/) (OX). 
+OX not having a provisioning API, 'dimail-api' or 'dimail' was created to allow mail-provisioning through People.
+
+API and its documentation can be found [here](https://api.dev.ox.numerique.gouv.fr/docs#/).
+
+## Architectural links of dimail
+
+As dimail's primary goal is to act as an interface between People and OX, its architecture is similar to that of People. A series of requests are sent from People to dimail upon creating domains, users and accesses.
+
+### Domains
+
+Upon creating a domain on People, the same domain is created on dimail and will undergo a series of checks. When all checks have passed, the domain is considered valid and mailboxes can be created on it. 
+
+### Users
+
+The ones issuing requests. Dimail users will reflect domains owners and administrators on People, for logging purposes and to allow direct use of dimail, if desired. User reconciliation is made on user uuid provided by ProConnect.
+
+### Accesses
+
+As for People, an access - a permissions (or "allows" in dimail) - grants an user permission to create objects on a domain.
+
+Permissions requests are sent automatically upon : 
+- dimail database initialisation: 
+    + permission for dimail user People to create users and domains
+- domain creation : 
+    + permission for dimail user People to manage domain
+    + permission for new owner on new domain
+- user creation:
+    + permission for People to manage user
+- access creation, if owner or admin:
+    + permission for this user to manage domain