Organograma

Sobre organogramas

Um organograma mapeia a estrutura formal de reporte de uma organização — quem gerencia quem, quais equipes ficam sob quais líderes, e onde se encaixam vagas em aberto e assessores externos. As equipes de RH recorrem a eles durante o planejamento de headcount; fundadores os usam antes de reuniões com o conselho; gerentes de operações os distribuem durante reestruturações. Ao contrário de um fluxograma genérico, um organograma trata pessoas (e cargos) como as entidades primárias, com a hierarquia codificada por indentação ou arestas explícitas.

O Schematex segue as convenções gerais de organograma com extensões para cargos em aberto/não preenchidos, reporte matricial (linha pontilhada) e relacionamentos de assessoria. Não há um padrão ISO único para organogramas; as convenções implementadas aqui são derivadas da prática de RH e normas do setor de software. Para o contexto acadêmico autoritativo, consulte Fayol (1916) e o artigo da Wikipedia sobre organogramas.

1. Seu primeiro organograma

O menor organograma útil: uma hierarquia de três níveis com um cargo em aberto.

Quatro regras cobrem 80% dos casos:

1. Comece com a palavra-chave orgchart, opcionalmente seguida de um título entre aspas.
2. Cada pessoa é um nó — id: "Nome" | "Cargo" | "Departamento" [props]. O | separa os campos de nome, cargo e departamento.
3. A indentação determina a hierarquia — cada dois (ou mais) espaços extras move um nó um nível mais fundo sob o nó menos indentado mais próximo acima dele.
4. Declare cargos em aberto com open id: ou draft id:, e assessores externos com advisor id:.

Os comentários devem começar com # em sua própria linha (o // inline no final da linha também é removido).

2. Nós

Uma linha de nó tem a forma [tipo] id: campos [props]. O id deve corresponder a [A-Za-z][A-Za-z0-9_-]*.

2.1 Campos (separados por pipe)

A parte após : e antes do bloco opcional [props] é dividida em |:

alice: "Alice Zhang"                                # apenas nome
alice: "Alice Zhang" | "VP Engineering"             # nome + cargo
alice: "Alice Zhang" | "VP Eng" | "Platform"        # nome + cargo + departamento
alice: "Alice Zhang" | "VP Eng" | "Platform" | "x@co.com"  # + linha de informação

2.2 Tipos de nó

A palavra-chave de tipo opcional antes do id muda como o nó é renderizado:

2.3 Propriedades dos nós

As propriedades ficam em [chave: valor, …] no final de uma linha de nó.

Ícones de função — o valor de role: resolve para um ícone de exibição. Palavras-chave aceitas (sem distinção de maiúsculas/minúsculas):

3. Hierarquia

A hierarquia é expressa por indentação — o padrão mais comum. Cada nó se torna filho do nó mais próximo acima dele com uma indentação menor. Tabulações são tratadas como dois espaços.

ceo: "CEO"
  cto: "CTO"           # filho de ceo (indent 2)
    eng: "Engineer"    # filho de cto (indent 4)
  cfo: "CFO"           # filho de ceo (indent 2, mesmo nível que cto)

Como alternativa, use a propriedade reports: para definir um pai explicitamente, independentemente da indentação:

orgchart "Flat file"
ceo: "CEO"
cto: "CTO" [reports: ceo]
eng: "Engineer" [reports: cto]

4. Arestas

Existem dois tipos de arestas. A maioria das linhas de reporte vem automaticamente da hierarquia de indentação. Você também pode escrevê-las explicitamente — ou adicionar linhas matriciais (pontilhadas).

Arestas explícitas requerem que ambos os ids de nó já estejam declarados. Uma aresta report criada explicitamente não é duplicada se o mesmo relacionamento já estiver implícito pela indentação.

Rótulos de arestas são suportados:

pm1 -.-> design [label: "product partnership"]

5. Configuração

Linhas config: ajustam o layout e a orientação. Cada uma vai em sua própria linha.

Notas sobre layout:

