# Estrutura de Diretórios — Mud Sentinel

**Documento:** `arquitetura/04-estrutura-de-diretorios.md`  
**Versão:** 1.0.0  
**Status:** Vigente  
**Nota:** Estrutura **lógica alvo**. Esta etapa não cria código de aplicação — apenas define o layout oficial.

---

## 1. Estratégia de repositório

**Monorepo** contendo apps, módulos de domínio, workers, IaC e documentação.

| Abordagem | Vantagens | Desvantagens | Decisão |
|-----------|-----------|--------------|---------|
| Monorepo | Refactors cross-cutting, versionamento único, docs co-localizadas | Clones maiores; precisa de CI path filters | **Adotado** |
| Polyrepo | Autonomia extrema | Drift de versões, PRs multi-repo | Rejeitado no MVP |

---

## 2. Árvore alvo

```text
mud-sentinel/
├── docs/                          # Documentação oficial (este conjunto)
│   ├── adr/
│   ├── arquitetura/
│   ├── engenharia/
│   ├── governanca/
│   ├── operacao/
│   └── produto/
├── apps/
│   ├── api/                       # FastAPI — composition root HTTP
│   ├── web/                       # Next.js — UI
│   ├── worker/                    # Consumers / jobs
│   └── admin/                     # (opcional) console ops interno
├── modules/                       # Bounded contexts (libraries)
│   ├── shared_kernel/
│   ├── iam/
│   ├── tenancy/
│   ├── catalog/
│   ├── search/
│   ├── graph/
│   ├── ingestion/
│   ├── risk/
│   ├── cases/
│   ├── ai/
│   ├── billing/
│   ├── audit/
│   └── notify/
├── connectors/                    # Plugins de fontes (ingestion)
│   └── <source_name>/
├── packages/                      # Libs transversais não-domínio
│   ├── observability/
│   ├── auth-client/
│   └── config/
├── infra/
│   ├── terraform/
│   ├── k8s/
│   └── docker/
├── scripts/                       # Tooling de DX (sem lógica de negócio)
├── tests/
│   ├── e2e/
│   ├── contract/
│   └── security/
├── .github/ ou .gitlab/           # CI
├── README.md
└── LICENSE / NOTICE
```

---

## 3. Estrutura interna de um módulo (Clean Architecture)

```text
modules/<context>/
├── domain/
│   ├── entities/
│   ├── value_objects/
│   ├── events/
│   ├── repositories/          # interfaces (ports)
│   ├── services/              # domain services
│   └── policies/
├── application/
│   ├── commands/
│   ├── queries/
│   ├── handlers/              # use cases
│   ├── dto/                   # somente bordas internas
│   └── ports/                 # interfaces para infra
├── infrastructure/
│   ├── persistence/
│   ├── messaging/
│   ├── http_clients/
│   └── ...
└── presentation/              # opcional: routers do contexto
    └── http/
```

**Regra de dependência:** `infrastructure` e `presentation` → `application` → `domain`.  
`domain` não depende de ninguém fora de `shared_kernel`.

---

## 4. Apps como composition roots

- `apps/api` apenas **compõe** módulos, middlewares, DI e roteamento.
- Não conter regra de negócio.
- Workers em `apps/worker` igualmente finos: despacham handlers de application.

**Justificativa:** evita “god app” e facilita testar domínio sem subir HTTP.

---

## 5. Documentação vs. código

| Conteúdo | Onde |
|----------|------|
| Visão, ADRs, políticas | `docs/` |
| README de módulo (glossário, API pública) | `modules/<ctx>/README.md` (quando código existir) |
| OpenAPI gerada | artefato de build / `docs/api` versionado se necessário |

---

## 6. Dados e migrações (política)

- Migrações pertencem ao módulo dono das tabelas (`infrastructure/persistence/migrations`) **ou** ao app api com pastas por módulo — escolher um padrão no ADR de persistência e manter.
- **Nenhuma migration nesta fase fundacional.**

---

## 7. Separação marketing × produto

| Superfície | Local sugerido |
|------------|----------------|
| Site marketing / landings | `apps/web` rotas públicas **ou** repositório/site estático separado |
| Core SaaS | `apps/api` + área autenticada em `apps/web` |

Shared hosting (`public_html`) pode servir apenas artefatos estáticos de marketing; runtime do SaaS em ambiente containerizado.

---

## 8. Critérios de aceite da estrutura

Antes do primeiro feature merge:

1. Boundaries de import configurados.
2. Pasta `docs/` completa e linkada no README raiz.
3. Skeleton dos módulos sem lógica de negócio ainda é aceitável; **vazamento de domínio entre pastas não é**.