---
name: mcd-mld-designer
description: >-
  Design, document, and maintain database Conceptual Models (MCD) and Logical Models (MLD)
  following strict Merise rules, naming conventions (<DB_TRIGRAM>_<TABLE> and <TBL_TRIGRAM>_<COLUMN>),
  and native Mermaid diagrams rendered in Antigravity and VS Code. Enforces tracking in db/mcd.md
  and db/mld.md, and must be used before any database modification.
---

# MCD & MLD Database Designer

This skill guides the creation, update, and maintenance of relational database architectures using the **Merise methodology** (MCD to MLD) with graphical **Mermaid.js** diagrams that render natively inside Antigravity artifacts and Visual Studio Code Markdown viewers.

---

## ⚠️ Mandatory Pre-Modification Rule

> [!IMPORTANT]
> **No database change may be made without this skill.**
> Before creating tables, adding columns, modifying relationships, writing ORM models, or running database migrations:
> 1. Read and inspect existing schemas in `db/mcd.md` and `db/mld.md`.
> 2. Apply all conceptual (MCD) and logical (MLD) modifications according to this skill.
> 3. Update and persist changes directly in `db/mcd.md` and `db/mld.md`.
> 4. Ensure `AGENT.md` (or `GEMINI.md`) in the project enforces this rule (see [AGENT.md Rule Template](./references/agent-rule-template.md)).

---

## 1. Strict Naming Conventions

All identifiers and data types must be in **UPPERCASE**.

### 1.1 Database Trigram (`<DB_TRIGRAM>`)
- Derived from the database or project name: **first 3 alphanumeric characters**, uppercase, stripped of accents/special characters (or an explicit 3-letter trigram requested by the user).
- *Examples*:
  - Database `ECOMMERCE` ➔ `ECO`
  - Database `INVENTORY` ➔ `INV`
  - Database `HEALTHCARE` ➔ `HEA`

### 1.2 Table Names (`<DB_TRIGRAM>_<NAME_OF_TABLE>`)
- Every table is prefixed with `<DB_TRIGRAM>_` followed by the functional entity name in UPPERCASE.
- *Examples*:
  - `ECO_CUSTOMER`
  - `ECO_ORDER`
  - `ECO_PRODUCT`

### 1.3 Table Trigram (`<TBL_TRIGRAM>`)
- Derived from the functional table name (without the DB prefix): **first 3 characters** of the table name.
- *Examples*:
  - `CUSTOMER` ➔ `CUS`
  - `ORDER` ➔ `ORD`
  - `PRODUCT` ➔ `PRO`
  - `CATEGORY` ➔ `CAT`

### 1.4 Column Names (`<TBL_TRIGRAM>_<NAME_OF_COLUMN>`)
- Every column is prefixed with its table's 3-letter abbreviation.
- *Examples for `ECO_CUSTOMER` (`CUS`)*:
  - `CUS_ID` (Primary Key)
  - `CUS_FIRST_NAME`
  - `CUS_LAST_NAME`
  - `CUS_EMAIL`
  - `CUS_CREATED_AT`

### 1.5 Foreign Keys (`<HOST_TBL_TRIGRAM>_<TARGET_TBL_TRIGRAM>_<COLUMN_NAME>`)
- When Table A references Table B, the foreign key column in Table A is prefixed with `HOST_TBL_TRIGRAM_TARGET_TBL_TRIGRAM_`:
- *Examples*:
  - Table `ECO_ORDER` (`ORD`) referencing `ECO_CUSTOMER` (`CUS`):
    ➔ Foreign Key column: `ORD_CUS_ID`
  - Table `ECO_PRODUCT` (`PRO`) referencing `ECO_CATEGORY` (`CAT`):
    ➔ Foreign Key column: `PRO_CAT_ID`

### 1.6 Associative / Junction Tables (N:M Relationships)
- Use meaningful functional names whenever applicable (e.g. `ECO_ORDER_ITEM`), or concatenation of entities (e.g. `ECO_ORDER_PRODUCT`).
- Table trigram follows the functional name:
  - `ECO_ORDER_ITEM` ➔ Trigram `ITE`
  - Columns: `ITE_ORD_ID` (FK referencing `ECO_ORDER`), `ITE_PRO_ID` (FK referencing `ECO_PRODUCT`), `ITE_QUANTITY`, `ITE_UNIT_PRICE`.
  - Primary Key is composite: `(ITE_ORD_ID, ITE_PRO_ID)`.

---

## 2. File-Based Tracking Architecture

All database artifacts **must** be stored and maintained under the project's `db/` folder:

```text
<project_root>/
├── db/
│   ├── mcd.md       # Conceptual Data Model (Data Dictionary + Mermaid Flowchart MCD)
│   └── mld.md       # Logical Data Model (Relational schema text + Mermaid erDiagram MLD)
├── AGENT.md         # Contains the mandatory rule requiring this skill before DB edits
```

### Protocol for Any Database Edit:
1. **Never edit code or SQL migrations directly** without first updating `db/mcd.md` and `db/mld.md`.
2. **Review `db/mcd.md`**: Update the Data Dictionary, add/modify entities, associations, and cardinalities in the MCD Mermaid flowchart.
3. **Review `db/mld.md`**: Translate MCD updates into relational tables, foreign keys, constraints, and update the MLD Mermaid `erDiagram`.
4. **Synchronize & Document**: Add a changelog entry at the bottom of both `db/mcd.md` and `db/mld.md` detailing the version, date, and changes made.

