Objetivo e escopo

Este guia foi elaborado como documentação técnica consolidada para desenvolvedores da plataforma NEO.

O objetivo é permitir que o desenvolvedor consiga:

• estruturar um app em NEO Framework;

• modelar entidades com DocTypes;

• implementar regras de negócio em Python;

• construir UX no Desk e no website;

• publicar APIs e integrações;

• operar sites, assets, filas e migrações com neoc.

Público-alvo

Este material atende principalmente:

Desenvolvedor backend

Trabalha com controllers, Document, hooks, ORM, integrações, jobs e segurança.

Desenvolvedor front-end

Atua no Desk, em scripts cliente, pages, listas, diálogos, portal, website e assets em public/.

Desenvolvedor full stack

Conecta metadados, backend e UI para transformar requisito de negócio em solução operacional.

Líder técnico

Define padrões de modularização, deploy, versionamento e fronteiras entre apps.

O que esta documentação cobre

O conteúdo foi organizado para cobrir o ciclo completo:

1. arquitetura da plataforma;

2. setup do ambiente;

3. estrutura de apps e sites;

4. modelagem com DocTypes;

5. regras de negócio e eventos;

6. front-end do Desk e website;

7. APIs, integrações e jobs;

8. segurança, relatórios e observabilidade;

9. testes, migrações e deploy.

O que este guia não substitui

Este guia não substitui o código-fonte do seu projeto, nem detalhes específicos da instalação usada pela sua organização. Alguns comportamentos podem variar conforme a versão do NEO, os apps instalados e a forma como o ambiente foi empacotado.

Como usar este guia

Há três usos principais:

• leitura linear, para onboarding;

• consulta por assunto, para o dia a dia;

• base para GitBook interno, com revisão contínua no Git.

Modelo mental recomendado

Uma forma eficiente de pensar uma solução NEO é separar em cinco camadas:

Camada	Pergunta principal
Metadados	Quais entidades, campos, permissões e layouts existem?
Domínio	Quais regras de negócio precisam ser executadas?
Interface	O que o usuário vê no Desk, no portal e no website?
Integração	Como a aplicação conversa com outros sistemas?
Operação	Como instalar, migrar, monitorar e publicar?

Onde o front-end do NEO entra

No NEO, o front-end não é só camada visual. Ele participa diretamente do fluxo de trabalho por meio de:

• formulários gerados a partir de DocTypes;

• Client Script com neo.ui.form.on;

• listas, pages, workspaces e dialogs;

• website, portal e web forms;

• assets do app em public/.

Isso significa que modelagem, backend e front-end são partes do mesmo desenho técnico.

Princípios recomendados

Priorize metadados quando o problema for estrutural

Se a necessidade é um novo cadastro, novo layout, nova relação ou novo fluxo documental, a resposta costuma começar no DocType.

Centralize regra crítica no backend

Segurança, integridade e cálculos de negócio não devem depender apenas do navegador.

Trate scripts cliente como camada de experiência

A UI deve guiar o usuário, mas o backend continua sendo a fonte da verdade.

Versione tudo o que for repetível

DocTypes, hooks, patches, fixtures e assets precisam morar no repositório.

Resultado esperado

Ao final deste guia, o desenvolvedor deve conseguir:

• entender a arquitetura do NEO;

• preparar o ambiente com neoc;

• criar apps e sites;

• modelar documentos;

• construir UX no Desk;

• expor APIs e jobs;

• preparar migração e deploy previsíveis.