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

Seja bem-vindo à TecLoja 02, a versão do nosso e-commerce de tecnologia baseada na stack moderníssima de Python (FastAPI) e Vue 3. Neste módulo de introdução conceitual, estudaremos as bases da Arquitetura Multirepo, desenharemos os fluxos de comunicação assíncrona entre as tecnologias usando diagramas Mermaid e estruturaremos o esqueleto de pastas das duas aplicações independentes.

🏛️ 1. O que é uma Arquitetura Multirepo?

No desenvolvimento de software profissional, é comum mantermos o frontend (SPA) e o backend (API) em repositórios separados do GitHub. Esta estratégia é chamada de Multirepo e traz benefícios valiosos:

  1. Ciclos de Release Independentes: Se precisarmos corrigir um erro visual simples no botão do catálogo do Vue, não precisamos rebuildar ou redeployar a API FastAPI. O frontend atualiza em segundos na Netlify sem encostar no servidor backend.
  2. Especialização de Times: Times de frontend focam exclusivamente no ecossistema JavaScript/TypeScript (Vite, Vue, Linters). Times de backend focam em performance do banco de dados, migrações SQLAlchemy e otimizações Python.
  3. Escalonamento de Infraestrutura Otimizado: A SPA estática do Vue 3 é distribuída de forma ultraveloz em redes de entrega global de conteúdo (Netlify CDN) de baixo custo. A API FastAPI roda em containers dedicados (Render) escalando apenas sob demanda de CPU/Memória.

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

O diagrama abaixo ilustra as interações lógicas dos usuários (Clientes e Administradores) com os limites do sistema TecLoja 02:

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

    subgraph "Limites do Sistema: TecLoja 02"
        UC_Catalogo("🛍️ Visualizar Catálogo e Filtrar Produtos")
        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

Em produção, nossa aplicação roda de forma desacoplada na nuvem. Abaixo, detalhamos o caminho físico de uma requisição web:

flowchart TD
    %% Styling
    classDef client fill:#41b883,stroke:#35495e,stroke-width:2px,color:#fff;
    classDef cdn fill:#00ad9f,stroke:#00796b,stroke-width:2px,color:#fff;
    classDef api fill:#009688,stroke:#004d40,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 Vue 3 Estática)"]:::cdn
    Render["🐳 Render Containers <br> (API FastAPI + Uvicorn)"]:::api
    Neon["🛢️ Neon PostgreSQL <br> (Database Serverless)"]:::db

    Navegador -->|1. Acessa URL Pública| Netlify
    Navegador -->|2. Baixa HTML/JS Compilados| Navegador
    Navegador -->|3. Requisições REST HTTPS com JWT| Render
    Render -->|4. Consultas Assíncronas (asyncpg)| Neon

🚨 O Desafio da Origem Compartilhada (CORS)

