Estrutura do projeto — Começando

Um projeto MAD é um app Laravel padrão — o framework em si vive como package Composer em packages/mad-framework (ou em vendor/mad/framework quando instalado via registry, não como path-repo local) e se registra via service provider, sem reescrever a árvore de diretórios do Laravel. Conhecer os diretórios principais economiza tempo de busca quando você está procurando onde adicionar uma classe, view ou rota.

Esta página reflete a árvore real deste repositório (raiz do projeto consumidor do MAD framework, com path-repo local), não um diagrama genérico — alguns diretórios específicos deste app (ex.: módulos de domínio em app/control/) variam de projeto pra projeto.

Visão geral

meu-projeto/
├── app/                         # Código da aplicação (Laravel padrão + convenções MAD)
│   ├── control/                 # MadComponents (controllers reativos), por domínio
│   ├── Models/                  # Models Eloquent, por domínio (Iam/Log/Comm/Ged/Ai/Sys...)
│   ├── Service/                 # Regras de negócio / integrações, por domínio
│   ├── Http/                    # Controllers e Middleware Laravel "puros" (não-reativos)
│   ├── Console/Commands/        # Comandos Artisan customizados
│   ├── Providers/                # Service providers (AppServiceProvider)
│   ├── madlib/                  # Autoload "files" — aliases globais (ver abaixo)
│   ├── lib/                     # Utilitários (menu builder, ShellViewModel, 2FA, recaptcha)
│   ├── resources/docs/markdown/ # Fonte .md desta documentação (app/resources/docs/markdown/)
│   ├── templates/               # Assets do tema do admin (theme-notch: css/js/themes)
│   ├── images/, output/, tmp/   # Estáticos da app, exports/PDF gerados, scratch
│   └── database/                # Banco SQLite local (quando DB_MAD_DRIVER=sqlite)
├── packages/
│   └── mad-framework/           # O FRAMEWORK em si — Composer path-repo (mad/framework)
│       ├── VERSION              # Versão semver do pacote (lida por Mad\Support\MadFramework)
│       ├── assets/builder-ui/   # JS/CSS fonte dos componentes mad-* (mad.js, mad-ui.css...)
│       └── src/mad/             # PHP do framework — component, form, grid, http, ui, view,
│                                 # routing, database, site, rest, install, filters, chart,
│                                 # sheet, pdv, reconcile, orgchart, Support, ai, mcp...
├── bootstrap/
│   ├── app.php                  # Bootstrap Laravel — registra rotas/middleware/exceptions
│   └── cache/                   # Cache de config/route/event (gerado, gravável)
├── config/                      # app.php, database.php, session.php, mad.php (config do MAD)
├── database/
│   ├── migrations/              # Migrations Laravel — cobrem as 6 conexões lógicas do MAD
│   └── seeders/                 # Seeders (ex.: MadReferenceSeeder usado pelo instalador)
├── public/
│   ├── index.php                # ÚNICO entry point HTTP (front controller do Laravel)
│   ├── lib/                     # Assets MAD publicados (servidos direto, sem build)
│   └── app/lib/include/         # Outros assets publicados (theme, builder-ui)
├── resources/
│   ├── views/                   # Blade — componentes mad-*, telas por domínio, docs-fw/
│   ├── css/, js/                # Entry points do Vite (shell padrão do tema, Tailwind)
│   └── menus/                   # menu.xml e variantes — navegação do admin
├── routes/
│   ├── web.php                  # Rotas do admin (allowlist) — carrega routes/modules/*.php
│   ├── console.php              # Artisan commands inline + Schedule::command(...)
│   ├── install.php              # Rotas do wizard /install (fora do grupo `web`)
│   └── ai.php, channels.php     # Embed do Copilot/IA, autorização de broadcast
├── scripts/                     # Tooling PHP/bash — mad:sync, githooks, export-template...
├── storage/                     # Cache, logs, sessões, views Blade compiladas (gravável)
├── tests/
│   ├── Feature/, Unit/          # PHPUnit
├── lang/                        # Catálogos de tradução (pt-BR, pt-PT, es, en)
├── docs/                        # Docs técnicas do PROJETO (Markdown solto, não confundir
│                                 # com app/resources/docs/markdown/ — fonte desta doc)
├── deploy/                      # Exemplos de systemd/supervisor pro queue worker
├── artisan                      # CLI do Laravel (php artisan ...)
├── composer.json                # path-repo local pro mad/framework + dependências
└── vite.config.js, package.json # Build do shell padrão (Tailwind)

packages/mad-framework/src/mad/ — mapa de namespaces

O pacote declara um PSR-4 por camada (packages/mad-framework/composer.json → autoload.psr-4). Saber o namespace poupa o grep quando você precisa achar uma classe do framework:

