📚 Módulo 00: Introdução, Arquitetura Multirepo e Visão Geral

Seja bem-vindo à TecLoja 03, a versão do nosso e-commerce de tecnologia baseada na stack corporativa de NestJS e React. Neste módulo inicial, estudaremos as bases da Arquitetura Multirepo, desenharemos os fluxos de comunicação e infraestrutura usando diagramas Mermaid e definiremos a estrutura de pastas física de ambos os projetos independentes.

🏛️ 1. O que é uma Arquitetura Multirepo?

No desenvolvimento profissional de software, é uma boa prática separar fisicamente o frontend (SPA) do backend (API) em dois repositórios independentes do GitHub. Esta abordagem, chamada de Multirepo, é altamente recomendada pelas seguintes razões:

  1. Desacoplamento de Deploy: Se modificarmos o texto de um botão na página de produto no React, o deploy na Netlify ocorre de forma instantânea em segundos, sem tocar ou colocar em risco a disponibilidade do servidor NestJS.
  2. Independência de Ambientes: O time de frontend trabalha estritamente no ambiente JavaScript/TypeScript compilado via Vite. O time de backend foca no servidor NestJS, injeção de dependências e mapeamento físico do banco com o Prisma ORM.
  3. Escalonamento Dedicado: A aplicação React estática é empacotada em arquivos HTML/JS/CSS puros e distribuída globalmente via CDN (Netlify) com custo quase nulo e tempo de resposta baixíssimo. A API NestJS roda sob demanda em containers dedicados (Render) escalando processamento sob alta concorrência.

🗺️ 2. Caso de Uso da Aplicação (Use Case Diagram)

O diagrama de casos de uso abaixo mapeia as interações e permissões dos usuários no ecossistema da TecLoja 03:

usecaseDiagram
    actor Cliente as "👤 Cliente (Consumidor)"
    actor Admin as "🔑 Administrador"

    subgraph "Limites da Aplicação: TecLoja 03"
        UC_Catalogo("🛍️ Visualizar Catálogo e Detalhes")
        UC_Carrinho("🛒 Gerenciar Carrinho de Compras")
        UC_Checkout("💳 Finalizar Compra (Checkout)")
        UC_Login("🔐 Autenticação (Login)")
        UC_CRUD("💻 Gerenciar Catálogo (CRUD)")
    end

    Cliente --> UC_Catalogo
    Cliente --> UC_Carrinho
    Cliente --> UC_Checkout
    Cliente --> UC_Login

    Admin --> UC_Login
    Admin --> UC_CRUD

🏗️ 3. Diagrama de Comunicação e Infraestrutura Cloud

Quando implantada em produção, a aplicação segue o fluxo de comunicação entre serviços distribuídos demonstrado abaixo:

flowchart TD
    %% Styling
    classDef client fill:#61dafb,stroke:#20232a,stroke-width:2px,color:#000;
    classDef cdn fill:#00ad9f,stroke:#00796b,stroke-width:2px,color:#fff;
    classDef api fill:#e0234e,stroke:#3b0713,stroke-width:2px,color:#fff;
    classDef db fill:#003545,stroke:#001f29,stroke-width:2px,color:#fff;

    Navegador["💻 Navegador do Usuário"]:::client
    Netlify["🌐 Netlify CDN <br> (SPA React + Vite)"]:::cdn
    Render["🐳 Render Containers <br> (API NestJS)"]:::api
    Neon["🛢️ Neon PostgreSQL <br> (Database Serverless)"]:::db

    Navegador -->|1. Solicita acesso| Netlify
    Navegador -->|2. Carrega bundle estático| Navegador
    Navegador -->|3. Chamadas REST HTTPS com JWT| Render
    Render -->|4. Acesso ao banco com Prisma Client| Neon

🚨 O Desafio do CORS (Cross-Origin Resource Sharing)

