Desenvolvimento — Frowexa

Cadeia lógica de módulos e features, documentação de design como bússola, regras e governação de agentes, fragmentação de arquivos, uso consciente do Cursor e racional de stack — o que o produto exige, no processo, não a lista de pastas.

Ambas Minha intenção não foi aprendr a codificar, e sim a estruturar e governaça de projeto

A documentação de desenvolvimento daqui não tem como fim informar o leitor a codificar, linha a linha, como num curso de programação. O propósito é entender a estrutura, os limites e a lógica organizacional: onde vive o domínio, como a feature se encaixa, como a landing e o app compartilham base sem se confundir, e como as regras e arquivos mantêm o repositório legível a humanos e alinhados para a ferramenta.

Na prática usada neste projeto, a IA (agente no editor) gera, altera e consolida código a partir de instrução e contexto. O humano delega tarefas com prioridade, escreve e refina a governaça (regras de design system, estrutura e convenções) e revisa o que a máquina não pode garantir sozinha: intenção de produto, segurança, coerência de domínio e alinhamento com o usuário. O “desenvolver” deixa de ser principalmente digitar, e passa a ser conduzir, contratar e manter o contrato entre pessoas, repositório e agentes.

Isso não tornou o trabalho trivial. Cada feature e cada implementação de componente — na landing ou no app — foi um desafio e um aprendizado: modelar, encaixar, evitar acoplamento, alinhar com design e, ao mesmo tempo, não deixar a IA “inventar” o produto. Esse percurso inclui, hoje, a economia de contexto e de tokens da assistência: contexto longo e difuso custa caro, em atenção e em custo; arquivos focados, regras claras, pedidos precisos e documentação alinhada são formas de gastar menos recursos para dizer a mesma coisa duas vezes — e, em paralelo, de reduzir regressões. O cansaço e o ajuste valem o registro explícito: engenharia aqui é também iteração e humildade perante a complexidade, com a IA a acelerar a execução, não substitui a jornada.

Classificação: Landing page e Aplicação (App)

Este guia de desenvolvimento mistura processo (regras, ferramenta, repositório) e conteúdo de produto (domínio, canvas, cálculo). A tabela abaixo indica, para cada bloco, o que pesa em cada produto — sem duplicar o documento Design e sistema, que já detalha a foundation entre outros.

Aplicação 1. O que a engenharia precisa cumprir

• Fluxo visual legível, com cálculo coerente com o desenho do canvas.
• Resposta contínua em ajuste de premissas (a experiência não pode “cair” a cada pequena mudança).
• Comunicação de impacto etapa a etapa, alinhada ao desenho de produto.
• Equilíbrio entre módulo base e módulo financeiro, evitando acoplamento injustificado.

Ambas 2. Estrutura e organização (arquitetura da informação)

O software é orientado a domínio: a lógica de fluxo, cálculo e projeção vive em um núcleo claro, enquanto a interface (canvas, painéis, marketing) organiza e expõe. Isso reduz o risco de “lógica espalhada” e torna testes e melhoria mais previsíveis, especialmente em um produto com interação densa e estados múltiplos.

Ambas Princípios

• Fronteira nítida entre cálculo e interface: a UI reage, mas as regras de domínio não se misturam com detalhe puramente estético.
• Reuso controlado — a landing e a aplicação compartilham a mesma base visual e componentes, quando faz sentido, em vez de duas linhas de design independentes.
• Evolução em camadas — a base de fluxo e o aprofundamento financeiro progridem de forma acumulativa, com menos surpresa para quem mantenha o produto.

Aplicação 3. Cadeia lógica: módulos, features, ferramentas, componentes

Aprender a estruturar uma cadeia lógica — do domínio à interface — foi tão relevante quanto a escolha de stack. Em termos de desenho do código:

• Módulo (ou domínio) — o que é a regra de negócio e o seu limite: fluxo, cálculo, projeção. Sem esse limite, a UI puxa lógica para lugar errado e o cálculo “vaza” para a apresentação.
• Feature — um encadeamento completo e entregável na perspectiva de usuário (ex.: ativar trial, conduzir o primeiro fluxo). A feature liga o módulo à experiência, sem ser um arquivo enorme a abarcar tudo.
• Ferramenta (no app) — a affordance que o produto oferece para agir: barra, painel, ação de nó, leitura de tabela. A ferramenta concretiza a feature, mas não a mistura com o cálculo bruto do domínio.
• Componente — o bloco reutilizável de UI, alinhado a tokens e textos, para a superfície não divergir a cada tela.

Quem domina quem manda em quem nessa cadeia (e onde para cada camada) evita arquivos “faz-tudo” e evita dependências invisíveis. No Frowexa, a tangibilidade do produto reforçou-se quando essa cadeia ficou explicável em conversa e no código, não só no protótipo.

Ambas 4. Design.md, design_system e a codificação

