Três planos compõem a arquitetura representada na Figura~\ref{fig:arch} ---

cliente, \textit{back-end} e infraestrutura ---, lidos da esquerda para a

direita. O aplicativo móvel comunica-se exclusivamente com a API por

HTTPS/JSON e mantém no dispositivo apenas o estado efêmero da interface e um

cache local dos dados já consultados; validação, autorização e regras de

domínio ficam concentradas no servidor. A API é a única porta de entrada para

os dados: acessa o PostgreSQL por meio do Prisma, grava avatares no

armazenamento de objetos e delega o trabalho que não precisa bloquear a

resposta ao usuário a filas no Valkey, consumidas por \textit{workers}

independentes. São esses \textit{workers} que enviam e-mails e notificações e

recalculam os indicadores, mantendo a API livre de tarefas de longa duração.

Essa organização tem como principal força a separação de responsabilidades em

torno de um contrato único: como o cliente só conhece a API, mudanças internas

no banco, nas filas ou nos serviços externos não o afetam, e a autenticação por

JWT permite que a API permaneça sem estado, reiniciável sem perda de sessão. O

desacoplamento por filas também torna o registro de um humor uma operação

curta, independente do custo de recalcular indicadores ou disparar

notificações. Em contrapartida, a topologia é deliberadamente monolítica e

vertical: todos os componentes são implantados em um único servidor por meio do

Docker Compose, sem replicação horizontal da API ou separação física entre

banco, fila e \textit{workers}. Isso significa que o trabalho pesado dos

\textit{workers} compete por CPU e memória com o atendimento das requisições, e

que a disponibilidade do conjunto equivale à disponibilidade desse único

\textit{host}. Trata-se de um \textit{trade-off} coerente com o porte do

projeto, mas que delimita seu principal limite de escalabilidade.

Aqui, é possível observar alguns elementos. O primeiro é o uso de

\texttt{z.nativeEnum} para reaproveitar diretamente os \textit{enums}

declarados no esquema do Prisma (linhas 1--5), em vez de repetir as listas de

valores no código. Como esses enums são a mesma fonte de verdade que o banco

impõe, a validação aceita exatamente o conjunto de valores que pode ser

persistido, e qualquer valor fora dele é rejeitado na borda da API antes de

chegar à camada de persistência. Esse padrão se repete de forma extensiva nos

demais esquemas, que reutilizam enumerações de gatilho, tipo de ação de

cuidado, periodicidade de medicamento e tipo de indicador. Em seguida, são

criados os \textit{schemas} de validação: um valida os componentes

O Código~\ref{lst:prisma-schema} reproduz um trecho representativo desse

esquema, o modelo de registro de humor. Além dos campos e de seus tipos, o

trecho evidencia a convenção de nomenclatura adotada: modelos e campos seguem o

padrão do TypeScript --- \texttt{PascalCase} para tipos e \texttt{camelCase}

para propriedades ---, enquanto as tabelas e colunas no PostgreSQL usam

\texttt{snake\_case}, com nomes de tabela no plural. Os atributos

\texttt{@map} e \texttt{@@map} fazem essa tradução, de modo que o código da

aplicação manipula \texttt{selectedMood} ou \texttt{anxietyLevel} sem que os

nomes físicos das colunas vazem para a API. O trecho também mostra a declaração

explícita das relações e o uso de enumerações para valores fechados. Esses

\textit{enums} não se limitam ao código: na migração, o Prisma os materializa

como tipos enumerados nativos do PostgreSQL, de modo que a restrição aos

valores previstos é imposta também pelo banco. O esquema declara enumerações

para humores, componentes e intensidade, categorias de gatilho, tipos de ação

de cuidado e periodicidade de medicamentos, entre outras. A partir desse único

arquivo, o Prisma gera o cliente tipado consumido pela API e as migrações SQL

versionadas no repositório, de modo que alterações no modelo passam por revisão

e são aplicadas de forma reproduzível em qualquer ambiente.

\begin{lstlisting}[caption={Trecho do esquema Prisma para o registro de humor}, label={lst:prisma-schema}]

model Mood {

  id           Int            @id @default(autoincrement())

  annotation   String?        @db.Text

  moment       DateTime       @default(now())

  selectedMood BaseMoodOption @default(GOOD) @map("selected_mood")

  anxietyLevel Int            @map("anxiety_level")

  stressLevel  Int            @map("stress_level")

  energyLevel  Int            @map("energy_level")

  userId       Int            @map("user_id")

  user         User           @relation(fields: [userId], references: [id])

  moodComponents MoodComponent[]

  triggerLinks   TriggerMoodLink[]

  careActions    CareAction[]

  @@map("moods")

}

\end{lstlisting}

\sourcecode{Elaborado pelo autor (2026)}

No projeto, o fluxo de trabalho de CI/CD é dividido em três etapas sequenciais

e dependentes entre si, como visto na

Figura~\ref{fig:screenshot-github-actions}. A primeira etapa (\texttt{test})

sobe um serviço efêmero de PostgreSQL e executa a suíte de testes automatizados

