diagrama-arquitectura

Mermaid Expert para Obsidian

Soy un experto en crear diagramas Mermaid optimizados para renderizar en Obsidian.

Cuando usar esta skill

• Visualizar flujos de datos o procesos
• Documentar arquitectura de sistemas
• Mostrar relaciones entre clases/modulos
• Crear diagramas de secuencia de APIs
• Modelar estados de una maquina de estados
• Documentar esquemas de base de datos

Reglas Criticas para Obsidian

[!IMPORTANT] Obsidian tiene limitaciones con Mermaid. Sigue estas reglas.

Caracteres a EVITAR dentro de nodos []

Evitar	Problema	Solucion
()	Rompe el parser	Mover a etiqueta de flecha o texto externo
: al inicio	Interpretado como directiva	Usar numeros: 1. en lugar de :00
" escapadas	Inconsistente	Usar nodos sin comillas cuando sea posible
<br/>	No siempre funciona	Separar en multiples nodos

Sintaxis segura para nodos

%% CORRECTO - nodos simples
flowchart TD
    A[Inicio] --> B[Proceso]
    B --> C[Fin]

%% CORRECTO - detalles en etiquetas de flechas
flowchart TD
    A[API] -->|POST /users| B[Controller]
    B -->|query| C[Database]

%% INCORRECTO - parentesis dentro del nodo
flowchart TD
    A[raw/ (audios)] --> B[process]

---

Tipos de Diagramas

1. Flowchart (Diagrama de Flujo)

El mas versatil. Usa para arquitectura, pipelines, flujos de datos.

Direcciones:

• TD / TB - Top to Down
• LR - Left to Right
• RL - Right to Left
• BT - Bottom to Top

Formas de nodos:

flowchart TD
    A[Rectangulo] --> B(Rectangulo redondeado)
    B --> C{Rombo - decision}
    C --> D[(Base de datos)]
    C --> E((Circulo))
    E --> F[[Subrutina]]
    F --> G>Flag]

Subgraphs:

flowchart TD
    subgraph Backend
        A[API] --> B[Service]
        B --> C[(DB)]
    end
    subgraph Frontend
        D[React App]
    end
    D --> A

Estilos:

flowchart TD
    A[Nodo con estilo]
    style A fill:#f9f,stroke:#333,stroke-width:2px

---

2. Sequence Diagram (Diagrama de Secuencia)

Para documentar interacciones entre componentes, llamadas API, flujos de autenticacion.

sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant A as API
    participant D as Database

    U->>F: Click login
    F->>A: POST /auth/login
    A->>D: SELECT user
    D-->>A: User data
    A-->>F: JWT token
    F-->>U: Redirect dashboard

Tipos de flechas:

Sintaxis	Significado
->>	Linea solida con flecha
-->>	Linea punteada con flecha
->	Linea solida sin flecha
-->	Linea punteada sin flecha

Bloques:

sequenceDiagram
    participant A as Service A
    participant B as Service B

    loop Cada 5 minutos
        A->>B: Health check
        B-->>A: OK
    end

    alt Si error
        A->>A: Retry
    else Si OK
        A->>B: Continuar
    end

    opt Opcional
        A->>B: Log evento
    end

---

3. Class Diagram (Diagrama de Clases)

Para documentar modelos, schemas, estructuras de datos.

classDiagram
    class User {
        +String id
        +String email
        -String password
        +login()
        +logout()
    }

    class Order {
        +String id
        +Date created
        +calculate_total()
    }

    User "1" --> "*" Order : places

Relaciones:

Sintaxis	Tipo
<|--	Herencia
*--	Composicion
o--	Agregacion
-->	Asociacion
..>	Dependencia

---

4. State Diagram (Diagrama de Estados)

Para maquinas de estado, workflows, ciclos de vida.

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : start
    Processing --> Completed : success
    Processing --> Failed : error
    Failed --> Pending : retry
    Completed --> [*]

---

5. ER Diagram (Entidad-Relacion)

Para schemas de base de datos, modelos de datos.

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : includes

    USER {
        string id PK
        string email UK
        string name
        date created_at
    }

---

6. Git Graph

Para visualizar historial de git, estrategias de branching.

gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "feat-1"
    commit id: "feat-2"
    checkout main
    merge develop id: "v1.0"

---

7. Gantt Chart

Para timelines, planificacion de proyectos.

gantt
    title Proyecto MVP
    dateFormat YYYY-MM-DD
    section Diseno
        Wireframes     :done, d1, 2024-01-01, 7d
        UI Design      :active, d2, after d1, 14d
    section Desarrollo
        Backend API    :d3, after d2, 21d
        Frontend       :d4, after d2, 28d
    section Testing
        QA             :d5, after d4, 14d

---

Flujo de Trabajo

1. Analizar - Entender que se quiere visualizar
2. Elegir tipo - Seleccionar el diagrama mas apropiado
3. Extraer info - Del codigo fuente o descripcion
4. Generar - Codigo Mermaid valido para Obsidian
5. Validar - Revisar caracteres problematicos
6. Insertar - En la nota correspondiente

Ubicaciones en el Vault

Contexto	Ubicacion
Proyecto especifico	02_Proyectos/<proyecto>/
Embebido en doc	Directamente en la nota de documentacion
Conocimiento tecnico	03_Conocimiento/<categoria>/

Buenas Practicas

1. Simplicidad - Maximo 15-20 nodos por diagrama
2. Nombres claros - Nodos descriptivos, sin abreviaturas cripticas
3. Jerarquia - Usar subgraphs para agrupar componentes relacionados
4. Etiquetas - Usar labels en flechas para dar contexto
5. Comentarios - %% para explicar partes complejas
6. Direccion - TD para jerarquias, LR para flujos lineales