Namespace	Diretório	O que vive ali
`Mad\Component`	`src/mad/component/`	`MadComponent` — base dos controllers reativos.
`Mad\Form`	`src/mad/form/`	`MadForm`, validação, campos, upload.
`Mad\Grid`	`src/mad/grid/`	`MadDataGrid` e o pipeline de listagem/export.
`Mad\Ui`	`src/mad/ui/`	Widgets e helpers de UI (`MadMessage`, ações, ícones).
`Mad\Http`	`src/mad/http/`	`MadResponse`, canal MadWire, helpers HTTP.
`Mad\View`	`src/mad/view/`	Compilador Blade dos tags `<mad-*>` e render.
`Mad\Routing`	`src/mad/routing/`	`MadRoutes`, drivers de rota, URLs amigáveis.
`Mad\Database`	`src/mad/database/`	Traits Eloquent, `QuerySource`, registries, guards de ordenação.
`Mad\Security`	`src/mad/security/`	Autenticação, permissões, tenancy.
`Mad\Install`	`src/mad/install/`	`InstallToken`, `EnvWriter`, `InstallSummary` (wizard `/install`).
`Mad\Site`	`src/mad/site/`	Portal público, páginas e Markdown (`MadDocMarkdown`).
`Mad\Rest`	`src/mad/rest/`	Base REST (`ApiResourceController`) e Driver REST.
`Mad\Chart` · `Mad\Calendar` · `Mad\Dashboard`	`src/mad/chart\|calendar\|Dashboard/`	Gráficos, calendário e dashboards.
`Mad\Sheet`	`src/mad/sheet/`	Novo no 5.x — planilha editável (`MadSheet`, `SheetColumn`, compilador).
`Mad\Pdv`	`src/mad/pdv/`	Novo no 5.x — frente de caixa (`MadPdvComponent`, `PdvPayment`, `PdvInstallmentPlan`).
`Mad\Reconcile`	`src/mad/reconcile/`	Novo no 5.x — conciliação (`MadReconcile`, `MatchEngine`).
`Mad\OrgChart`	`src/mad/orgchart/`	Novo no 5.x — organograma (`MadOrgChart` + compilador).
`Mad\Support`	`src/mad/Support/`	Novo no 5.x — utilitários transversais: `MadFramework::version()`, `MadMask`, `MadCnpj`, `ValueFormatter`, `CssUnits`, `BrazilianStates`.
`Mad\Ai` · `Mad\Mcp` · `Mad\Usage`	`src/mad/ai\|mcp\|usage/`	Copilot/agente, servidor MCP e medição de uso/billing.
`Mad\Console`	`src/mad/console/`	Comandos Artisan do pacote (`mad:trace-*`, purga de exports, driver REST).
`Mad\Seek` · `Mad\Filters` · `Mad\I18n` · `Mad\Util`	homônimos	Busca, filtros de grid, tradução e utilitários gerais.

Cuidado com o case do diretório: Mad\Web → src/mad/Web/, Mad\Dashboard → src/mad/Dashboard/ e Mad\Support → src/mad/Support/ usam pasta com inicial maiúscula; o resto é minúsculo. Em macOS (filesystem case-insensitive) errar não quebra local, mas quebra em Linux.

Entry point — public/index.php

Diferente de arquiteturas com múltiplos scripts por tipo de rota, o MAD sobre Laravel tem um único front controller: public/index.php. Toda requisição HTTP passa por ele, que monta a aplicação via bootstrap/app.php e despacha para o roteador do Laravel. A distinção entre "admin reativo", "rota pública" e "API REST" é feita por grupos de rota e middleware dentro de routes/ — não por arquivos PHP separados na raiz.

Camada	Onde mora	Middleware típico
Admin reativo (MadComponent)	`routes/web.php`, prefixo `/app`	`mad.auth` + `mad.permission`
MadWire (partial render)	rota `POST /app/_mad-wire` (registrada pelo `MadServiceProvider`)	`mad.auth`
Portal público	`routes/web.php`, fora do grupo autenticado	conforme a rota — sessão Laravel padrão
Instalador (`/install`)	`routes/install.php`	pilha própria, fora do grupo `web` (roda pré-banco)

app/control/ — MadComponents

Controllers reativos (extends Mad\Component\MadComponent), organizados por domínio em subpastas com namespace App\Control\{Dominio} — ex.: App\Control\Iam\UserForm, App\Control\Docs\MadFrameworkDocs. Autoload PSR-4 (composer.json → "App\\Control\\": "app/control/").

app/control/
├── Iam/        # Identidade — usuários, grupos, papéis, programas, unidades
├── Log/        # Auditoria, request log, dashboard de logs
├── Sys/        # Configurações e telas de sistema
├── Comm/       # Comunicação (chat, correio interno, notificações)
├── Ged/        # Gestão eletrônica de documentos
├── Ai/         # Copilot / agente embutido
├── Builder/    # Telas do builder visual (MadBuilder)
├── Install/    # Componente do wizard /install
└── Docs/       # Esta documentação (MadFrameworkDocs + catálogo)

Esses domínios são os do framework e desta app de referência. Um projeto seu cria os próprios — ex.: app/control/Vendas/PedidoForm.php com namespace App\Control\Vendas.