Escrever um guia de design (ou equivalente, como o que pode viver em Design.md / documentação de leitura, e regras de design system em design_system.md ou arquivo semelhante) não é burocracia: é âncora na codificação. Neste trabalho, ajudou a:

• Alinhar discurso e implementação — tokens de cor, tipografia e hierarquia deixam de ser “gosto pessoal” e passam a ser critério. Quem codifica sabe o que a landing pode ousar e o que o app tem de cumprir.
• Reduzir retrabalho de UI — decisões de contraste, foco, espaçamento e padrão de seção vêm de cima, na definição do design; a implementação aplica, em vez de renegociar a cada tarefa.
• Encontrar a IA (e humanos) no mesmo texto — se o desenho está escrito, o agente e o revisor têm uma fonte de verdade fora do diff do dia — menos interpretação oportunista, mais consistência.
• Tangibilizar o produto — o repositório deixa de ser só o binário: passa a incluir a explicação de como o fruto do design se materializa, o que aproxima o portfólio da engenharia.

O arquivo exato (nome, pasta) importa menos do que a obrigação de existir um lugar canônico: sem isso, o design evapora e o código assume o vazio (ou a moda do último tela).

Ambas 5. Regras, delegação a agentes e alinhamento (sem conflito)

Agentes de IA não substituem o dono de produto, mas amplificam o que você lhes dá. Por isso importa criar regras explícitas e delegar papéis a partir delas, em vez de mandar a IA “fazer tudo” sem contrato.

• Regras = fronteiras — idioma, acessibilidade, estrutura de arquivo, tamanho de alvo, o que tocar e o que não tocar, formato de resposta, segurança. Isso dá previsibilidade a quem reutiliza a mesma IA em tarefas distintas.
• Delegação = papéis — numa tarefa, a IA fica a “swe/UX/revisor” o que a regra define: por exemplo, uma regra cuida de a11y, outra de separação de UI/lógica, outra de escopo. Sem papéis, tudo vira a mesma voz, e tudo conflitua com tudo.
• Alinhar regras para evitar embate — regras contraditórias (ex.: “mínimo de código” vs. “refactor abrangente”, ou “só o pedido” vs. “muda o que achar necessário”) geram oscilação e diff imprevisível. O alinhamento percorre: prioridade (o que manda se dois princípios se cruzam), o mesmo vocabulário de design e o mesmo limite de escopo. Uma regra geral, um guia de design e uma memória de produto alinhados reduzem conflito entre agentes, entre agente e pessoa, e entre PRs consecutivos.
• Revisão humana confirma o que a regra não cobre, ou onde o contexto faltou a um agente.
• Segurança — credenciais e segredos fora de regras visíveis à IA, fora de commits, e o mínimo de contexto sensível no prompt.

Ambas 5.1. Delegar regras por pilar (revisão, output, security, code, core)

Na ferramenta de assistência no editor (no dia a dia, Cursor e o respectivo ecossistema de regras, repositório e tarefa), o ganho de qualidade sobe quando as regras do projeto não vivem num único bloco genérico — mas quando se delega a intenção a domínios de responsabilidade que a IA sabe acompanhar, em paralelo, sem se sobreporem em conflito. Isso aproxima o que em equipe se faria com checklists e owners; na prática, o agente “troca de chapéu” conforme o arquivo de regra ou a tarefa, desde que tudo isso esteja alinhado na mesma hierarquia de prioridade (por exemplo: core antes de segurança, segurança antes de entrega — o repositório deve fixar a ordem).

• Code review (revisão) — regras que puxam a IA para: critério de diff pequeno, alinhamento com padrão do repositório, acessibilidade, não expandir o escopo, não apagar comentários úteis. Aqui o agente atua como revisor antes de fundir lógica nova com o tronco.
• Output — tom, língua (ex.: português), estrutura de resposta, quando usar listas, quando citar código, proporção de explicação vs. entrega, para a saída do assistente ser previsível em PRs, chat e comentários de commit.
• Security — tratar inputs, nunca comitar segredos, não exfiltrar credenciais em prompts, validar suposições em camadas sensíveis, e reforçar o que a CI e a revisão humana também vigiariam.
• Code (estilo e convenção) — TypeScript, nomes, separação de UI e lógica, tamanho de arquivo, imports, padrão de teste onde existir, para a implementação automática ou semi-automática não abrir mão da legibilidade alinhada à equipe.
• Core (arquitetura e produto) — princípios de domínio, fronteira entre fluxo e apresentação, o que o produto é (raciocínio rastreável, módulo base vs. financeiro), e o que a landing não pode quebrar. Isso restringe a IA para não “simplificar” a custo de violar a ideia de produto.

Por que isso importa na ferramenta de coding: sem pilares, um único agente (ou o mesmo atalho) tenta servir tudo e acaba a conciliar o inconciliável no mesmo prompt. Com regras distribuídas e prioridade explícita, a delegação mimetiza várias vozes alinhadas (revisor, redator, segurança, estilo, arquitetura) sem exigir cinco conversas. O humano ainda aprovará o merge; a máquina deixa de adivinhar qual crítica prevalece.

