eletrotupi / tcc/ commit / b77de0c

all: rewrite the README

Pedro Lucas Porcellis porcellis@eletrotupi.com · 13 days ago b77de0cf2fd487c62b9c698932d65906b0ef9398 Browse files
Parents 38004a3
Changed files
1
Additions
+125
Deletions
-8
README.md modified+125 -8
README.md
1 - 
# orbit - web
1 + 
# Nexo
2 +
3 + 
Nexo é um aplicativo de monitoramento de humor para pessoas com
4 + 
transtorno bipolar, e também um trabalho de conclusão de curso. Ele
5 + 
parte de uma pergunta simples e teimosa: como perceber o próprio estado
6 + 
emocional quando ele muda depressa, e o que ajuda a explicá-lo?
7 +
8 + 
Registrar "como eu estou" é só o começo. A proposta é guardar também o
9 + 
contexto em volta do registro — o que aconteceu, como estavam o corpo e
10 + 
a cabeça, o que veio depois. Com o tempo, esses fragmentos formam uma
11 + 
linha do tempo que dá para reler e onde dá para enxergar padrões.
12 +
13 + 
Originalmente o app seria 100% offline; por exigência do curso, porém,
14 + 
passou a contar com um backend, então esta versão funciona com uma API
15 + 
implantada.
16 +
17 + 
> Nota histórica: o nome original do projeto era **orbit**. É normal
18 + 
> encontrá-lo por aí em algum arquivo de código ou string esquecida.
19 +
20 + 
## O que é o EMA
21 +
22 + 
O Nexo se apoia no EMA — *Ecological Momentary Assessment*, ou avaliação
23 + 
ecológica momentânea. Em vez de pedir que a pessoa reconstrua o dia
24 + 
inteiro de memória no fim da noite, o EMA propõe capturar o estado no
25 + 
momento em que ele acontece, no ambiente cotidiano e não no consultório.
26 +
27 + 
Na prática, isso muda o que o app pergunta. Ele não quer ser um diário
28 + 
genérico nem um placar de humor; quer registrar o instante e os seus
29 + 
arredores. É isso que permite, mais tarde, comparar tendências, cruzar
30 + 
sono e energia, e notar quais situações tendem a se repetir.
31 +
32 + 
## Funcionalidades
33 +
34 + 
- **Humor** — registro rápido ou detalhado, com energia, ansiedade e
35 + 
  estresse (escala de 0 a 10), emoções com intensidade e anotação livre.
36 + 
- **Gatilhos** — eventos do dia a dia por categoria, que podem ser
37 + 
  vinculados a um humor com o impacto percebido de cada um.
38 + 
- **Sono** — registro diário de horas e qualidade.
39 + 
- **Ações de cuidado** — medicações, consultas e atividades, que também
40 + 
  podem se ligar a humores e gatilhos.
41 + 
- **Medicamentos** — regimes recorrentes com horários, uma visão do
42 + 
  "hoje" para confirmar doses e lembretes automáticos.
43 + 
- **Histórico** — um feed único e cronológico de tudo, com filtros por
44 + 
  tipo.
45 + 
- **Jornada** — tendência de humor, correlação entre sono e energia,
46 + 
  padrões de gatilho e resumos diários, gerados periodicamente.
47 + 
- **Relatório** — um PDF "clínico" do período (até 90 dias) para levar à
48 + 
  consulta.
49 + 
- **Exportação** — todos os dados em CSV, enviados por e-mail.
50 +
51 + 
## Estrutura do monorepo
52 +
53 + 
```sh
54 + 
nexo/
55 + 
├── api         # servidor Express + Prisma
56 + 
├── frontend    # app React Native (Expo)
57 + 
├── monografia  # a tese, em LaTeX
58 + 
├── docs        # decisões (ADRs) e notas de trabalho
59 + 
├── ansible     # provisionamento do servidor
60 + 
└── docker-compose.yml
61 + 
```
62 +
63 + 
## Arquitetura
64 +
65 + 
- **API** — Express, Zod e Prisma sobre PostgreSQL; BullMQ com Valkey
66 + 
  para tarefas em segundo plano; Resend para e-mail e Expo para
67 + 
  notificações.
68 + 
- **Mobile** — React Native (Expo), expo-router, React Query com cache
69 + 
  persistido em MMKV e Zustand para o estado efêmero.
70 + 
- **Infra** — Docker Compose no dia a dia e Ansible para o servidor;
71 + 
  GitHub Actions cuida do deploy da API e da publicação da tese.
72 +
73 + 
![Arquitetura e elementos do sistema](monografia/images/arch-v2.png)
74 +
75 + 
## Como rodar localmente
76 +
77 + 
Pré-requisitos: Docker e o Expo CLI.
2 78
3 - 
Essa é a versão acadêmica do projeto orbit. Um tracker de humor para pessoas com
4 - 
TAB.
79 + 
```sh
80 + 
# sobe banco, fila e API
81 + 
docker compose up -d db valkey api
82 +
83 + 
# cria dados de exemplo
84 + 
cd api && npm run seed
85 + 
```
5 86
6 - 
Essa versão pretende ser web, justamente porque o curso não permite uma
7 - 
aplicação 100% offline, e também tem um carater mais acadêmico, reunindo
8 - 
documentos do processo de desenvolvimento, etc.
87 + 
O app móvel usa um *development build* por conta de dependências nativas, então logue com a conta do expo, gere uma build e depois basta rodar o comando:
9 88
10 - 
A aplicação final, offline será desenvolvida nesse [repositório aqui][orbit]
89 + 
```sh
90 + 
cd frontend
91 + 
npm install
92 + 
cp .env.example .env.local   # aponte a base da API para o IP da máquina
93 + 
eas build # apenas para gerar a build de desenvolvimento
94 + 
npx expo start # uso normal
95 + 
```
11 96
12 - 
[orbit]: https://git.eletrotupi.com/orbit
97 + 
## Testes
98 +
99 + 
A API usa Vitest e roda dentro do container, porque o banco de teste
100 + 
vive na rede do Compose:
101 +
102 + 
```sh
103 + 
docker compose exec api npm run test:setup
104 + 
docker compose exec api npm test
105 + 
```
106 +
107 + 
No mobile há fluxos de fumaça com Maestro, que roda num aparelho Android
108 + 
físico. Vale dizer que isso ainda é experimental: exige o Maestro e o `adb`
109 + 
instalados, além de um device conectado.
110 +
111 + 
```sh
112 + 
cd frontend && npm run test:e2e
113 + 
```
114 +
115 + 
## Monografia
116 +
117 + 
A tese que acompanha o projeto vive em `monografia/`, escrita em LaTeX.
118 + 
A edição costuma ser feita no Vim com o **vimtex**, que cuida de
119 + 
compilar enquanto se escreve.
120 +
121 + 
## Licença
122 +
123 + 
Por ser um projeto acadêmico, ele não é plenamente livre: o IFSul
124 + 
reserva uma parcela de autoria ao orientador, ao aluno e à instituição.
125 +
126 + 
Ainda assim, na medida do possível, o código está sob os termos da
127 + 
GPL-3.0-only e o texto sob a CC BY-NC-SA 4.0. Na prática: a tese pode
128 + 
ser lida, citada e compartilhada, mas não pode ser vendida nem usada
129 + 
comercialmente.