tuio/docs/arquitetura.md

Arquitetura Interna

Visão de como o código está organizado. A aplicação segue o padrão The Elm Architecture (Model–Update–View) da biblioteca Bubble Tea.

Estrutura de pastas

.
├── cmd/
│   └── main.go            # Ponto de entrada; inicia o programa Bubble Tea
├── internal/tui/
│   ├── model.go           # Struct Model, ConfigValues, carga de defaults, InitialModel/Init
│   ├── steps.go           # Enum das etapas do assistente
│   ├── update.go          # Lógica de transição (Update) por etapa
│   ├── view.go            # Renderização (View) por etapa
│   ├── form.go            # Componente genérico de formulário (FormStep/FormField)
│   ├── cmds.go            # Mensagens (Msg) e comandos assíncronos (tea.Cmd)
│   ├── docker.go          # Wrappers de chamadas ao binário docker
│   ├── config.go          # Geração e gravação de config.toml e envs
│   └── styles.go          # Paleta de cores e estilos Lip Gloss
├── config.toml            # (gerado em runtime; ignorado no git)
├── envs                   # (gerado em runtime, vproxy)
└── Makefile               # Build multiplataforma e publicação no S3

Componentes principais

Model (model.go)

Estado único da aplicação. Campos relevantes:

• currentStep — etapa atual do assistente.
• Estado de progresso/flags: dockerInstalled, downloadDone, finishedFile, finishedDockerRun, e os respectivos erros.
• Um FormStep por etapa de formulário (loginForm, wireguardForm, appForm, serverForm, dbForm, certForm).
• configValues (ConfigValues) — acumula os valores de todos os formulários, agrupados por seção.

loadConfig() define os valores padrão e, se houver um config.toml no diretório, sobrescreve com o conteúdo dele (usando BurntSushi/toml). InitialModel() constrói todos os formulários com esses defaults.

Etapas (steps.go)

step é um enum (iota) que define a ordem do assistente. O Update faz o dispatch com base em currentStep. Ver fluxo.md para o detalhamento.

Update (update.go)

Update trata primeiro mensagens globais (Ctrl+C, WindowSizeMsg, tick do spinner) e depois delega para um handler por etapa (ex.: updateCheckDocker, updateDownloadImage, updateRunDocker). As transições de etapa acontecem ao concluir formulários (done == true) ou ao receber mensagens de conclusão dos comandos assíncronos.

Constantes importantes ficam no topo do arquivo:

• imageName / wireguardImageName — imagens no registry privado.
• configPath (config.toml) / wireguardConfigPath (envs).

View (view.go)

View monta a tela com cabeçalho fixo, corpo dependente da etapa e rodapé de ajuda. Usa AltScreen. Cada etapa tem um método viewXxx ou reutiliza o View() do formulário.

Formulário genérico (form.go)

FormStep agrupa vários FormField. Suporta os tipos texto, senha, número e seleção. Update cuida da navegação entre campos (Tab/setas) e retorna done = true quando o Enter é pressionado no último campo. Values() devolve um map[string]string indexado pelo Id de cada campo — é isso que alimenta o ConfigValues.

Comandos e mensagens (cmds.go)

Toda operação bloqueante (chamar docker, escrever arquivo) é encapsulada em um tea.Cmd que roda em goroutine e devolve uma Msg ao loop do Bubble Tea:

Comando	Ação	Mensagem de retorno
CheckDockerCmd	exec.LookPath("docker")	DockerCheckedMsg
DownloadImageCmd	docker login + pull (app)	ImageDownloadFinishedMsg
DownloadWireguardImageCmd	docker login + pull (vproxy)	ImageDownloadFinishedMsg
GenerateConfigFile	grava config.toml	ConfigFileMsg
GenerateWireguardConfigFile	grava envs	ConfigFileMsg
RunAppContainer	docker run (app)	DockerRunMsg
RunWireguardContainer	docker run (vproxy)	DockerRunMsg
TickCmd	tick da barra de progresso	TickMsg

Camada Docker (docker.go)

Funções utilitárias que invocam o binário docker via os/exec:

• EnsureNetwork — cria a rede app-dono_app se necessário.
• RunAppClienteContainer / RunWireguardDockerContainer — montam os argumentos do docker run, removem container homônimo prévio e verificam o status running.
• verifyContainerRunning — inspeciona o status e, em falha, anexa os últimos logs.
• removeExistingContainer, PullImage, ImageExists, PushFileToContainer.

Estilos (styles.go)

Paleta de cores e estilos Lip Gloss reutilizados na View (títulos, cursor, ajuda, erros, barra de progresso, seleção).

Dependências

• charm.land/bubbletea/v2 — runtime TUI (loop Model/Update/View).
• charm.land/bubbles/v2 — componentes (textinput, spinner).
• charm.land/lipgloss/v2 — estilização.
• github.com/BurntSushi/toml — leitura do config.toml para defaults.

Observações para manutenção

• Porta: o config.toml grava port = 8080 fixo; a porta do formulário só afeta o mapeamento de host no docker run. Ver configuracao.md.
• Credenciais: o login do registry é coletado uma vez e reutilizado para baixar a imagem do vproxy.
• Rede: o nome da rede é a constante networkName (app-dono_app) em docker.go; usar sempre a constante ao referenciá-la.