---

## 3. End-to-End Modeling Workflow

Follow this 4-step sequence whenever modeling or extending a database:

### Step 1: Requirements & Data Dictionary
Extract all entities and properties from user requirements or business domain.
Construct the Data Dictionary table:

| Code Propriété | Libellé / Description | Type | Contraintes | Entité Source |
| :--- | :--- | :--- | :--- | :--- |
| `CUS_ID` | Identifiant client | INT | PK, AUTO_INCREMENT | CUSTOMER |
| `CUS_EMAIL` | Adresse e-mail | VARCHAR(150) | UNIQUE, NOT NULL | CUSTOMER |
| `ORD_ID` | Numéro de commande | INT | PK, AUTO_INCREMENT | ORDER |

*(In English contexts, use English column headers: Property Code, Description, Type, Constraints, Source Entity)*

### Step 2: Conceptual Data Model (MCD)
- Identify **Entities** (Entités) and **Associations** (Relations).
- Define **Merise Cardinalities**:
  - `0,1`: Optional single link (zero or one)
  - `1,1`: Mandatory single link (exactly one)
  - `0,N`: Optional multiple link (zero to many)
  - `1,N`: Mandatory multiple link (at least one)
- Render the MCD using a **Mermaid Flowchart** (`flowchart LR` or `flowchart TD`) compatible with Antigravity and VS Code:
  - Entities as rectangular nodes with attributes.
  - Associations as rounded/oval nodes `((Association))`.
  - Links annotated with cardinalities: `ENTITE_A ---|"1,N"| ASSOC ---|"1,1"| ENTITE_B`.
- Save in `db/mcd.md`.

### Step 3: Logical Data Model (MLD)
Apply the standard Merise transformation rules (see [Merise Rules Reference](./references/merise-rules.md)):
1. **One-to-Many (`1,N` - `1,1` or `0,1`)**:
   - The primary key of the `(0,N)` or `(1,N)` entity migrates into the `(1,1)` or `(0,1)` entity as a foreign key.
   - Named: `<HOST_TRIGRAM>_<TARGET_TRIGRAM>_<COL>` (e.g. `ORD_CUS_ID`).
2. **Many-to-Many (`0,N`/`1,N` - `0,N`/`1,N`)**:
   - The association becomes a junction table `<DB_TRIGRAM>_<NAME>`.
   - Its primary key is composite, formed by foreign keys to both participating entities.
   - Any attributes of the association become columns in this junction table.
3. **Write Relational Schema Text**:
   - Primary Keys are underlined (or indicated with `(PK)`).
   - Foreign Keys are marked with `#` (or `(FK)`).
   - Example:
     ```text
     ECO_CUSTOMER (CUS_ID, CUS_FIRST_NAME, CUS_LAST_NAME, CUS_EMAIL)
     ECO_ORDER (ORD_ID, ORD_DATE, ORD_TOTAL_AMOUNT, #ORD_CUS_ID)
     ECO_ORDER_ITEM (#ITE_ORD_ID, #ITE_PRO_ID, ITE_QUANTITY, ITE_UNIT_PRICE)
     ```
4. **Render Mermaid `erDiagram`**:
   - Use standard Mermaid ER syntax with exact table names and typed columns.
   - Save in `db/mld.md`.

### Step 4: Normalization Verification (3NF)
Verify all schemas comply with the 3 Normal Forms:
- **1NF**: All attributes are atomic (no repeating groups or comma-separated lists).
- **2NF**: In 1NF and all non-key attributes are fully functionally dependent on the entire primary key (no partial dependency on part of a composite key).
- **3NF**: In 2NF and no transitive functional dependencies (no non-key attribute depends on another non-key attribute).

---

## 4. Bilingual Support (French / English)

Adapt the vocabulary and documentation language automatically to the language used by the user:
- **French**: Modèle Conceptuel de Données (MCD), Modèle Logique de Données (MLD), Entités, Associations, Cardinalités, Dictionnaire des Données, Clé Primaire (PK), Clé Étrangère (FK).
- **English**: Conceptual Data Model (CDM / MCD), Logical Data Model (LDM / MLD), Entities, Relationships, Cardinalities, Data Dictionary, Primary Key (PK), Foreign Key (FK).

The strict naming conventions (`<DB>_<TABLE>` and `<TBL>_<COLUMN>`) and Mermaid diagram syntax remain strictly enforced regardless of language.

---

## 5. References & Examples

- **[AGENT.md Rule Template](./references/agent-rule-template.md)**: Setup instructions to enforce this skill in `AGENT.md` / `GEMINI.md`.
- **[Merise Transformation Rules](./references/merise-rules.md)**: Detailed formal rules for translating MCD associations to MLD relations.
- **[Mermaid Diagram Syntax](./references/diagram-syntax.md)**: Formatting rules and templates for Antigravity & VS Code compatibility.
- **[Complete E-Commerce Example](./examples/ecommerce-sample.md)**: Fully worked example with `db/mcd.md` and `db/mld.md` templates.