From f8e55be60c94570d709c1ec19558a61369360929 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Fri, 29 May 2026 15:53:47 +0200 Subject: [PATCH 01/16] Add Mocodo to generate MCD and MLD diagrams Mocodo (a Python CLI tool) is used to generate the: - MCD diagram in `docs/database/mcd/` - MLD diagram in`docs/database/mld/` Installation: cd learn)dev python -m pip pip # Run once source venv/bin/activate # Run each time you start a new shell pip install 'mocodo[svg,clipboard]' Usage: mocodo --input docs/database/mcd/learn-dev.mcd -t arrange --colors brewer+ --- CONTRIBUTING.md | 15 ++ Makefile | 57 +++++++ README.md | 35 ++++ docs/database/mcd/learn-dev.mcd | 28 ++++ docs/database/mcd/learn-dev.svg | 197 +++++++++++++++++++++++ docs/database/mcd/learn-dev_geo.json | 43 +++++ docs/database/mld/learn-dev_geo.json | 43 +++++ docs/database/mld/learn-dev_mld.mcd | 25 +++ docs/database/mld/learn-dev_mld.md | 9 ++ docs/database/mld/learn-dev_mld.svg | 171 ++++++++++++++++++++ docs/database/mld/learn-dev_mld_geo.json | 24 +++ 11 files changed, 647 insertions(+) create mode 100644 Makefile create mode 100644 docs/database/mcd/learn-dev.mcd create mode 100644 docs/database/mcd/learn-dev.svg create mode 100644 docs/database/mcd/learn-dev_geo.json create mode 100644 docs/database/mld/learn-dev_geo.json create mode 100644 docs/database/mld/learn-dev_mld.mcd create mode 100644 docs/database/mld/learn-dev_mld.md create mode 100644 docs/database/mld/learn-dev_mld.svg create mode 100644 docs/database/mld/learn-dev_mld_geo.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf9b106..372dfd3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -340,6 +340,21 @@ Here are the naming conventions for the **name** of our database **tables**: Do not use an underscore as the first character. +##### Database MCD Diagram + +*MCD* stands for 🇫🇷 **Modèle Conceptuel de Données** (in the Merise methodology). +This is a diagram that shows the *Conceptual Data Model* with entities and relationships. + +![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). + +The MCD is available as an +[SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). + + +##### Database MPD Diagram + +TODO: Add MPD diagram and link + ##### Database ERD Diagram diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..10285e6 --- /dev/null +++ b/Makefile @@ -0,0 +1,57 @@ +# Ignore existing files with the same name as phony targets +.PHONY: diagrams mcd mld mpd ddl clean + +# Default make target used if none specified +.DEFAULT_GOAL := help + +# Display the syntax with available targets +help: + @echo "Available targets:" + @echo " make diagrams — generate MCD, MLD, and MPD" + @echo " make mcd — generate MCD" + @echo " make mpd — generate MPD" + @echo " make ddl — regenerate DDL (SQL with Postgres database structure)" + @echo " make clean — remove generated diagrams" + +# Generate all database diagrams (MCD, MLD, MPD) +diagrams: mcd mld mpd + @echo "All diagrams generated (MCD, MLD, MPD)" + +# Generate MCD from Mocodo source +mcd: + @echo "Generating MCD..." + mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/mcd --colors brewer+1 + @echo "MCD generated in docs/database/mcd/" + +# Generate MLD (2 step process): +# - transform MCD source into a MLD source: docs/database/mld/learn-dev_mld.mcd +# - Render the MLD source +mld: + @echo "Generating MLD..." + mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/mld --transform mld diagram + rm -f docs/database/mld/learn-dev.* + mocodo --input docs/database/mld/learn-dev_mld.mcd --output_dir docs/database/mld --colors ocean + @echo "MLD generated in docs/database/mld/learn-dev_mld.svg" + +# Generate MPD from the PostgreSQL database +mpd: + @echo "Generating MPD from PostgreSQL Database..." + tbls docs/database/mpd --force + @echo "MPD generated in docs/database/mpd/" + +# Generate a SQL file to create the database structure (tables, associations) +# (with Postgres DDL syntax) +ddl: + @echo "Generating DDL (Postgres SQL syntax)..." + mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/ddl -t postgres + @echo "DDL generated in docs/database/ddl/" + +# Clean up generated diagram files (keep source files) +clean: + @echo "Cleaning up generated diagrams..." + rm -f docs/database/mcd/learn-dev.svg + rm -f docs/database/mcd/learn-dev_geo.json + rm -f docs/database/mld/* + rm -f docs/database/mpd/* + rm -f docs/database/ddl/* + @echo "Cleaned" diff --git a/README.md b/README.md index 070824a..b61fde5 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,41 @@ Install _Docker_ and _Docker Compose_: ``` - on [Windows and Linux](https://docs.docker.com/get-started/get-docker/) +### Python Setup + +This is **optional** if you only need **to run the application**. + +This is necessary in order to regenerate the MERISE database diagrams +(MCD, MLD and MPD) after any changes have been made to the database design. + +You will need to install *Python* and some additional Python packages (i.e., libraries and tools): +- `mocodo`: a CLI tool to generate the MCD and MLD database diagrams + from a text-file description of the conceptual data model. +- `tbls`: a CLI tool to reverse engineer the live database to generate the MPD. + +Here is the procedure: + +- [ ] Install Python + - Install Python on macOS + ```shell + brew install python@3.14 + ``` + - Install Python on other OSes: + http://docs.python-guide.org/en/latest/starting/installation/ +- [ ] Create a Python Virtual Environment: + ```shell + # cd to the folder where you cloned the repository + python -m pip pip venv venv # Do it once + source venv/bin/activate # Run this line each time you open a new shell/terminal/window/tab + ``` +- [ ] Install **[mocodo](https://laowantong.github.io/mocodo/doc/fr_refman.html#Installation-et-lancement-du-programme) + ```shell + pip install 'mocodo[svg,clipboard]' + ``` +- [ ] Install **[tbls](https://github.com/k1LoW/tbls#install)** + ```shell + pip install tbls + ``` ## Configuration diff --git a/docs/database/mcd/learn-dev.mcd b/docs/database/mcd/learn-dev.mcd new file mode 100644 index 0000000..1948f43 --- /dev/null +++ b/docs/database/mcd/learn-dev.mcd @@ -0,0 +1,28 @@ +% learn-dev MCD (Modele Conceptuel des Données). +% This text file uses Mocodo-syntax to describe the MCD. +% +% See: +% - GitHub Repository: https://github.com/laowantong/mocodo +% - Syntax: https://laowantong.github.io/mocodo/doc/fr_refman.html#Syntaxe-de-description-d'un-MCD +% Usage: +% mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/mcd --colors brewer+1 + +: +Email Token: token_id, token, expires_at, used_at +Audit Log: log_id, action_type, entity_type, entity_id, description, ip_address, user_agent, was_successful, error_message, metadata +: + +Reset Token: token_id, token, expires_at, used_at, ip_address +Receives, 11 Email Token, 0N User +Performs, 01 Audit Log, 0N User +: + +Requests, 11 Reset Token, 0N User +User: user_id, username, email, password, first_name, last_name, is_active, is_verified, is_locked, failed_login_attempts, last_login_at, password_changed_at +Holds, 0N User, 0N Role : assigned_at, assigned_by +Role: role_id, role_name, description, is_active + +: +Owns, 11 Refresh Token, 0N User +Refresh Token: token_id, token, expires_at, revoked_at, revoked_reason, ip_address, user_agent, last_used_at +: \ No newline at end of file diff --git a/docs/database/mcd/learn-dev.svg b/docs/database/mcd/learn-dev.svg new file mode 100644 index 0000000..066f1fb --- /dev/null +++ b/docs/database/mcd/learn-dev.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + Receives + + 1,1 + 0,N + + + + + + + + + + + + Performs + + 0,1 + 0,N + + + + + + + + + + + + Requests + + 1,1 + 0,N + + + + + + + + + + + + Holds + assigned_at + assigned_by + + 0,N + 0,N + + + + + + + + + + + + Owns + + 1,1 + 0,N + + + + + + + + + + + Email Token + token_id + + token + expires_at + used_at + + + + + + + + + + + Audit Log + log_id + + action_type + entity_type + entity_id + description + ip_address + user_agent + was_successful + error_message + metadata + + + + + + + + + + + Reset Token + token_id + + token + expires_at + used_at + ip_address + + + + + + + + + + + User + user_id + + username + email + password + first_name + last_name + is_active + is_verified + is_locked + failed_login_attempts + last_login_at + password_changed_at + + + + + + + + + + + Role + role_id + + role_name + description + is_active + + + + + + + + + + + Refresh Token + token_id + + token + expires_at + revoked_at + revoked_reason + ip_address + user_agent + last_used_at + + \ No newline at end of file diff --git a/docs/database/mcd/learn-dev_geo.json b/docs/database/mcd/learn-dev_geo.json new file mode 100644 index 0000000..7d256b0 --- /dev/null +++ b/docs/database/mcd/learn-dev_geo.json @@ -0,0 +1,43 @@ +{ + "width": 551, + "height": 819, + "cx": [ + [ "EMAIL_TOKEN", 230 ], + [ "AUDIT_LOG", 382 ], + [ "RESET_TOKEN", 73 ], + [ "RECEIVES", 230 ], + [ "PERFORMS", 382 ], + [ "REQUESTS", 73 ], + [ "USER", 230 ], + [ "HOLDS", 382 ], + [ "ROLE", 499 ], + [ "OWNS", 230 ], + [ "REFRESH_TOKEN", 382 ] + ], + "cy": [ + [ "EMAIL_TOKEN", 115 ], + [ "AUDIT_LOG", 115 ], + [ "RESET_TOKEN", 274 ], + [ "RECEIVES", 274 ], + [ "PERFORMS", 274 ], + [ "REQUESTS", 485 ], + [ "USER", 485 ], + [ "HOLDS", 485 ], + [ "ROLE", 485 ], + [ "OWNS", 721 ], + [ "REFRESH_TOKEN", 721 ] + ], + "shift": [ + [ "RECEIVES,EMAIL_TOKEN,0", 0 ], + [ "RECEIVES,USER,0", 0 ], + [ "PERFORMS,AUDIT_LOG,0", 0 ], + [ "PERFORMS,USER,0", 0 ], + [ "REQUESTS,RESET_TOKEN,0", 0 ], + [ "REQUESTS,USER,0", 0 ], + [ "HOLDS,USER,0", 0 ], + [ "HOLDS,ROLE,0", 0 ], + [ "OWNS,REFRESH_TOKEN,0", 0 ], + [ "OWNS,USER,0", 0 ] + ], + "ratio": [] +} diff --git a/docs/database/mld/learn-dev_geo.json b/docs/database/mld/learn-dev_geo.json new file mode 100644 index 0000000..7d256b0 --- /dev/null +++ b/docs/database/mld/learn-dev_geo.json @@ -0,0 +1,43 @@ +{ + "width": 551, + "height": 819, + "cx": [ + [ "EMAIL_TOKEN", 230 ], + [ "AUDIT_LOG", 382 ], + [ "RESET_TOKEN", 73 ], + [ "RECEIVES", 230 ], + [ "PERFORMS", 382 ], + [ "REQUESTS", 73 ], + [ "USER", 230 ], + [ "HOLDS", 382 ], + [ "ROLE", 499 ], + [ "OWNS", 230 ], + [ "REFRESH_TOKEN", 382 ] + ], + "cy": [ + [ "EMAIL_TOKEN", 115 ], + [ "AUDIT_LOG", 115 ], + [ "RESET_TOKEN", 274 ], + [ "RECEIVES", 274 ], + [ "PERFORMS", 274 ], + [ "REQUESTS", 485 ], + [ "USER", 485 ], + [ "HOLDS", 485 ], + [ "ROLE", 485 ], + [ "OWNS", 721 ], + [ "REFRESH_TOKEN", 721 ] + ], + "shift": [ + [ "RECEIVES,EMAIL_TOKEN,0", 0 ], + [ "RECEIVES,USER,0", 0 ], + [ "PERFORMS,AUDIT_LOG,0", 0 ], + [ "PERFORMS,USER,0", 0 ], + [ "REQUESTS,RESET_TOKEN,0", 0 ], + [ "REQUESTS,USER,0", 0 ], + [ "HOLDS,USER,0", 0 ], + [ "HOLDS,ROLE,0", 0 ], + [ "OWNS,REFRESH_TOKEN,0", 0 ], + [ "OWNS,USER,0", 0 ] + ], + "ratio": [] +} diff --git a/docs/database/mld/learn-dev_mld.mcd b/docs/database/mld/learn-dev_mld.mcd new file mode 100644 index 0000000..4b5d4b1 --- /dev/null +++ b/docs/database/mld/learn-dev_mld.mcd @@ -0,0 +1,25 @@ +%%mocodo +::: +Email Token: token_id, token, expires_at, used_at, #user_id > User > user_id +: +Audit Log: log_id, action_type, entity_type, entity_id, description, ip_address, user_agent, was_successful, error_message, metadata, #user_id > User > user_id +::: + + +: +Reset Token: token_id, token, expires_at, used_at, ip_address, #user_id > User > user_id +::::::: + + +::: +User: user_id, username, email, password, first_name, last_name, is_active, is_verified, is_locked, failed_login_attempts, last_login_at, password_changed_at +: +Holds: #user_id > User > user_id, _#role_id > Role > role_id, assigned_at, assigned_by +: +Role: role_id, role_name, description, is_active +: + + +::::: +Refresh Token: token_id, token, expires_at, revoked_at, revoked_reason, ip_address, user_agent, last_used_at, #user_id > User > user_id +::: diff --git a/docs/database/mld/learn-dev_mld.md b/docs/database/mld/learn-dev_mld.md new file mode 100644 index 0000000..375dbd9 --- /dev/null +++ b/docs/database/mld/learn-dev_mld.md @@ -0,0 +1,9 @@ + + +- **Audit Log** (log_id, action_type, entity_type, entity_id, description, ip_address, user_agent, was_successful, error_message, metadata, _#user_id_) +- **Email Token** (token_id, token, expires_at, used_at, _#user_id_) +- **Holds** (_#user_id_, _#role_id_, assigned_at, assigned_by) +- **Refresh Token** (token_id, token, expires_at, revoked_at, revoked_reason, ip_address, user_agent, last_used_at, _#user_id_) +- **Reset Token** (token_id, token, expires_at, used_at, ip_address, _#user_id_) +- **Role** (role_id, role_name, description, is_active) +- **User** (user_id, username, email, password, first_name, last_name, is_active, is_verified, is_locked, failed_login_attempts, last_login_at, password_changed_at) diff --git a/docs/database/mld/learn-dev_mld.svg b/docs/database/mld/learn-dev_mld.svg new file mode 100644 index 0000000..d9984d6 --- /dev/null +++ b/docs/database/mld/learn-dev_mld.svg @@ -0,0 +1,171 @@ + + + + + + + + + + + + + + Email Token + token_id + + token + expires_at + used_at + #user_id + + + + + + + + + + + Audit Log + log_id + + action_type + entity_type + entity_id + description + ip_address + user_agent + was_successful + error_message + metadata + #user_id + + + + + + + + + + + Reset Token + token_id + + token + expires_at + used_at + ip_address + #user_id + + + + + + + + + + + User + user_id + + username + email + password + first_name + last_name + is_active + is_verified + is_locked + failed_login_attempts + last_login_at + password_changed_at + + + + + + + + + + + Holds + #user_id + + #role_id + + assigned_at + assigned_by + + + + + + + + + + + Role + role_id + + role_name + description + is_active + + + + + + + + + + + Refresh Token + token_id + + token + expires_at + revoked_at + revoked_reason + ip_address + user_agent + last_used_at + #user_id + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/database/mld/learn-dev_mld_geo.json b/docs/database/mld/learn-dev_mld_geo.json new file mode 100644 index 0000000..fc2fc81 --- /dev/null +++ b/docs/database/mld/learn-dev_mld_geo.json @@ -0,0 +1,24 @@ +{ + "width": 772, + "height": 694, + "cx": [ + [ "EMAIL_TOKEN", 302 ], + [ "AUDIT_LOG", 514 ], + [ "RESET_TOKEN", 102 ], + [ "USER", 302 ], + [ "HOLDS", 514 ], + [ "ROLE", 691 ], + [ "REFRESH_TOKEN", 514 ] + ], + "cy": [ + [ "EMAIL_TOKEN", 124 ], + [ "AUDIT_LOG", 124 ], + [ "RESET_TOKEN", 263 ], + [ "USER", 410 ], + [ "HOLDS", 410 ], + [ "ROLE", 410 ], + [ "REFRESH_TOKEN", 587 ] + ], + "shift": [], + "ratio": [] +} From 6816dacce65b0f52ae14935fdc961cc8c7cf7bf9 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 16:39:45 +0200 Subject: [PATCH 02/16] docs(db): Add a section about Merise database diagrams (MCD, MLD, MPD) --- CONTRIBUTING.md | 51 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 372dfd3..be2419c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -323,10 +323,33 @@ The main advantages in my opinion are: > letter and each subsequent word begins with an uppercase letter, with no spaces or underscores: `useJuryVote`. -#### Database Schema +#### Database + +The *learn-dev* platform uses a **PostgreSQL** relational database to persist entities. + +##### Database Schema This section describes how the database is structured. -The *learn-dev* platform uses a PostgreSQL relational database to persist entities. + +The data model (entities and relationships...) are described +using 3 diagrams from the Merise methodology: MCD, MLD, and MPD. +This is a 3-step progressive approach from conceptual, logical to physical: +- **MCD** (Conceptual Data Model): This high-level **business-domain** oriented diagram + that shows the **data (entities), their **relationships** and **cardinalities**, + with **NO technical details**. +- **MLD** (Logical Data Model): This diagram shows the relational structure + in a database agnostic way. It is a transformed version of the MCD where: + entities become tables, `1..N` relationships become foreign keys, + `N..N` relationships become junction tables, `1..1` relationship become foreign key. + The *MLD* is shared domain experts, database administrators, + and application developers. + Domain experts can check that the relational structure captures the business correctly. + Application developers can start creating the entities (and database admins) + can create the migration scripts. +- **MPD**: This diagram is aimed at database administrators and application developers. + It is exhaustive and database-specific. It contains all the tables, fields, keys, + database-specific data types, and constraints... + It can be used to implement the data model in the database. ##### Database Naming Conventions @@ -342,13 +365,27 @@ Do not use an underscore as the first character. ##### Database MCD Diagram -*MCD* stands for 🇫🇷 **Modèle Conceptuel de Données** (in the Merise methodology). -This is a diagram that shows the *Conceptual Data Model* with entities and relationships. +*MCD* stands for 🇫🇷 **Modèle Conceptuel de Données**. +This diagram from the MERISE methodology shows the *Conceptual Data Model*: +entities and relationships without the (database) technical details. +It is aimed at the business owners. + +> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). + +To view the MCD in full screen, you can also open it in a new window: +[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). + + +#### Database MLD + +*MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). +The MLD diagram is part of the _Merise_ methodology. +It is used to display the *Logical Data Model*. -![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). -The MCD is available as an -[SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +To view the MLD in full screen, you can also open it in a new window: +[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). ##### Database MPD Diagram From d1969bc245eb53b63ac23e20abb46b4c8fd5394e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 2 Jun 2026 17:04:11 +0000 Subject: [PATCH 03/16] docs: use branch-aware links for merise diagrams --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be2419c..2e2ea76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -370,10 +370,10 @@ This diagram from the MERISE methodology shows the *Conceptual Data Model*: entities and relationships without the (database) technical details. It is aimed at the business owners. -> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +> ![MCD](docs/database/mcd/learn-dev.svg). To view the MCD in full screen, you can also open it in a new window: -[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +[MCD as an SVG image](docs/database/mcd/learn-dev.svg). #### Database MLD @@ -382,10 +382,10 @@ To view the MCD in full screen, you can also open it in a new window: The MLD diagram is part of the _Merise_ methodology. It is used to display the *Logical Data Model*. -> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). +> ![MLD](docs/database/mld/learn-dev_mld.svg). To view the MLD in full screen, you can also open it in a new window: -[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). +[MLD as an SVG image](docs/database/mld/learn-dev_mld.svg). ##### Database MPD Diagram From 6b2b99cb229a845e66baccfac569529699b3a8f8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 2 Jun 2026 17:04:55 +0000 Subject: [PATCH 04/16] docs: make merise diagram links branch-agnostic --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e2ea76..aac3ef7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -370,10 +370,10 @@ This diagram from the MERISE methodology shows the *Conceptual Data Model*: entities and relationships without the (database) technical details. It is aimed at the business owners. -> ![MCD](docs/database/mcd/learn-dev.svg). +> ![MCD](docs/database/mcd/learn-dev.svg) To view the MCD in full screen, you can also open it in a new window: -[MCD as an SVG image](docs/database/mcd/learn-dev.svg). +[MCD as an SVG image](docs/database/mcd/learn-dev.svg) #### Database MLD @@ -382,10 +382,10 @@ To view the MCD in full screen, you can also open it in a new window: The MLD diagram is part of the _Merise_ methodology. It is used to display the *Logical Data Model*. -> ![MLD](docs/database/mld/learn-dev_mld.svg). +> ![MLD](docs/database/mld/learn-dev_mld.svg) To view the MLD in full screen, you can also open it in a new window: -[MLD as an SVG image](docs/database/mld/learn-dev_mld.svg). +[MLD as an SVG image](docs/database/mld/learn-dev_mld.svg) ##### Database MPD Diagram From 43fa2fc843d074bf1af638f7ef3bb9fae3e1e192 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 19:22:26 +0200 Subject: [PATCH 05/16] docs: Fix brolen links to Merise data model diagrams --- CONTRIBUTING.md | 45 +++++++++++++++++++++++++++++++++++++-------- Makefile | 3 ++- README.md | 6 +++--- 3 files changed, 42 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aac3ef7..044b1bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -331,11 +331,11 @@ The *learn-dev* platform uses a **PostgreSQL** relational database to persist en This section describes how the database is structured. -The data model (entities and relationships...) are described +The data model (entities and relationships...) is described using 3 diagrams from the Merise methodology: MCD, MLD, and MPD. This is a 3-step progressive approach from conceptual, logical to physical: - **MCD** (Conceptual Data Model): This high-level **business-domain** oriented diagram - that shows the **data (entities), their **relationships** and **cardinalities**, + that shows the **data (entities)**, their **relationships** and **cardinalities**, with **NO technical details**. - **MLD** (Logical Data Model): This diagram shows the relational structure in a database agnostic way. It is a transformed version of the MCD where: @@ -363,32 +363,61 @@ Here are the naming conventions for the **name** of our database **tables**: Do not use an underscore as the first character. -##### Database MCD Diagram +##### MCD Diagram *MCD* stands for 🇫🇷 **Modèle Conceptuel de Données**. -This diagram from the MERISE methodology shows the *Conceptual Data Model*: -entities and relationships without the (database) technical details. +The MCD diagram is part of the MERISE methodology and shows the *Conceptual Data Model*, +that is entities and relationships without the (database) technical details. It is aimed at the business owners. +<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams > ![MCD](docs/database/mcd/learn-dev.svg) +||||||| Common ancestor +> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +======= +> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). + +--- +Relative Link to MCD + +> ![MCD](docs/database/mcd/learn-dev.svg). +>>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams To view the MCD in full screen, you can also open it in a new window: +<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams [MCD as an SVG image](docs/database/mcd/learn-dev.svg) +||||||| Common ancestor +[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). +======= +[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). +>>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams -#### Database MLD +#### MLD Diagram *MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). The MLD diagram is part of the _Merise_ methodology. It is used to display the *Logical Data Model*. +<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams > ![MLD](docs/database/mld/learn-dev_mld.svg) +||||||| Common ancestor +> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). +======= +> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). +>>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams To view the MLD in full screen, you can also open it in a new window: +<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams [MLD as an SVG image](docs/database/mld/learn-dev_mld.svg) +||||||| Common ancestor +[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). +======= +[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). +>>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams -##### Database MPD Diagram +##### MPD Diagram TODO: Add MPD diagram and link @@ -396,7 +425,7 @@ TODO: Add MPD diagram and link ##### Database ERD Diagram The **Entity Relationships Diagram** (ERD) -is available as an [SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/ERD.svg) +is available as an [SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/mpd/ERD.svg) > [!NOTE] > This diagram uses [Crow's foot notation](https://mermaid.js.org/syntax/entityRelationshipDiagram.html#relationship-syntax) diff --git a/Makefile b/Makefile index 10285e6..cb8184e 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,7 @@ help: @echo "Available targets:" @echo " make diagrams — generate MCD, MLD, and MPD" @echo " make mcd — generate MCD" + @echo " make mld — generate MLD" @echo " make mpd — generate MPD" @echo " make ddl — regenerate DDL (SQL with Postgres database structure)" @echo " make clean — remove generated diagrams" @@ -46,7 +47,7 @@ ddl: mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/ddl -t postgres @echo "DDL generated in docs/database/ddl/" -# Clean up generated diagram files (keep source files) +# Clean up generated diagram files clean: @echo "Cleaning up generated diagrams..." rm -f docs/database/mcd/learn-dev.svg diff --git a/README.md b/README.md index b61fde5..93a1671 100644 --- a/README.md +++ b/README.md @@ -117,10 +117,10 @@ Here is the procedure: - [ ] Create a Python Virtual Environment: ```shell # cd to the folder where you cloned the repository - python -m pip pip venv venv # Do it once - source venv/bin/activate # Run this line each time you open a new shell/terminal/window/tab + python -m venv venv # Do it once + source venv/bin/activate # Run this line each time you open a new shell/terminal/window/tab ``` -- [ ] Install **[mocodo](https://laowantong.github.io/mocodo/doc/fr_refman.html#Installation-et-lancement-du-programme) +- [ ] Install **[mocodo](https://laowantong.github.io/mocodo/doc/fr_refman.html#Installation-et-lancement-du-programme)** ```shell pip install 'mocodo[svg,clipboard]' ``` From af06d9a2e8586bf8b6e41e49c952065468ce9e6c Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 20:31:22 +0200 Subject: [PATCH 06/16] docs: Remove conflict markers and reorder diagram links --- CONTRIBUTING.md | 43 ++++++++++--------------------------------- 1 file changed, 10 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 044b1bc..5488a34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -370,51 +370,28 @@ The MCD diagram is part of the MERISE methodology and shows the *Conceptual Data that is entities and relationships without the (database) technical details. It is aimed at the business owners. -<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams -> ![MCD](docs/database/mcd/learn-dev.svg) -||||||| Common ancestor -> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). -======= > ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). ---- -Relative Link to MCD - -> ![MCD](docs/database/mcd/learn-dev.svg). ->>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams - To view the MCD in full screen, you can also open it in a new window: -<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams -[MCD as an SVG image](docs/database/mcd/learn-dev.svg) -||||||| Common ancestor -[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mcd/learn-dev.svg). -======= [MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). ->>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams + +Relative Link to MCD +> ![MCD](docs/database/mcd/learn-dev.svg) #### MLD Diagram *MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). -The MLD diagram is part of the _Merise_ methodology. -It is used to display the *Logical Data Model*. - -<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams -> ![MLD](docs/database/mld/learn-dev_mld.svg) -||||||| Common ancestor -> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). -======= +The MLD diagram is part of the _Merise_ methodologyand is used to display +the *Logical Data Model*. + > ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). ->>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams To view the MLD in full screen, you can also open it in a new window: -<<<<<<< New base: docs: Fix brolen links to Merise data model diagrams -[MLD as an SVG image](docs/database/mld/learn-dev_mld.svg) -||||||| Common ancestor -[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/docs/database/mld/learn-dev_mld.svg). -======= -[MLD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). ->>>>>>> Current commit: docs: Fix brolen links to Merise data model diagrams +[MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). + +Relative Link to MLD: +> ![MLD as an SVG image](docs/database/mld/learn-dev_mld.svg) ##### MPD Diagram From ed41e9ce8212a8602abdb301d49f9b37367d60aa Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 20:45:31 +0200 Subject: [PATCH 07/16] docs: Fix docs, Makefile targets, folders and install commands --- CONTRIBUTING.md | 4 ++-- Makefile | 4 +++- README.md | 4 ++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5488a34..6cda8a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -379,7 +379,7 @@ Relative Link to MCD > ![MCD](docs/database/mcd/learn-dev.svg) -#### MLD Diagram +##### MLD Diagram *MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). The MLD diagram is part of the _Merise_ methodologyand is used to display @@ -399,7 +399,7 @@ Relative Link to MLD: TODO: Add MPD diagram and link -##### Database ERD Diagram +##### ERD Diagram The **Entity Relationships Diagram** (ERD) is available as an [SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/mpd/ERD.svg) diff --git a/Makefile b/Makefile index cb8184e..99ea313 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ # Ignore existing files with the same name as phony targets -.PHONY: diagrams mcd mld mpd ddl clean +.PHONY: help diagrams mcd mld mpd ddl clean # Default make target used if none specified .DEFAULT_GOAL := help @@ -37,6 +37,7 @@ mld: # Generate MPD from the PostgreSQL database mpd: @echo "Generating MPD from PostgreSQL Database..." + @mkdir -p docs/database/mpd tbls docs/database/mpd --force @echo "MPD generated in docs/database/mpd/" @@ -44,6 +45,7 @@ mpd: # (with Postgres DDL syntax) ddl: @echo "Generating DDL (Postgres SQL syntax)..." + @mkdir -p docs/database/ddl mocodo --input docs/database/mcd/learn-dev.mcd --output_dir docs/database/ddl -t postgres @echo "DDL generated in docs/database/ddl/" diff --git a/README.md b/README.md index 93a1671..2642e30 100644 --- a/README.md +++ b/README.md @@ -113,11 +113,11 @@ Here is the procedure: brew install python@3.14 ``` - Install Python on other OSes: - http://docs.python-guide.org/en/latest/starting/installation/ + https://docs.python-guide.org/en/latest/starting/installation/ - [ ] Create a Python Virtual Environment: ```shell # cd to the folder where you cloned the repository - python -m venv venv # Do it once + python3 -m venv venv # Do it once source venv/bin/activate # Run this line each time you open a new shell/terminal/window/tab ``` - [ ] Install **[mocodo](https://laowantong.github.io/mocodo/doc/fr_refman.html#Installation-et-lancement-du-programme)** From a535cb218300b0b119fae328f5ad10c05bb2217c Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:05:52 +0200 Subject: [PATCH 08/16] docs: Move description of Merise diagrams to dedicated sections --- CONTRIBUTING.md | 63 ++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cda8a8..b81d4f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -329,23 +329,10 @@ The *learn-dev* platform uses a **PostgreSQL** relational database to persist en ##### Database Schema -This section describes how the database is structured. - -The data model (entities and relationships...) is described -using 3 diagrams from the Merise methodology: MCD, MLD, and MPD. -This is a 3-step progressive approach from conceptual, logical to physical: -- **MCD** (Conceptual Data Model): This high-level **business-domain** oriented diagram - that shows the **data (entities)**, their **relationships** and **cardinalities**, - with **NO technical details**. -- **MLD** (Logical Data Model): This diagram shows the relational structure - in a database agnostic way. It is a transformed version of the MCD where: - entities become tables, `1..N` relationships become foreign keys, - `N..N` relationships become junction tables, `1..1` relationship become foreign key. - The *MLD* is shared domain experts, database administrators, - and application developers. - Domain experts can check that the relational structure captures the business correctly. - Application developers can start creating the entities (and database admins) - can create the migration scripts. +This section describes the data model using the progressive 3 diagrams +(MCD, MLD, and MPD) from the Merise methodology. +This gives a view from high-level conceptual (MCD), logical (MLD) to +physical (MPD) with all the database details. - **MPD**: This diagram is aimed at database administrators and application developers. It is exhaustive and database-specific. It contains all the tables, fields, keys, database-specific data types, and constraints... @@ -365,44 +352,50 @@ Do not use an underscore as the first character. ##### MCD Diagram -*MCD* stands for 🇫🇷 **Modèle Conceptuel de Données**. -The MCD diagram is part of the MERISE methodology and shows the *Conceptual Data Model*, -that is entities and relationships without the (database) technical details. -It is aimed at the business owners. +*MCD* stands for 🇫🇷 **Modèle Conceptuel de Données** (Conceptual Data Model). +The *MCD diagram* is part of the *Merise* methodology and shows the entities +and relationships without the (database) technical details. -> ![MCD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). +This is a high-level **business-domain** oriented diagram +that shows the **data (entities)**, their **relationships** and **cardinalities**, +with **NO technical and implementation details**. -To view the MCD in full screen, you can also open it in a new window: -[MCD as an SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mcd/learn-dev.svg). - -Relative Link to MCD > ![MCD](docs/database/mcd/learn-dev.svg) ##### MLD Diagram *MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). -The MLD diagram is part of the _Merise_ methodologyand is used to display +The **MLD diagram** is part of the _Merise_ methodology and shows the *Logical Data Model*. -> ![MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). +It shows the relational structure in a database-agnostic way. +It is a transformed version of the MCD where: +- entities become tables, +- `1..N` relationships become foreign keys, +- `N..N` relationships become junction tables, +- `1..1` relationship become foreign key. -To view the MLD in full screen, you can also open it in a new window: -[MLD](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/database/mld/learn-dev_mld.svg). +The *MLD* is shared domain experts, database administrators, +and application developers. +*Domain experts* can check that the relational structure captures the business correctly. +*Application developers* can start creating the entities (and database admins) +can create the migration scripts. -Relative Link to MLD: -> ![MLD as an SVG image](docs/database/mld/learn-dev_mld.svg) +> ![MLD](docs/database/mld/learn-dev_mld.svg) ##### MPD Diagram -TODO: Add MPD diagram and link +*MPD* stands for The *MPD* diagram +> ![MPD](docs/database/mpd/learn-dev_mpd.svg) + ##### ERD Diagram -The **Entity Relationships Diagram** (ERD) -is available as an [SVG image](https://raw.githubusercontent.com/ebouchut/learn-dev/dev/docs/mpd/ERD.svg) +> ![ERD Diagram](docs/database/mpd/ERD.svg) + > [!NOTE] > This diagram uses [Crow's foot notation](https://mermaid.js.org/syntax/entityRelationshipDiagram.html#relationship-syntax) From 8459e02d98894f880ab4afa96da7b724d7990893 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:09:22 +0200 Subject: [PATCH 09/16] docs: Unshift heading-level of database sections --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b81d4f0..1a3b2fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -327,7 +327,7 @@ The main advantages in my opinion are: The *learn-dev* platform uses a **PostgreSQL** relational database to persist entities. -##### Database Schema +#### Database Schema This section describes the data model using the progressive 3 diagrams (MCD, MLD, and MPD) from the Merise methodology. @@ -339,7 +339,7 @@ physical (MPD) with all the database details. It can be used to implement the data model in the database. -##### Database Naming Conventions +#### Database Naming Conventions Here are the naming conventions for the **name** of our database **tables**: @@ -350,7 +350,7 @@ Here are the naming conventions for the **name** of our database **tables**: Do not use an underscore as the first character. -##### MCD Diagram +#### MCD Diagram *MCD* stands for 🇫🇷 **Modèle Conceptuel de Données** (Conceptual Data Model). The *MCD diagram* is part of the *Merise* methodology and shows the entities @@ -363,7 +363,7 @@ with **NO technical and implementation details**. > ![MCD](docs/database/mcd/learn-dev.svg) -##### MLD Diagram +#### MLD Diagram *MLD* stands for 🇫🇷 **Modèle Logique de Données** (Logical Data Model). The **MLD diagram** is part of the _Merise_ methodology and shows @@ -385,14 +385,14 @@ can create the migration scripts. > ![MLD](docs/database/mld/learn-dev_mld.svg) -##### MPD Diagram +#### MPD Diagram *MPD* stands for The *MPD* diagram > ![MPD](docs/database/mpd/learn-dev_mpd.svg) -##### ERD Diagram +#### ERD Diagram > ![ERD Diagram](docs/database/mpd/ERD.svg) From 4157a28756cb500e6d53eba03b2874b472208695 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:16:46 +0200 Subject: [PATCH 10/16] docs: Clarify database diagrams docs and fix typos --- CONTRIBUTING.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a3b2fa..fe8922a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -356,10 +356,12 @@ Do not use an underscore as the first character. The *MCD diagram* is part of the *Merise* methodology and shows the entities and relationships without the (database) technical details. -This is a high-level **business-domain** oriented diagram +It is a high-level **business-domain** oriented diagram that shows the **data (entities)**, their **relationships** and **cardinalities**, with **NO technical and implementation details**. +**Learn-dev MCD Diagram**: + > ![MCD](docs/database/mcd/learn-dev.svg) @@ -376,25 +378,31 @@ It is a transformed version of the MCD where: - `N..N` relationships become junction tables, - `1..1` relationship become foreign key. -The *MLD* is shared domain experts, database administrators, +The *MLD* is shared by domain experts, database administrators, and application developers. -*Domain experts* can check that the relational structure captures the business correctly. -*Application developers* can start creating the entities (and database admins) -can create the migration scripts. +*Domain experts* can verify that the relational structure accurately reflects +the business. +*Application developers* can then start creating the entities +while database adminstrators can create the migration scripts. + +**Learn-dev MLD Diagram**: > ![MLD](docs/database/mld/learn-dev_mld.svg) #### MPD Diagram -*MPD* stands for The *MPD* diagram -> ![MPD](docs/database/mpd/learn-dev_mpd.svg) +*MPD* stands for Modèle Physique des Données (Physical Data Model). + +**Learn-dev MPD Diagram**: + +> TODO: ![MPD](docs/database/mpd/learn-dev_mpd.svg) #### ERD Diagram -> ![ERD Diagram](docs/database/mpd/ERD.svg) +> TODO: ![ERD Diagram](docs/database/mpd/ERD.svg) > [!NOTE] From f63ae45c3ec890202003452323f9454f984db841 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:19:41 +0200 Subject: [PATCH 11/16] docs: Fix MLD description --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe8922a..8277e7f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -378,12 +378,10 @@ It is a transformed version of the MCD where: - `N..N` relationships become junction tables, - `1..1` relationship become foreign key. -The *MLD* is shared by domain experts, database administrators, -and application developers. +The *MLD* is shared by domain experts and application developers. *Domain experts* can verify that the relational structure accurately reflects the business. -*Application developers* can then start creating the entities -while database adminstrators can create the migration scripts. +*Application developers* can then start creating the entities. **Learn-dev MLD Diagram**: @@ -394,6 +392,8 @@ while database adminstrators can create the migration scripts. *MPD* stands for Modèle Physique des Données (Physical Data Model). +Database administrators use it to create the migration scripts. + **Learn-dev MPD Diagram**: > TODO: ![MPD](docs/database/mpd/learn-dev_mpd.svg) From 5f2eea8c4ffdbfcb800469e9e6b2dc11b11dc026 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:25:13 +0200 Subject: [PATCH 12/16] docs: Move "Database Schema" section --- CONTRIBUTING.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8277e7f..43d5c0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -327,17 +327,6 @@ The main advantages in my opinion are: The *learn-dev* platform uses a **PostgreSQL** relational database to persist entities. -#### Database Schema - -This section describes the data model using the progressive 3 diagrams -(MCD, MLD, and MPD) from the Merise methodology. -This gives a view from high-level conceptual (MCD), logical (MLD) to -physical (MPD) with all the database details. -- **MPD**: This diagram is aimed at database administrators and application developers. - It is exhaustive and database-specific. It contains all the tables, fields, keys, - database-specific data types, and constraints... - It can be used to implement the data model in the database. - #### Database Naming Conventions @@ -350,6 +339,15 @@ Here are the naming conventions for the **name** of our database **tables**: Do not use an underscore as the first character. + +#### Database Schema + +This section describes the data model using the progressive 3 diagrams +(MCD, MLD, and MPD) from the Merise methodology. +This gives a view from high-level conceptual (MCD), logical (MLD) to +physical (MPD) with all the database details. + + #### MCD Diagram *MCD* stands for 🇫🇷 **Modèle Conceptuel de Données** (Conceptual Data Model). @@ -392,6 +390,13 @@ the business. *MPD* stands for Modèle Physique des Données (Physical Data Model). +This diagram is exhaustive and database-specific. +It contains all the tables, fields, keys, +database-specific data types, and constraints... + +It is aimed at database administrators and application developers. +It can be used to implement the data model in the database. + Database administrators use it to create the migration scripts. **Learn-dev MPD Diagram**: @@ -399,7 +404,6 @@ Database administrators use it to create the migration scripts. > TODO: ![MPD](docs/database/mpd/learn-dev_mpd.svg) - #### ERD Diagram > TODO: ![ERD Diagram](docs/database/mpd/ERD.svg) From 8d2a840820973376bc4d5a2b6618b91632082a8b Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:30:21 +0200 Subject: [PATCH 13/16] docs: Remove a note about frontend naming convention --- CONTRIBUTING.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43d5c0a..ab4a74f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -307,13 +307,7 @@ The main advantages in my opinion are: `client` (adapter for an external service) - `extension` refers to the file extension such as `ts` -> [!TIP] -> **FRONTEND** naming convention: -> -> If the file's default export is a **React component** — use **[PascalCase](http://c2.com/cgi/wiki?PascalCase)**. -> For everything else — use **[camelCase](https://wiki.c2.com/?CamelCase)**. - - + > [!NOTE] > **What are `PascalCase` and `camelCase`?** > @@ -388,15 +382,13 @@ the business. #### MPD Diagram -*MPD* stands for Modèle Physique des Données (Physical Data Model). +*MPD* stands for 🇫🇷*Modèle Physique des Données* (Physical Data Model). This diagram is exhaustive and database-specific. It contains all the tables, fields, keys, -database-specific data types, and constraints... - +database-specific data types, and constraints... It is aimed at database administrators and application developers. It can be used to implement the data model in the database. - Database administrators use it to create the migration scripts. **Learn-dev MPD Diagram**: From 6bb5093f7555b4b32140200d53fb51a020056ec9 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:35:54 +0200 Subject: [PATCH 14/16] docs: Add a description for snake_case naming --- CONTRIBUTING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab4a74f..7ec1936 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -309,12 +309,17 @@ The main advantages in my opinion are: > [!NOTE] -> **What are `PascalCase` and `camelCase`?** +> **What are `PascalCase`, `snake_case`, and `camelCase`?** > > - **[PascalCase](http://c2.com/cgi/wiki?PascalCase)** is a naming convention where the first letter of every word - > is capitalized, with no spaces or underscores between words: `YouTubeEmbed`. -> - **[camelCase](https://wiki.c2.com/?CamelCase)** is a naming convention where the first word starts with a lowercase - > letter and each subsequent word begins with an uppercase letter, with no spaces or underscores: `useJuryVote`. + > is capitalized, with no spaces or underscores between words such as `YouTubeEmbed`. +> - **[snake_case](https://en.wikipedia.org/wiki/Snake_case)** +> is a naming convention where words are lowercase and separated +> with underscores (`_`), such as `first_name`. +> - **[camelCase](https://wiki.c2.com/?CamelCase)** is a naming convention +> where the first word starts with a lowercase letter and each subsequent +> word begins with an uppercase letter, with no spaces or underscores +> such as `useJuryVote`. #### Database From bf27d600e3f9d6af426aafbe609edd46d4dc8789 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:58:52 +0200 Subject: [PATCH 15/16] chore(docs): require TBLS_DSN and update tbls install docs --- Makefile | 3 ++- README.md | 12 ++++++++---- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 99ea313..41fdf99 100644 --- a/Makefile +++ b/Makefile @@ -38,7 +38,8 @@ mld: mpd: @echo "Generating MPD from PostgreSQL Database..." @mkdir -p docs/database/mpd - tbls docs/database/mpd --force + @test -n "$(TBLS_DSN)" || (echo "TBLS_DSN is required (e.g., postgres://user:pass@host:5432/dbname)" >&2; exit 1) + tbls doc "$(TBLS_DSN)" docs/database/mpd --force @echo "MPD generated in docs/database/mpd/" # Generate a SQL file to create the database structure (tables, associations) diff --git a/README.md b/README.md index 2642e30..978530a 100644 --- a/README.md +++ b/README.md @@ -100,10 +100,10 @@ This is **optional** if you only need **to run the application**. This is necessary in order to regenerate the MERISE database diagrams (MCD, MLD and MPD) after any changes have been made to the database design. -You will need to install *Python* and some additional Python packages (i.e., libraries and tools): -- `mocodo`: a CLI tool to generate the MCD and MLD database diagrams +You will need to install *Python* and: +- **`mocodo`**: a CLI tool to generate the MCD and MLD database diagrams from a text-file description of the conceptual data model. -- `tbls`: a CLI tool to reverse engineer the live database to generate the MPD. +- **`tbls`**: a CLI tool to reverse engineer the live database to generate the MPD. Here is the procedure: @@ -126,7 +126,11 @@ Here is the procedure: ``` - [ ] Install **[tbls](https://github.com/k1LoW/tbls#install)** ```shell - pip install tbls + # On macOS + brew install tbls + + # or any OS with Go installed + go install github.com/k1LoW/tbls@latest ``` ## Configuration From 0e83c98e3e43dde10f531daa2169c7db3ae5c7ac Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Tue, 2 Jun 2026 21:59:24 +0200 Subject: [PATCH 16/16] docs: Fix typos --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ec1936..3bdded7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -343,8 +343,8 @@ Do not use an underscore as the first character. This section describes the data model using the progressive 3 diagrams (MCD, MLD, and MPD) from the Merise methodology. -This gives a view from high-level conceptual (MCD), logical (MLD) to -physical (MPD) with all the database details. +This gives a view from high-level conceptual model (MCD), logical model (MLD) to +physical model (MPD) with all the database details. #### MCD Diagram @@ -373,9 +373,9 @@ It is a transformed version of the MCD where: - entities become tables, - `1..N` relationships become foreign keys, - `N..N` relationships become junction tables, -- `1..1` relationship become foreign key. +- `1..1` relationships become foreign keys. -The *MLD* is shared by domain experts and application developers. +The *MLD* is shared with domain experts and application developers. *Domain experts* can verify that the relational structure accurately reflects the business. *Application developers* can then start creating the entities.