Como o React roda no domínio do cliente (ex: https://tecloja.netlify.app) e a API do NestJS roda em outro domínio (ex: https://tecloja-api.render.com), o navegador irá bloquear qualquer requisição HTTP assíncrona por questões de segurança.

Para solucionar esse problema, no Módulo 05 configuraremos o CORS Middleware nativo do NestJS no arquivo main.ts, liberando explicitamente as origens confiáveis e permitindo a troca de tokens de autenticação.

📂 4. Estrutura de Pastas dos Repositórios

Os estudantes devem organizar os dois projetos em pastas completamente independentes no computador de desenvolvimento:

⚙️ Repositório 1: tecloja-backend (API NestJS)

tecloja-backend/
├── src/
│   ├── main.ts                 # Arquivo de inicialização (bootstrap) do NestJS
│   ├── app.module.ts           # Módulo raiz que unifica a aplicação
│   ├── prisma/
│   │   └── prisma.service.ts   # Serviço de conexão com o banco via Prisma Client
│   ├── common/
│   │   └── filters/
│   │       └── http-exception.filter.ts # Filtro global de tratamento de erros
│   ├── categoria/              # Módulo isolado de Categorias
│   │   ├── categoria.module.ts
│   │   ├── categoria.controller.ts
│   │   └── categoria.service.ts
│   ├── produto/                # Módulo isolado de Produtos
│   │   ├── produto.module.ts
│   │   ├── produto.controller.ts
│   │   ├── produto.service.ts
│   │   └── dto/
│   │       ├── criar-produto.dto.ts
│   │       └── atualizar-produto.dto.ts
│   ├── pedido/                 # Módulo de Pedidos e Transações ACID
│   │   ├── pedido.module.ts
│   │   ├── pedido.controller.ts
│   │   ├── pedido.service.ts
│   │   └── dto/
│   │       └── checkout.dto.ts
│   └── auth/                   # Módulo de Autenticação e Guards JWT
│       ├── auth.module.ts
│       ├── auth.controller.ts
│       ├── auth.service.ts
│       ├── jwt.strategy.ts
│       └── roles.guard.ts
├── prisma/
│   ├── schema.prisma           # Modelagem física e mapeamento ORM
│   └── seed.ts                 # Script carregador de dados inicial (Seed)
├── test/                       # Suíte de testes integrados e E2E
├── package.json
├── tsconfig.json
└── Dockerfile                 # Configuração de conteinerização de produção

⚛️ Repositório 2: tecloja-frontend (SPA React)

tecloja-frontend/
├── src/
│   ├── assets/
│   │   └── styles.css          # Design System Glassmorphic em CSS Puro
│   ├── components/             # Componentes reaproveitáveis
│   │   ├── Navbar.tsx
│   │   ├── ProductCard.tsx
│   │   └── AdminProductRow.tsx
│   ├── contexts/               # Gerenciamento de estado global
│   │   └── AuthContext.tsx     # Contexto reativo de login e token JWT
│   ├── hooks/                  # Regras de estado reaproveitáveis
│   │   └── useCart.ts          # Gerenciamento dinâmico do carrinho
│   ├── views/                  # Componentes de página (roteados)
│   │   ├── Catalogo.tsx        # Vitrine de produtos
│   │   ├── Carrinho.tsx        # Tela de checkout e carrinho
│   │   ├── Login.tsx           # Tela de entrada de usuários
│   │   └── admin/
│   │       ├── AdminProdutos.tsx # Listagem de produtos no painel
│   │       └── ProdutoForm.tsx   # Tela de cadastro/edição com validações
│   ├── services/
│   │   └── api.ts              # Configuração do Axios e Interceptor JWT
│   ├── types/
│   │   └── index.ts            # Interfaces TypeScript representando os DTOs
│   ├── App.tsx                 # Elemento de entrada do React
│   └── main.tsx                # Bootstrap do React com Vite
├── index.html
├── package.json
├── vite.config.ts
└── nginx.conf                  # Regras de rotas e rewrites do SPA para Nginx

✅ Pré-Requisitos deste Módulo

Para iniciar a jornada do e-commerce corporativo na stack NestJS + React, certifique-se de possuir:

🤔 Por que fizemos assim?

🔍 Checkpoint

  1. Ambiente Inicializado: Execute node -v e npm -v no seu terminal e verifique se as ferramentas estão devidamente instaladas e nas versões corretas.
  2. Diretórios do Projeto: Crie duas pastas separadas em seu computador: /tecloja-backend e /tecloja-frontend para servir de base física para cada um dos repositórios independentes do projeto.

⚠️ Erros Comuns

Erro Causa Solução
Criar uma única pasta e misturar os arquivos do NestJS com os arquivos do React Falta de divisão clara dos papéis de frontend e backend em pastas independentes no disco. Garanta que os diretórios tecloja-backend e tecloja-frontend estejam criados de forma paralela (lado a lado) e não um dentro do outro.
O navegador bloqueia requisições locais feitas pelo React para o NestJS O mecanismo de segurança CORS do navegador barrou a comunicação pois os domínios/portas locais diferem. Lembre-se de que no Módulo 05 ativaremos o CORS explicitamente no backend usando o método app.enableCors().
Comandos de inicialização de projetos (como npm install) gerando erros de permissão ou conexão Proxy corporativo bloqueando requisições HTTPS ou privilégios de administrador insuficientes no sistema. Execute o terminal como Administrador ou configure as diretivas de proxy do npm via terminal, utilizando npm cache clean --force se necessário.

🏁 Conclusão

Com o design conceitual consolidado e as estruturas organizadas, o aluno possui o mapa para iniciar as codificações práticas.

No Módulo 01, nos aprofundaremos na modelagem do banco de dados da TecLoja 03. Desenharemos o diagrama ERD em Mermaid e escreveremos as definições físicas das tabelas no arquivo schema.prisma utilizando o moderno ecossistema declarativo do Prisma ORM.

Voltar para o Sumário