From d7e0d4c4b75dc74de108c366a5057efb9d5b612f Mon Sep 17 00:00:00 2001
From: VPS 4 Builder <deploy@clube67.com>
Date: Mon, 18 May 2026 00:01:44 +0200
Subject: [PATCH] docs: add custom domains and CNAME routing architecture
 specification

---
 global/arquitetura_dominios_proprios.md | 69 +++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 global/arquitetura_dominios_proprios.md

diff --git a/global/arquitetura_dominios_proprios.md b/global/arquitetura_dominios_proprios.md
new file mode 100644
index 0000000..db7872f
--- /dev/null
+++ b/global/arquitetura_dominios_proprios.md
@@ -0,0 +1,69 @@
+# 🌐 Arquitetura de Domínios Próprios e Subdomínios (Mercado)
+
+Esta especificação define o padrão arquitetural para o provisionamento e roteamento de lojas no ecossistema Clube67, suportando tanto subdomínios nativos quanto domínios próprios de clientes.
+
+---
+
+## 🏛️ 1. Modelo Arquitetural: Multi-Instância Isolada
+
+Em vez de usar uma única aplicação gigante compartilhada (*Shared Database/App*), o ecossistema Clube67 adota um modelo de **Multi-Instância de Tenant Único por Contêiner**:
+
+```text
+Usuário ➔ DNS (Hostinger/Próprio) ➔ Traefik Gateway (VPS 1)
+                                      ├── Loja A (mercadodopovoms.clube67.com) -> Contêineres Loja A (Isolado)
+                                      └── Loja B (mercadodopovo.com)         -> Contêineres Loja B (Isolado)
+```
+
+### Principais Vantagens:
+*   **Isolamento Absoluto**: Se uma loja tiver pico de acessos ou erro no banco, as demais continuam online sem degradação.
+*   **Customização Plena**: Cada loja pode rodar versões específicas de código ou plugins.
+*   **Segurança de Dados**: Bancos de dados fisicamente separados eliminam qualquer risco de vazamento de dados entre clientes.
+
+---
+
+## 🛣️ 2. As Duas Vias de Implantação
+
+Quando um cliente assina o sistema de mercados no Clube67, existem duas vias de roteamento e provisionamento configuradas no `docker-compose.yml` de sua respectiva instância clonada:
+
+### 🔵 Via 1: Subdomínio Padrão (DNS `*.clube67.com`)
+*   **Provisionamento**: A plataforma chama a API da Hostinger e adiciona um apontamento tipo `A` ou `CNAME` para o IP público de produção.
+*   **Configuração Traefik**:
+    ```yaml
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.mercado-loja.rule=Host(`mercadodopovoms.clube67.com`)"
+      - "traefik.http.routers.mercado-loja.entrypoints=websecure"
+      - "traefik.http.routers.mercado-loja.tls.certresolver=letsencrypt"
+    ```
+
+### 🟢 Via 2: Domínio Próprio do Cliente (CNAME / Curinga)
+*   **Ação do Cliente**: O cliente acessa o registrador dele (GoDaddy, Registro.br, etc.) e adiciona:
+    *   Apontamento **CNAME** para `clube67.com` (ou apontamento **A** para o IP público do servidor).
+*   **Configuração Traefik**: O script de automação atualiza o arquivo `docker-compose.yml` da instância clonada do cliente para mapear o novo Host:
+    ```yaml
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.mercado-loja.rule=Host(`mercadodopovoms.clube67.com`) || Host(`mercadodopovo.com`)"
+      - "traefik.http.routers.mercado-loja.entrypoints=websecure"
+      - "traefik.http.routers.mercado-loja.tls.certresolver=letsencrypt"
+    ```
+*   **Emissão de SSL Automática**: O Traefik detecta o novo Host e se comunica automaticamente com o **Let's Encrypt** para gerar e renovar o certificado SSL para o domínio próprio do cliente, com zero complexidade manual.
+
+---
+
+## 🛠️ 3. Roteamento Inteligente de Layout no Frontend (Vite)
+
+Para exibir a identidade visual correta (Cores, Logotipo, Favicon e Descrição), o frontend compilado em Vite realiza a leitura dinâmica do host no carregamento inicial:
+
+1.  **Captura**: O app captura a URL acessada:
+    ```javascript
+    const currentHost = window.location.hostname; // ex: mercadodopovo.com ou mercadodopovoms.clube67.com
+    ```
+2.  **Consulta**: Faz um request para o backend:
+    ```http
+    GET /api/branding/resolve?host=mercadodopovo.com
+    ```
+3.  **Processamento**: O backend local da instância responde com os dados salvos na tabela `branding` para carregar as cores e logo corretos imediatamente.
+
+---
+*Este padrão de design garante escalabilidade e isolamento premium no nível corporativo.*