O que de fato existe dentro de um app criado com IA: um tour para não-desenvolvedores

Você digitou uma descrição, apertou começar e, vinte minutos depois, tinha um app funcionando. Ótimo. Mas agora você clicou em “ver arquivos” e está encarando uma árvore de pastas que parece ter sido escrita em outra língua. O que é o package.json? Por que tem quarenta coisas em node_modules? O que significa “schema” e por que você tem um?

Este post é um tour guiado. Não um tutorial — um tour. Depois de lê-lo você não vai saber escrever nenhum desses arquivos sozinho, mas na próxima vez que algo parecer estranho, você vai saber para qual canto do app apontar.

Vou usar três exemplos ao longo do texto, para que as partes abstratas tenham algo concreto a que se prender:

• Maya, uma líder de marketing, que construiu um ranking de indicações para a equipe dela.
• Jordan, um professor de yoga, que construiu um site de agendamento de aulas.
• Sam, que toca uma padaria, que construiu uma página de “pré-encomende os croissants de amanhã”.

Os três usaram um criador de apps com IA. Os três apps parecem completamente diferentes para um cliente. Por baixo do capô, eles têm um formato surpreendentemente parecido.

O frontend: o que o seu cliente de fato vê

O frontend é tudo o que carrega no navegador de alguém. Botões, layouts, fontes, animações, o jeito como um formulário se limpa depois que você envia. Se você consegue ver, é frontend.

Para a Maya, o frontend é um ranking com posição, nome e número de indicações. Para o Jordan, é um calendário de aulas com um botão de “agendar”. Para o Sam, é uma lista de doces com botõezinhos de mais e menos ao lado de cada um.

Dentro do projeto, o frontend em geral vive numa pasta chamada algo como app/, pages/ ou src/. Você vai ver arquivos que terminam em .tsx ou .jsx. Cada um é, grosso modo, “uma tela” ou “um pedaço de uma tela”. A linha do ranking é um arquivo. O cabeçalho é outro arquivo. A página que amarra tudo é um terceiro.

Quando você pede ao criador de apps com IA para “deixar os botões mais arredondados” ou “mover o ranking para a direita”, é esta a parte que muda.

O backend: a parte que pensa

O backend é a parte que ninguém vê, mas de que todo mundo depende. É o código que roda em outro lugar — num servidor, não no navegador do cliente — quando algo precisa acontecer que não dá para confiar que o navegador do cliente faça sozinho.

Por que o navegador não pode fazer tudo? Porque o navegador é a máquina do cliente, e você não pode confiar nele. Se o ranking da Maya atualizasse as contagens de indicação puramente no navegador, qualquer um poderia clicar com o botão direito e adicionar 9.000 indicações para si mesmo. Então o backend é onde as regras vivem: “esta pessoa pode fazer isto, mas não aquilo”, “salve isto de verdade no banco de dados”, “envie este e-mail”.

O backend em geral vive numa pasta chamada api/, server/ ou app/api/. Os arquivos ali costumam ser curtos. Cada um trata de uma requisição específica: “criar um agendamento”, “listar os croissants de hoje”, “adicionar uma indicação”.

Quando algo funciona no seu app mas o resultado não cola — você clica em enviar, vê uma confirmação, mas amanhã os dados sumiram — o backend é quase sempre onde está o bug.

O banco de dados: a memória do seu app

Imagine a memória do seu app como uma fileira de arquivos de gaveta. Cada arquivo tem um rótulo na frente. Um diz “usuários”. Um diz “agendamentos”. Um diz “pedidos_de_croissant”. Dentro de cada arquivo, cada gaveta é uma linha. Cada gaveta tem o mesmo conjunto de espaços: um nome, um e-mail, um created_at, um status.

Essa estrutura — “quais arquivos existem, quais espaços cada linha tem” — se chama schema. É o arquivo mais importante do projeto, mesmo sendo provavelmente o mais sem graça de se ver. Encontre um arquivo chamado schema.ts, schema.prisma, ou algo dentro de uma pasta chamada db/ ou migrations/. Abra-o. Você vai ver uma lista que espelha o que o seu app de fato lembra sobre o mundo.

O schema do Jordan tem uma tabela classes, uma tabela bookings e uma tabela users. O do Sam tem products, orders e order_items. O da Maya tem members e referrals. O formato do schema é o formato do produto, e é por isso que mudá-lo depois é mais difícil que mudar a cara dos botões.