• tree — árvore hierárquica padrão com conectores ramificados. Melhor para a maioria dos organogramas.
• list / directory / compact — visualização de diretório indentado compacto. Bom para listas grandes de headcount onde a ramificação em árvore se torna complicada.

Layout em árvore (padrão) — cartões de avatar com conectores ramificados e codificação de cor por departamento. Melhor para equipes com até ~30 pessoas.

Layout em lista — linhas de diretório compactas com guias de indentação. Melhor para equipes grandes onde a ramificação em árvore se torna complicada.

6. Rótulos e comentários

• Título: orgchart "Acme Corp" — somente na primeira linha.
• Campo de nome: primeiro campo delimitado por pipe após o dois-pontos; pode ser entre aspas ("Alice Zhang") ou sem aspas (Alice).
• Campos de cargo/departamento: segundo e terceiro campos delimitados por pipe.
• Linha de informação: quarto campo delimitado por pipe, ou definido via props note:, email:, phone: ou location:. O primeiro encontrado prevalece.
• Comentários: # no início de uma linha (após espaço em branco inicial). O // inline também é removido.

7. Palavras reservadas e escape

Reservadas no início da linha: orgchart (cabeçalho), config:, role, open, draft, tbh, advisor, external.

Tokens de operador reservados — evite estas sequências dentro de ids: ->, -.->.

Regras de ID: deve corresponder a [A-Za-z][A-Za-z0-9_-]*. Nomes com espaços vão no campo de nome entre aspas, não no id.

Strings com espaços em valores de props (ex.: department: "Platform Eng") devem ser entre aspas duplas.

8. Erros comuns

9. Gramática (EBNF)

document       = header (blank | comment | config | edge | node)*

header         = "orgchart" ( WS quoted-string )? NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

config         = "config" WS ":" WS key WS "=" WS value NEWLINE
key            = "direction" | "layout"

node           = INDENT* kind? id ":" WS fields ( "[" node-attrs "]" )? NEWLINE
kind           = "role" | "open" | "draft" | "tbh" | "advisor" | "external" | "person"
fields         = field ( "|" field )*
field          = quoted-string | unquoted-text
node-attrs     = node-attr ("," node-attr)*
node-attr      = "role:" role-keyword
               | "icon:" role-keyword
               | "department:" text
               | "status:" ( "new" | "leaving" | "on-leave" )
               | "avatar-color:" quoted-hex
               | "gender:" ( "male" | "female" )
               | "note:" text
               | "email:" text
               | "phone:" text
               | "location:" text
               | "assistant-of:" id
               | "matrix:" id-list
               | "reports:" id
               | bare-flag

bare-flag      = "open" | "draft" | "tbh" | "external"

edge           = id WS edge-op WS id ( "[" edge-attrs "]" )? NEWLINE
edge-op        = "->" | ".->"  // -.-> for matrix
edge-attrs     = "label:" quoted-string

id             = [A-Za-z] [A-Za-z0-9_-]*
comment        = ( "#" | "//" ) any NEWLINE

Fonte autoritativa: src/diagrams/orgchart/parser.ts. Se houver divergência com o parser, o parser prevalece — por favor, abra uma issue.

10. Roadmap

Planejado — ainda não analisável pelo parser. Não use estes itens em DSL gerada hoje; o parser irá rejeitá-los ou armazená-los como propriedades personalizadas não utilizadas.

• Renderização visual de assistant-of: — a propriedade é analisada e armazenada na AST, mas o renderizador ainda não desenha o conector de cotovelo do assessor.
• Config coloring — temas de cores baseados em departamento (coloring: department).
• Tamanhos de compact em config — controle explícito do tamanho do cartão (size: small | medium | large).
• span: de largura de nó — expansão de um nó por múltiplas colunas irmãs no layout em árvore.
• URL de foto / avatar — avatar: "https://…" para exibir uma foto real.
• Exportação para formatos HRIS — saída estruturada em JSON/CSV junto com o SVG.

Acompanhe nas issues do GitHub se você precisar de algum desses recursos mais cedo.

Exemplos relacionados

Cenários prontos para uso da galeria de exemplos: