# Arquitetura do Projeto

## Objetivo da fase

Esta macrofase consolida a fundacao tecnica do stack desacoplado:

- `cms/` como origem privada de conteudo e configuracao.
- `api/` como fronteira publica versionada entre CMS e consumidores.
- `front-end/` como superficie publica indexavel e substituivel.

O foco aqui e estrutural: instalar, endurecer e documentar o baseline para que as fases seguintes implementem CRUD, workflow editorial, API real e experiencias mais completas sem revisitar as decisoes de base.

## Separacao de camadas

### `cms/`

- Responsavel por instalacao, sessao administrativa, configuracao, persistencia MySQL e futuros fluxos de autoria.
- `cms/install/` executa o bootstrap inicial do ambiente: checagem de requisitos, provisionamento MySQL, schema minimo, admin inicial, escolha do `project_mode`, reserva do `admin.path` e geracao de `config.php`.
- A conclusao do instalador grava tambem `cms/config/install.lock`, invalida a sessao temporaria e inutiliza reentradas futuras no fluxo de setup.
- `cms/public/` permanece privado e nao descobrivel; enquanto nao houver painel real, responde `404` generico com `noindex`, exceto no `admin.path` reservado, que devolve uma pagina privada de bootstrap pendente.
- `cms/core/` guarda bootstrap compartilhado, conexao ao banco, sessao e servicos transversais.
- `cms/modules/` reserva os bounded contexts operacionais: conteudo, midia, taxonomias, settings, usuarios, migracao e SEO.

### `api/`

- Superficie publica somente-leitura em `/api/v1`.
- Contrato formal documentado em [docs/contracts/api-v1.md](./contracts/api-v1.md).
- Camada de transformacao CMS -> payload externo documentada em [docs/contracts/cms-transform-layer.md](./contracts/cms-transform-layer.md).
- Deve depender apenas do banco/configuracao necessarios para leitura e nunca compartilhar a sessao administrativa do CMS.
- Middlewares de CORS, rate limiting, cache, autenticacao de integracoes e observabilidade operacional existem como pontos de extensao desta fase; a implementacao detalhada segue nas issues filhas.

### `front-end/`

- Cliente publico desacoplado que consome a API por contrato, nunca acessando o banco nem includes do CMS.
- Guarda apenas configuracao publica em `front-end/config/`.
- Publica o shell indexavel em `front-end/public/`, com fallback para `index.html`, roteamento cliente e hidratacao exclusiva via `/api/v1`.
- O padrao normativo do shell, das rotas publicas e do consumo da API esta em [docs/front-end-public-shell.md](./front-end-public-shell.md).

## Fluxo de bootstrap do ambiente

1. Operador acessa `cms/install/` em um ambiente privado.
2. O instalador valida runtime, extensoes e permissoes de escrita.
3. O instalador provisiona o banco MySQL, cria schema minimo e semeia o primeiro `super_admin`.
4. O instalador grava `cms/config/config.php` fora do versionamento e cria o lock pos-instalacao.
5. `cms/public/` continua privado ate a fase de painel funcional; `api/` e `front-end/` seguem usando o contrato desacoplado.

## Fronteiras de seguranca

- Todo entrypoint privado (`cms/install/`, `cms/public/`) recebe `X-Robots-Tag: noindex`, `no-store`, `DENY`, `nosniff` e CSP restritiva.
- O frontend e a unica superficie indexavel.
- O banco MySQL e compartilhado entre camadas apenas por contrato de dados; nao ha acoplamento de sessao entre CMS e API publica.
- `config.php` permanece ignorado no Git e passa a existir apenas por instalacao.

## Artefatos normativos desta fase

- [docs/security-baseline.md](./security-baseline.md)
- [docs/seo-baseline.md](./seo-baseline.md)
- [docs/seo-operational-model.md](./seo-operational-model.md)
- [docs/mysql-foundation.md](./mysql-foundation.md)
- [docs/contracts/api-v1.md](./contracts/api-v1.md)
- [docs/front-end-public-shell.md](./front-end-public-shell.md)
- [docs/experience-guidelines.md](./experience-guidelines.md)
- [docs/admin-ia-client-flows.md](./admin-ia-client-flows.md)
- [docs/admin-export-migration-flow.md](./admin-export-migration-flow.md)
- [docs/editorial-workflow.md](./editorial-workflow.md)
- [docs/cms-crud-minimo.md](./cms-crud-minimo.md)
- [docs/multi-site-segmentation.md](./multi-site-segmentation.md)

## Desdobramentos esperados

- Fase 3 transforma o `cms/` em painel funcional sobre a fundacao criada aqui.
- Fase 4 implementa a API publica aderente ao contrato e middlewares definidos.
- Issues filhas especializadas refinam autenticacao, transformacao de payload, auditoria, SEO operacional e multi-site sem reabrir a arquitetura-base.