Como o frontend do usuário roda em um domínio público (ex: https://tecloja.netlify.app) e tenta requisitar recursos em outro domínio (ex: https://tecloja-api.render.com), o navegador por padrão bloqueia essa comunicação devido à política de mesma origem (Same-Origin Policy).

Para solucionar isso, no Módulo 05 configuraremos o CORS Middleware no FastAPI. Ele injetará cabeçalhos HTTP especiais (Access-Control-Allow-Origin) instruindo o navegador a aceitar requisições vindas explicitamente de nossa URL da Netlify.

📂 4. Estrutura de Pastas de Múltiplos Repositórios

Os estudantes devem criar duas pastas independentes em suas máquinas de desenvolvimento, simulando perfeitamente o ambiente de trabalho de uma grande corporação.

🐍 Repositório 1: tecloja-backend (API Python)

tecloja-backend/
├── app/
│   ├── __init__.py
│   ├── config.py              # Configurações de conexões e segurança JWT
│   ├── main.py                # Ponto de inicialização do FastAPI
│   ├── models/                # Entidades declarativas SQLAlchemy 2.0
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── produto.py
│   │   ├── pedido.py
│   │   └── usuario.py
│   ├── schemas/               # Schemas Pydantic v2 (Padrão DTO)
│   │   ├── __init__.py
│   │   ├── produto_schema.py
│   │   ├── pedido_schema.py
│   │   └── usuario_schema.py
│   ├── repositories/          # Interações diretas com Sessão do DB
│   ├── services/              # Camada de Negócio e Transações
│   │   ├── __init__.py
│   │   ├── produto_service.py
│   │   └── pedido_service.py
│   └── routers/               # APIRouters (REST Controllers)
│       ├── __init__.py
│       ├── produto_router.py
│       ├── pedido_router.py
│       └── auth_router.py
├── alembic/                   # Migrações geradas pelo Alembic
├── alembic.ini                # Arquivo de propriedades do Alembic
├── requirements.txt           # Dependências do Python (FastAPI, SQLAlchemy)
└── Dockerfile                 # Conteinerização de Produção

💚 Repositório 2: tecloja-frontend (SPA Vue 3)

tecloja-frontend/
├── src/
│   ├── assets/                # Imagens e Estilos Globais
│   │   └── styles.css         # Glassmorphism Design System
│   ├── components/            # Componentes reutilizáveis
│   │   ├── Navbar.vue
│   │   ├── ProductCard.vue
│   │   └── AdminProductRow.vue
│   ├── views/                 # Páginas (Views roteadas)
│   │   ├── Catalogo.vue       # Vitrine pública
│   │   ├── Carrinho.vue       # Checkout reativo
│   │   ├── Login.vue          # Entrada de usuários
│   │   ├── admin/
│   │   │   ├── AdminProdutos.vue # Painel de listagem
│   │   │   └── ProdutoForm.vue   # Criação/Edição com validação
│   ├── router/
│   │   └── index.ts           # Roteador lógico do Vue Router
│   ├── composables/           # Estados reativos reutilizáveis (Signal equivalentes)
│   │   ├── useAuth.ts         # Login e token stateless JWT
│   │   └── useCart.ts         # Carrinho computed
│   ├── models/
│   │   └── index.ts           # Interfaces TypeScript (DTOs equivalentes)
│   ├── App.vue                # Componente raiz
│   └── main.ts                # Inicializador do Vue
├── index.html
├── package.json
├── vite.config.ts
└── nginx.conf                 # Configuração para deploy no Nginx/Docker

✅ Pré-Requisitos deste Módulo

Antes de avançar para a criação prática dos diretórios, certifique-se de que seu ambiente possui as ferramentas básicas instaladas executando os seguintes comandos no terminal:

# Verificar se o Python 3.10+ está instalado
python --version

# Verificar se o Node.js 18+ está instalado
node --version

# Verificar se o Git está instalado
git --version

🤔 Por que fizemos assim?

🔍 Checkpoint

  1. Estrutura de Pastas: Crie duas pastas vazias em seu diretório de estudos: tecloja-backend e tecloja-frontend.
  2. Validação de Ambiente: Confirme que os três comandos listados nos Pré-Requisitos retornaram versões válidas e sem erros (ex: Python 3.10.x ou superior, Node v18.x.x ou superior).

⚠️ Erros Comuns

Erro Causa Solução
python ou node não é reconhecido como um comando interno ou externo O binário foi instalado mas seu caminho físico não foi adicionado à variável de ambiente PATH do sistema operacional. Reabra o terminal. Se o erro persistir, reinstale a ferramenta marcando a opção “Add to PATH” ou adicione manualmente nas variáveis de ambiente.
Versão do Node.js inferior a 18 O ambiente possui uma versão antiga (LTS desatualizada) que não suporta os recursos modernos do Vite/Vue 3. Baixe a versão LTS atualizada diretamente do site oficial do Node.js ou utilize o gerenciador de versões nvm.

🏁 Conclusão

Com a arquitetura desenhada e a divisão clara de responsabilidades entre backend (Python) e frontend (Vue), estamos prontos para arregaçar as mangas!

No Módulo 01, focaremos no banco de dados da TecLoja 02. Desenharemos o Modelo Entidade-Relacionamento e programaremos o mapeamento físico através das classes declarativas modernas do SQLAlchemy 2.0, entendendo como chaves estrangeiras, relacionamentos 1:N e tabelas associativas N:M com dados extras funcionam no ecossistema Python.

Voltar para o Sumário