---
id: <ARCH-...|CORE-...>
tipo: arquitetura
onda: 1
status: pendente
unidades: []
fontes: []
depende_de: []
consumidores: []
criticidade: alta
dono:
---

# Arquitetura: <mecanismo>

> Guia: documentar um mecanismo global. O foco é o contrato que ele impõe a todos os
> módulos, não a listagem de arquivos.

## 0. Ficha de identidade

| Campo | Valor |
|---|---|
| Efeito primário | o que passa a existir/valer para todo o sistema |
| Entrada | request, comando, evento, arquivo de configuração |
| Saída | rotas, views, middlewares, tabelas, cache |
| Efeitos colaterais | ordem de boot, custo por request, cache |
| Particularidade central | |
| Como se integra | ponto de extensão e contrato |
| Se removido, quebra | |

## 1. Efeito

> O que o mecanismo garante, em termos observáveis. Ex.: "todo módulo em V2/Modules
> tem rotas `cms.php`, `web.php`, `api.php` registradas automaticamente; views no
> namespace `v2-<slug>`; migrations carregadas".

## 2. Abordagem

### 2.1 Mecânica passo a passo
> Com classes/métodos reais e ordem de execução.

### 2.2 Trechos de código pivô
```php
// V2/Core/...:linha — o que mostra
```

### 2.3 Decisões e restrições
> Por que assim; o que o desenho impede; custo (ex.: varredura de diretórios por boot).

## 3. Particularidades

> Ordem alfabética de módulos; fallback registrado por último; namespaces;
> `refreshNameLookups`; exceções silenciadas; divergências README × código.

## 4. Integrabilidade

### 4.1 Contrato para módulos/serviços
> Estrutura de pastas exigida, arquivos reconhecidos, nomes de namespace, ordem.

### 4.2 Como adicionar/alterar
> Receita passo a passo, com exemplo mínimo completo.

### 4.3 Anti-uso
> O que quebra (ex.: depender da ordem alfabética, registrar rota fora do padrão).

## 5. Inventário

| Arquivo | Papel | Efeito | Fonte |
|---|---|---|---|

## 6. Riscos de reimplementação

## 7. Lacunas

## 8. Checklist de paridade

- [ ] `PC-...-01` — ...

## 9. Evidências consultadas