Um truque útil: se você consegue descrever o que o seu app lembra, em palavras simples, você em geral consegue descrever o schema. “Eu lembro o nome e o e-mail de cada cliente. Para cada cliente, eu lembro os pedidos que ele fez. Para cada pedido, eu lembro quais doces e quantos de cada.” Essa frase é, quase palavra por palavra, o schema.

Auth: o segurança na porta

“Auth” é duas palavras grudadas: autenticação (quem é você?) e autorização (o que você pode fazer?). As duas em geral são tratadas por um pequeno conjunto de arquivos numa pasta chamada auth/, ou por um serviço cujo nome você talvez reconheça: Clerk, Auth0, Supabase Auth, NextAuth.

As duas perguntas são diferentes. A autenticação responde: “isto é mesmo a Maya?” — em geral com uma senha, um login do Google ou um link mágico enviado por e-mail para ela. A autorização responde: “a Maya pode apagar as indicações de outras pessoas?” — e a resposta honesta para a maioria dos apps criados com IA na primeira semana é “esquecemos de verificar”.

Esta é a parte que mais costuma estar quietamente quebrada. A tela de login funciona, então parece segura. Mas o backend nem sempre está verificando se a pessoa logada é a mesma pessoa cujos dados ela está tentando ler. Se o seu app tem qualquer noção de “meus dados vs seus dados”, peça ao criador de apps com IA explicitamente: “Garanta que os usuários só possam ver e editar os próprios dados.” Você vai se surpreender com a frequência com que essa única frase revela uma verificação faltando.

Integrações: as coisas que você não construiu mas está usando mesmo assim

É aqui que a maioria dos não-desenvolvedores subestima o que de fato está acontecendo. A coisa que envia o e-mail de “os seus croissants estão prontos” do Sam não é código — é uma conta no SendGrid ou no Resend. A coisa que processa o pagamento das aulas do Jordan não é código — é o Stripe. A coisa que hospeda as fotos no ranking da Maya não é código — é um serviço de armazenamento como o S3 ou o Cloudinary.

Cada integração aparece em dois lugares. Há um pequeno trecho de código no backend que diz “ei, Stripe, cobre este cartão”. E há uma chave — uma longa string secreta — armazenada em algum lugar seguro (em geral um arquivo chamado .env que ninguém jamais deveria commitar) que prova ao Stripe que a requisição veio da padaria do Sam e não de um estranho.

Se você um dia se perguntar por que o seu app de repente para de enviar e-mails ou para de aceitar pagamentos, a causa quase sempre é uma de: uma chave expirada, um limite de uso atingido ou uma mudança nas políticas da integração. O código não quebrou. O aperto de mão quebrou.

O deploy: como ele chega à internet

A peça final é a parte que transforma a pasta no seu disco numa coisa que o seu cliente pode visitar numa URL. Isso em geral significa três coisinhas trabalhando juntas:

• O host: um serviço como Vercel, Netlify, Fly ou Render que roda o seu backend e serve o seu frontend.
• O domínio: um nome como ranking-da-maya.com que aponta para o seu host.
• O build: a receita que pega os seus arquivos-fonte bagunçados e os transforma na versão mais enxuta e rápida que de fato roda.

Quando algo funciona localmente mas quebra em produção, o problema em geral está aqui. Uma chave definida no seu notebook mas não no host. Uma biblioteca instalada em desenvolvimento mas não em produção. Um banco de dados que existe no seu navegador mas não no site ao vivo.

O hábito de cinco minutos que se paga

Você não precisa ler cada arquivo do seu projeto. Você não precisa saber o que a maioria deles faz. Mas você deveria, uma vez por semana, fazer uma passada de cinco minutos em que abre cada uma das pastas acima e pergunta ao criador de apps com IA, em palavras simples, o que mudou.

A Maya faz isso toda sexta à tarde. Ela digita: “O que mudou no schema esta semana, e por quê?” E: “Há alguma integração nova neste app que eu não pedi?” As respostas quase sempre são tranquilizadoras. As poucas vezes em que não são, ela pega os problemas enquanto ainda são pequenos.

É esse o ponto inteiro de entender as partes. Não para virar um desenvolvedor. Só para conseguir fazer perguntas melhores.

Para onde ir a seguir

Se este tour ajudou, dois textos complementares valem o seu tempo. O bug do ‘parece estar tudo bem’ cobre o que fazer quando uma dessas partes está quietamente quebrada, e pronto para demo vs pronto para produção cobre como saber quando o seu app passou do primeiro estágio para o segundo. O mesmo mapa, usos diferentes para ele.