app/Models/ — Entidades Eloquent

Models Eloquent puro (Illuminate\Database\Eloquent\Model), namespace App\Models\{Dominio}, cada domínio apontando para uma das 6 conexões lógicas via protected $connection. Ver Banco de dados para a API completa (traits, política de PK, auditoria).

app/Models/
├── Iam/        # User, Group, Role, Program, Unit, Tenant...
├── Log/        # registros de auditoria e billing de IA
├── Comm/       # Notification, mensagens internas
├── Ged/        # documentos, versões, links compartilhados
├── Ai/         # conversas/sessões do agente
├── Mcp/        # tokens e escopo do MCP
└── Concerns/   # traits compartilhados entre models (fora de Mad\Database\Concerns)

app/Service/ — Regras de negócio

Lógica que não cabe num controller nem num model: integrações externas, orquestrações, cálculos complexos. Também organizado por domínio (App\Service\{Dominio}).

app/madlib/ — Aliases globais (autoload files)

Quatro arquivos carregados sempre via composer.json → autoload.files (não PSR-4 — registram um spl_autoload_register lazy, só dispara em classe desconhecida):

Arquivo	O que resolve
`global_models.php`	Nome curto → `App\Models\*` (ex.: `User` em vez de `App\Models\Iam\User`).
`global_services.php`	Nome curto → `App\Service\*`, incluindo nomes legados renomeados.
`global_controls.php`	Basename de tela → `App\Control\*` (usado pelo dispatcher de rota e pelo menu).
`legacy_i18n.php`	Função `_t()` — shim de tradução sobre os catálogos nativos do Laravel em `lang/`.

Conveniência para não escrever use toda hora — mas IDEs e análise estática (PHPStan/Psalm) não enxergam esses aliases. Para autocompletar/análise estática, prefira use App\Models\X; explícito (o que o scaffold do MAD já insere).

app/resources/ — Markdown desta documentação

Não confundir com resources/ na raiz (views Blade do projeto inteiro): app/resources/docs/markdown/{secao}/{slug}.md é onde mora a fonte Markdown das páginas desta documentação — renderizada por Mad\Site\MadDocMarkdown (league/commonmark) e servida pelo catálogo em app/control/Docs/MadFrameworkDocsCatalog.php.

resources/ — Views, CSS/JS e menus

resources/
├── views/
│   ├── components/      # Componentes <mad-*> reutilizáveis (Blade)
│   ├── public/docs-fw/  # Esta documentação (layout, page, pages/{secao}/{slug}.blade.php)
│   ├── shell/           # Casco do tema (login/layout/public/iframe) em Blade
│   └── {dominio}/       # Telas por domínio (iam/, comm/, ged/, ai/, sys/, builder/...)
├── css/, js/             # Entry points do Vite (app.css com Tailwind, app.js)
└── menus/                # menu.xml e variantes — fonte versionada da navegação do admin

routes/ — Rotas

Modelo allowlist, sem catch-all: toda tela do admin precisa de uma linha explícita. routes/web.php é o orquestrador — declara as rotas públicas e universais, e carrega os módulos de conteúdo de routes/modules/*.php. Ver Roteamento para o detalhe completo.

config/application.ini não existe mais

Diferente de versões anteriores do framework, não há application.ini nem qualquer arquivo INI. Configuração é .env + config/*.php, como em qualquer app Laravel — ver Configuração.

Convenções

Convenção	Exemplo
Classes em PascalCase, por domínio	`App\Models\Iam\User`, `App\Control\Comm\MessageForm`
Arquivo = nome da classe	`User.php` declara `class User`
Views em dot notation	`business.produto-form` → `resources/views/business/produto-form.blade.php`
Autoload PSR-4 + classmap + files	`App\` → `app/`, `App\Control\` → `app/control/`, classmap `app/lib/`, files de `app/madlib/`
Model aponta a própria conexão	`protected $connection = 'comm';` no model

Onde adicionar X

O que	Onde
Novo CRUD (admin)	`app/control/{Dominio}/` + `app/Models/{Dominio}/` + `resources/views/{dominio}/`
Página pública	rota em `routes/web.php` (fora do grupo autenticado) + controller em `App\Http\Controllers\` ou um `MadComponent`
Endpoint REST	`App\Http\Controllers\` + rota em `routes/web.php`/`routes/api.php` conforme o projeto
Service / integração externa	`app/Service/{Dominio}/`
Migration	`database/migrations/` — `php artisan make:migration`
Comando Artisan	`app/Console/Commands/`
Componente Blade reutilizável	`resources/views/components/`
Middleware	`app/Http/Middleware/` + registro em `bootstrap/app.php`
Asset estático publicado	`public/` diretamente, ou `resources/css`/`js` + `npm run build` se passa pelo Vite

Próximos passos

Configuração — .env, config/mad.php, conexões e permissões.
Ciclo de requisição — como o request percorre o framework.
Anatomia do MadComponent — estrutura de um componente reativo.
CRUD completo — exemplo end-to-end criando uma tela.