Trata-se de tratar a IA como acelerador assistido com comando único e coerente — o oposto de “cada prompt um império”.

Ambas 6. Fragmentar a feature (arquivo) e aproveitar o Cursor

Um dos maiores riscos no desenvolvimento assistido é inflar um arquivo (UI, lógica, constantes, tudo) porque a IA consolida rápido, mas a manutenção fica lenta, e o agente lê pior, com contexto confuso. Por isso:

• Fragmentar a feature — módulo pequeno, hook dedicado, constantes em outro arquivo, subcomponente quando o JSX cresce, slice de estado quando a responsabilidade se duplicou. Isso mapeia a cadeia lógica: cada arquivo com um contrato, não “um monólito fácil de gerar de uma vez”.
• Entender a ferramenta (Cursor) — aproveita melhor modos e limites do produto: quando pedir implementação, quando pesquisa read-only, quando regras de projeto, quando skills, quando diff pequeno. Não tratar o Cursor como “chat genérico”: usa-se o que a ferramenta dá (contexto de repo, padrão de tarefa, regras persistentes) para alinhar com as seções 4 e 5.
• Contexto afinado — referenciar arquivos certos, pedir o mínimo de arquivo para o agente, e manter repositório legível (nomes, fronteiras) para a ferramenta não perder a noção da cadeia lógica.
• Reiteração — tarefa em passos, em vez de um mega-pedido, reduz a probabilidade de a IA pular a governança e a consistência de design.

Em resumo: arquivo pequeno, fronteira clara, regra e design escritos, Cursor usado de forma deliberada — aí a codificação do projeto ganha ritmo e rigor, sem trocar o desenho do domínio a cada geração.

Ambas 7. Tecnologias e porquê (escolhas, alto nível)

As escolhas refletem necessidades de interface reativa, modelagem lógica e entrega contínua de uma SPA (Single Page Application):

Persistência do fluxo (cliente, não “nuvem” do grafo): o rascunho e o desenho do canvas (nós e ligações) são guardados, na prática, no armazenamento local do navegador (ex. localStorage), e não se replica automaticamente a um servidor como repositório pessoal do mesmo grafo noutro equipamento. Trocar de browser, de perfil, de máquina, limpar dados do site, ou janela anônima: tipicamente outro alvo de armazenamento — sem as mesmas configurações e o mesmo desenho, salvo exportação ou outra cópia feita por você. Em paralelo, quando a configuração existir, Supabase pode tratar de leads, autenticação, feedback e trial, com fim distinto, descrito em Política de privacidade — ainda que a “alma” do fluxo, nesta arquitetura, fique ancorada no dispositivo.

• React (UI) — ecossistema maduro, componentização natural para uma interface com muitos estados e re-renderização. Adequada para um canvas e painéis que precisam acompanhar alterações de dados em tempo real de forma previsível.
• TypeScript (linguagem) — tipagem forte para o núcleo de domínio, reduzindo regressões em modelos, contratos e propriedades compartilhadas entre tela, painéis e cálculo.
• Vite (ferramenta de build) — desenvolvimento ágil, empacotamento moderno, adequado a um app front-end com iteração frequente, sem ciclos de build lentos.
• Biblioteca de canvas em grafo (fluxo de nós) — acelera o desenho de nós, ligações, handles e interações, permitindo estender a experiência com componentes do produto, em vez de construir “do zero” um motor de desenho completo.
• Estado global leve (store) — adequado a slices de proposta/canvas/áreas do produto, com atualizações localizadas, sem forçar um padrão excessivamente pesado para a escala do projeto.
• Validação de input (esquemas) — reforça consistência em formulários (como acesso) e regras de entrada, reduzindo erros cedo, antes de tocar a lógica de negócio.
• Testes de domínio (unitários) — prioridade para a matemática e as transformações, onde bugs são mais caros e difíceis de “enxergar” na UI. A interface tem revisão, mas a lógica tem teste direto, onde fizer sentido.

Ambas 8. Risco, qualidade e manutenção

Qualidade, aqui, é combinação de revisão de tipo, teste de regras críticas, revisão de experiência (UX/UI) e disciplina de entrega (não crescer a raiz da aplicação com requisitos invisíveis de marketing ou experimentos de agente fora de escopo).

Ambas 9. Resultado, como visão de engenharia

Uma aplicação web moderna, coerente com a promessa: modelar no fluxo, ver impacto, auditar a cadeia, com arquitetura e processo de desenvolvimento preparados para evolução, sem trocar o desenho do domínio a cada iteração.

Nota: serviços externos (hospedagem, autenticação, persistência) são operação, configuráveis. Este guia concentra-se em cadeia lógica, documentação de design, regras de agente, prática de arquivo e stack.

90% da documentação foi gerada por IA dentro dos contextos e intenções do autor.