da API a cada \textit{push} ou \textit{pull request} que modifique arquivos do

\begin{figure}[H]

\centering

\caption{Github Actions rodando os testes e realizando \textit{deploy}}

\label{fig:screenshot-github-actions}

\includegraphics[width=\linewidth]{screenshot-github-actions.png}

\source{Elaborado pelo autor (2026)}

\end{figure}

e ao do GitHub Actions: enquanto estes automatizam, respectivamente,

a orquestração dos serviços da aplicação e o ciclo de integração e entrega

contínuas, o Ansible é responsável exclusivamente pelo provisionamento inicial

do servidor de produção, executado uma única vez --- ou sempre que um novo

servidor precisar ser provisionado. Esse provisionamento consiste em: (1) criar

o usuário dedicado à aplicação; (2) adicionar a chave pública SSH utilizada

pelo GitHub Actions para se autenticar no servidor durante a etapa de

implantação; (3) criar os diretórios da aplicação com as permissões adequadas;

e (4) instalar o Docker no servidor. A cópia do arquivo de variáveis de

ambiente de produção (\texttt{.env.production}), por conter segredos

e credenciais sensíveis, é deliberadamente mantida como uma etapa manual, não

automatizada, e não é versionada no repositório. O Ansible, trabalha de forma

modularizada, portanto permite que possamos organizar as tarefas a serem feitas

em ``perfis'', da qual podem ter uma serie de tarefas para serem executadas em

sequencia, \textit{templates}, etc. O Código~\ref{lst:ansible-setup} demonstra

a lista de tarefas iniciais, em qual máquinas devem rodar, através da diretiva

\textit{hosts}, o método de troca de permissão (através da diretiva

\textit{become}) e tarefas posteriores.

\begin{lstlisting}[caption={Provisionamento utilizando um \textit{playbook} de configuração}, label={lst:ansible-setup}]

- name: Base host setup

  hosts: vps

  become: yes

  become_method: doas

  roles:

    - bootstrap

    - docker

    - appuser

  post_tasks:

    - name: Confirm deploy user can reach Docker

      ansible.builtin.command: docker info

      become_user: "{{ deploy_user }}"

      changed_when: false

      register: docker_check

    - name: Show Docker status

      ansible.builtin.debug:

        msg: "Docker is reachable by {{ deploy_user }}"

      when: docker_check.rc == 0

\end{lstlisting}

\sourcecode{Elaborado pelo autor (2026)}

O Código~\ref{lst:ansible-setup-tasks} mostra o conteúdo de um desses papéis, o

de Docker. Cada tarefa descreve um estado desejado --- o pacote instalado, o

diretório existente com determinada permissão, o arquivo de configuração do

\textit{daemon} com seu conteúdo, o serviço habilitado --- em vez de uma

sequência de comandos imperativos. É essa forma declarativa que permite ao

Ansible inspecionar o estado atual e agir apenas sobre o que diverge; a tarefa

de rotação de \textit{logs}, por exemplo, vale para todos os contêineres, e não

apenas para aqueles que declaram um bloco de \textit{logging} próprio no arquivo

de composição.

\begin{lstlisting}[caption={Tarefas de provisionamento utilizando um \textit{playbook}}, label={lst:ansible-setup-tasks}]

- name: Install Docker and Compose plugin

  community.general.apk:

    name:

      - docker

      - docker-cli-compose

    state: present

- name: Ensure /etc/docker exists

  ansible.builtin.file:

    path: /etc/docker

    state: directory

    owner: root

    group: root

    mode: "0755"

# Bound every container's json-file logs globally, not just the ones that set

# an explicit logging block in a compose file

- name: Configure the Docker daemon log rotation

  ansible.builtin.copy:

    dest: /etc/docker/daemon.json

    content: |

      {

        "log-driver": "json-file",

        "log-opts": { "max-size": "10m", "max-file": "3" }

      }

    owner: root

    group: root

    mode: "0644"

  notify: restart docker

- name: Enable Docker service

  ansible.builtin.service:

    name: docker

    enabled: yes

    state: started

\end{lstlisting}

\sourcecode{Elaborado pelo autor (2026)}

Automatizar esse provisionamento com o Ansible, em vez de repetir os mesmos

passos manualmente por SSH, não economiza apenas comandos: troca um

procedimento implícito, que existiria apenas na memória de quem o executa, por

um artefato versionado e revisável. Por ser idempotente, o \textit{playbook}

pode ser reexecutado após uma falha parcial ou sobre um servidor já configurado

sem duplicar usuários, diretórios ou configurações; como consequência, o

processo se torna auditável e reproduzível por terceiros.

Em um projeto de código aberto, é isso que permite que outra pessoa reconstrua

a infraestrutura do zero --- ou a audite antes de confiar nela --- sem acesso

prévio ao servidor de produção, além de reduzir a chance de erro humano e de

divergência entre ambientes. A divisão em papéis (\textit{roles}) reforça essa

propriedade ao separar responsabilidades --- usuário da aplicação, Docker e

configuração base ---, de modo que cada parte pode ser alterada e testada

isoladamente.