Desenvolvimento

1 - Pré-requisitos

Docker e Docker Compose instalados

Tempo de execução Bun instalado (https://bun.sh)

Repositório Lowcode Studio clonado

Repositório Tauri do Motor Lowcode clonado (opcional, para funcionalidade de pré-visualização)

2 - Instalação

2.1 - Dependências de Instalação

A partir da raiz do projeto, instale todas as dependências do workspace:

bun install

2.2 - Iniciar Serviços de Infraestrutura

Lowcode Studio requer PostgreSQL e Redis. A é fornecido na raiz do projeto:docker-compose.yml

docker compose up -d

Começa assim:

PostgreSQL 17 na porta (usuário: , senha: 5432 run2biz run2biz)

PgBouncer na porta (pooler de conexão para PostgreSQL, modo transação) 6432

Redis 7 na porta (senha: 6379 run2biz)

📌 A API se conecta via PgBouncer (porta) em vez de diretamente ao PostgreSQL (porta). O PgBouncer oferece pooling de conexões no modo de transação, essencial para cargas de trabalho multi-inquilino. 6432 5432

2.3 - Configuração do Ambiente

Configuração do servidor

Crie um arquivo no diretório após o modelo. .env/ server .env .example

Para desenvolvimento local, configure o banco de dados e URLs do Redis apontando para via PgBouncer: localhost

DATABASE_URL=postgresql://run2biz:run2biz@localhost:6432/postgres
REDIS_URL=redis://default:run2biz@localhost:6379

❗ Não inclua no — o PgBouncer no modo de transação não suporta parâmetros de inicialização. O esquema de Drizzle já é qualificado com , então todas as consultas são prefixadas automaticamente. search_path DATABASE_URL pgSchema("lowcode_studio")

Migrações de banco de dados usam que reescrevem a porta de para conectar diretamente ao PostgreSQL (contornando o PgBouncer), já que precisa do parâmetro de inicialização. drizzle.config.ts 6432 5432 drizzle-kit search_path

📌 Ao rodar dentro do Docker (por exemplo, via Edge-runtime), use os nomes de host dos contêineres:

DATABASE_URL=postgresql://run2biz:run2biz@pgbouncer:6432/postgres REDIS_URL=redis://default:run2biz@redis:6379

Configuração do Cliente

Crie um arquivo no diretório após o modelo. .env /client .env .example

Para desenvolvimento local, o cliente aponta diretamente para a API do servidor:

VITE_API_URL=http://localhost:8080/api
VITE_ENGINE_URL=http://localhost:1420/tauri-engine

Variável	Descrição	Padrão
VITE_API_URL	URL completa para o servidor API do Lowcode Studio	/lowcode-studio-api/api (produção)
VITE_ENGINE_URL	URL onde a Tauri Engine é servida	/tauri-engine (produção)

📌 Em produção, ambos e usam caminhos relativos porque a API e o motor são servidos pela mesma origem em tempo de execução de borda. No desenvolvimento local, eles devem apontar para as URLs reais dos serviços, já que não há proxy reverso.

VITE_API_URL VITE_ENGINE_URL

2.4 - Executar migrações de banco de dados

Após iniciar o PostgreSQL, execute as migrações do banco de dados:

cd server bun run db:migrate

2.5 - Iniciar Servidores de Desenvolvimento

A partir da raiz do projeto, inicie tanto o cliente quanto o servidor simultaneamente:

bun run dev

Começa assim:

Servidor (Hono API): http://localhost:8080

Cliente (Vite): http://localhost:4000

Você também pode começar individualmente:

bun run dev:client # Vite dev server on port 4000 bun run dev:server # Hono server with --hot flag on port 8080

Iniciar o motor Tauri (opcional)

Para usar o recurso de pré-visualização móvel, inicie o servidor de desenvolvimento do Tauri Engine em seu próprio repositório:

cd /path/to/lowcode-engine-tauri bun run dev

Isso serve ao motor em .http://localhost:1420/tauri-engine

Veja Integração do Motor para detalhes da configuração do Motor Tauri.

A aplicação requer um token JWT válido. Defina o cookie no seu navegador para .HYPER-AUTH-TOKENlocalhost:4000

Você pode fazer isso via DevTools do navegador:

Abra no seu navegador http://localhost:4000

Abrir DevTools → Cookies de Aplicação → → http://localhost:4000

Adicione um cookie com nome e um token JWT válido como valor HYPER-AUTH-TOKEN

Alternativamente, se o tempo de execução de borda estiver disponível, use o endpoint set-cookie:

http://localhost:3000/set-cookie?token=YOUR_TOKEN_HERE

2.7. Acesse ao Lowcode Studio

Quando ambos os serviços estiverem em execução, acesse o Lowcode Studio em:

http://localhost:4000

3. Notas de Arquitetura

3.1. Stack de Middleware de Servidor

O middleware da API executa nesta ordem:

prettyJSON → → trimTrailingSlashcors

/health endpoint (não autenticado)

/webhooks Rotas (não autenticadas)

setTenantDb → validateToken

Rotas de domínio (, , , /components/projects/permissions/users)

📌 O middleware CORS é colocado antes da autenticação para garantir que as solicitações de pré-voo tenham sucesso. Isso é essencial quando o cliente e o servidor rodam em origens diferentes (por exemplo, e ).OPTIONSlocalhost:4000localhost:8080

3.2. Solicitações de Origem Cruzada

No desenvolvimento local, o cliente () faz requisições diretas ao servidor (). Isso exige: localhost:4000localhost:8080

Servidor: CORS configurado com origem dinâmica e credentials: true

Cliente: Todas as solicitações de busca incluem enviar cookies de origem cruzada credentials: "include"

Tauri Engine: Usa em seu cliente HTTP pelo mesmo motivo withCredentials: true

Em produção, todos os serviços estão atrás da mesma origem (tempo de execução de borda), então a origem cruzada não é um problema.

4. Implantação via tempo de execução de borda

Para implantação via Edge-runtime (configuração semelhante a produção), consulte a integração original Edge-runtime:

4.1. Configurar o Volume do Docker

No runtime do Edge, adicione o volume correspondente para o servidor Lowcode Studio: docker-compose.yml

volumes:
  - ../edge-functions/lowcode-studio/server:/home/deno/functions/lowcode-studio-api/1.0.0

4.2. Iniciar Serviços de Execução em Borda

Navegue até o diretório raiz Edge-runtime e execute:

docker-compose up -d --build

📌 Ao iniciar, o tempo de execução da borda irá automaticamente:

Executar migrações de banco de dados

Configure o esquema necessário para o Lowcode Studio

Preencher dados iniciais de seed

Uma vez em execução, acesse o Lowcode Studio via Edge-runtime em:

http://localhost:3000

5. Solução de problemas

5.1. Problemas de Conexão com Banco de Dados

Se você encontrar erros na conexão do banco de dados:

Verifique se o PostgreSQL está rodando: docker compose ps

Confirme que o parâmetro está corretamente definido em search_pathDATABASE_URL

Verifique se o esquema existe no banco de dados lowcode_studio

Certifique-se de estar usando (desenvolvedor local) ou o nome de host Docker (container) localhost:5432

5.2. Falhas na migração

Se as migrações falharem em executar:

Verifique se o PostgreSQL está acessível: docker compose logs postgres

Verificar credenciais de banco de dados em server/.env

Certifique-se de que o formato da URL do banco de dados esteja correto

Execute migrações manualmente: cd server && bun run db:migrate

5.3. Problemas de Conexão com o Cliente

Se o cliente não conseguir se conectar à API:

Verifique se o servidor está rodando na porta 8080

Verifique os pontos de entrada para VITE_API_URLclient/.envhttp://localhost:8080/api

Verifique o console do navegador para erros CORS — certifique-se de que o middleware CORS do servidor esteja antes da autenticação

Verifique se o cookie está configurado para o domínio correto HYPER-AUTH-TOKEN

5.4. Prévia Não Funcionando

Se a prévia móvel mostrar "Projeto não encontrado":

Verifique se o Motor Tauri está rodando em http://localhost:1420/tauri-engine

Pontos de verificação para VITE_ENGINE_URLclient/.env http://localhost:1420/tauri-engine

Verifique se a Tauri Engine tem e .env VITE_API_URL=http://localhost:8080/api VITE_ENGINE_MODE=PREVIEW

Verifique no console do navegador para erros de CORS ou autenticação

Certifique-se de que o cliente HTTP do Tauri Engine esteja ativado withCredentials: true

Desenvolvimento

﻿Desenvolvimento ﻿

﻿1 - Pré-requisitos ﻿

﻿2 - Instalação ﻿

﻿2.1 - Dependências de Instalação ﻿

﻿2.2 - Iniciar Serviços de Infraestrutura ﻿

﻿2.3 - Configuração do Ambiente﻿

﻿2.4 - Executar migrações de banco de dados ﻿

﻿2.5 - Iniciar Servidores de Desenvolvimento ﻿

﻿2.6. Definir o Cookie de Autenticação ﻿

﻿2.7. Acesse ao Lowcode Studio ﻿

﻿3. Notas de Arquitetura ﻿

﻿3.1. Stack de Middleware de Servidor ﻿

﻿3.2. Solicitações de Origem Cruzada ﻿

﻿4. Implantação via tempo de execução de borda ﻿

﻿4.1. Configurar o Volume do Docker ﻿

﻿4.2. Iniciar Serviços de Execução em Borda ﻿

﻿5. Solução de problemas ﻿

﻿5.1. Problemas de Conexão com Banco de Dados ﻿

﻿5.2. Falhas na migração ﻿

﻿5.3. Problemas de Conexão com o Cliente ﻿

﻿5.4. Prévia Não Funcionando ﻿

Desenvolvimento

1 - Pré-requisitos

2 - Instalação

2.1 - Dependências de Instalação

2.2 - Iniciar Serviços de Infraestrutura

2.3 - Configuração do Ambiente

2.4 - Executar migrações de banco de dados

2.5 - Iniciar Servidores de Desenvolvimento

2.6. Definir o Cookie de Autenticação

2.7. Acesse ao Lowcode Studio

3. Notas de Arquitetura

3.1. Stack de Middleware de Servidor

3.2. Solicitações de Origem Cruzada

4. Implantação via tempo de execução de borda

4.1. Configurar o Volume do Docker

4.2. Iniciar Serviços de Execução em Borda

5. Solução de problemas

5.1. Problemas de Conexão com Banco de Dados

5.2. Falhas na migração

5.3. Problemas de Conexão com o Cliente

5.4. Prévia Não Funcionando