|
Plataforma de acompanhamento de pacientes com hanseníase — Desenvolvido por alunos da Universidade Federal de Alagoas (UFAL), 
|
O Brasil registra historicamente um dos maiores números de casos novos de hanseníase do mundo. Apesar de ter cura, a doença exige tratamento prolongado — de seis meses a dois anos — e o abandono do tratamento é a principal causa de recidivas e de complicações que levam à incapacidade física permanente.
Pequi nasceu para reduzir esse abandono. O aplicativo permite que pacientes registrem sintomas e doses diárias de forma simples, enquanto profissionais de saúde acompanham a adesão, recebem alertas automáticos e se comunicam com suas equipes. A plataforma também oferece um espaço de comunidade anônima, onde pacientes podem compartilhar experiências sem expor sua identidade.
O projeto é desenvolvido como software de código aberto para unidades de saúde pública e organizações que atuam no combate à hanseníase no Brasil.
Note
O objetivo do Pequi é apoiar o acompanhamento de pacientes com hanseníase, mas ele não substitui avaliação médica profissional. A plataforma foi projetada para auxiliar a adesão ao tratamento, o monitoramento clínico e a comunicação entre equipes de saúde, sempre respeitando princípios de privacidade, segurança da informação e conformidade com a LGPD.
| Perfil | O que encontra aqui |
|---|---|
| Desenvolvedor novo | Instruções para subir o ambiente local do zero |
| Contribuidor | Como abrir um PR e onde está cada parte do código |
| Gestor de saúde / parceiro | Visão geral do produto e links para documentação detalhada |
flowchart TD
U["👤 Usuário\n(paciente ou profissional de saúde)"]
F["frontend/ · Angular 21\nInterface web — check-in, painel, comunidade"]
B["backend/ · FastAPI + Python 3.12\nAPI REST, autenticação JWT, regras de negócio"]
PG[("PostgreSQL\ndados clínicos")]
R[("Redis\ncache / filas")]
M[("MinIO / R2\nimagens de lesões")]
W["Workers ARQ\naderência · notificações · resumos assíncronos"]
U -->|HTTPS| F
F -->|"REST /v1/"| B
B --> PG
B --> R
B --> M
PG -.-> W
R -.-> W
Antes de clonar o projeto, certifique-se de ter instalado:
| Ferramenta | Versão mínima | Uso |
|---|---|---|
| Docker | 24.x | Subir toda a stack (banco, cache, storage, API) |
| Docker Compose | v2.x | Orquestrar os serviços |
| Node.js | 20.x LTS | Desenvolvimento do frontend |
| Python | 3.12+ | Desenvolvimento do backend |
| UV | última versão | Gerenciador de pacotes Python |
Para contribuições apenas no frontend, Docker + Node são suficientes. Para contribuições apenas no backend, Docker + Python + UV cobrem o essencial.
git clone https://github.com/seu-org/pequi.git
cd pequicp backend/.env.example backend/.env
# Edite backend/.env se necessário — os valores padrão já funcionam para desenvolvimento localcd backend
docker compose up -dIsso inicia:
db— PostgreSQL com PostGIS na porta5432redis— Redis na porta6379minio— armazenamento de objetos nas portas9000(API) e9001(console web)migrate— aplica as migrações Alembic automaticamente na primeira subidaapi— API FastAPI emhttp://localhost:8000(com hot reload)worker— processador de filas ARQ
Verifique se tudo subiu:
docker compose psA documentação interativa da API estará disponível em http://localhost:8000/docs.
Em outro terminal, a partir da raiz do repositório:
cd frontend
npm install
npm startO app estará acessível em http://localhost:4200.
pequi/
├── backend/ # API FastAPI, workers ARQ, migrações Alembic
│ ├── src/pequi/ # Código-fonte principal da aplicação
│ ├── tests/ # Testes unitários, de integração e E2E
│ ├── alembic/ # Migrações de banco de dados
│ ├── bruno/ # Coleções Bruno (contratos de endpoints)
│ └── scripts/ # Scripts de CI e utilitários de desenvolvimento
│
├── frontend/ # App Angular 21 (interface do paciente e do profissional)
│ └── src/ # Componentes, páginas e serviços Angular
│
├── docs/ # Documentação de produto: roadmap, épicos, milestones
│
├── .agents/ # Guias e workflows para agentes de IA e desenvolvedores
│
├── .github/
│ └── workflows/ # Pipelines de CI/CD (ci, build, lint, tests, release, security)
│
├── AGENTS.md # Guia técnico principal do backend (convenções, camadas, LGPD)
├── CHANGELOG.md # Histórico de versões (Keep a Changelog + SemVer)
└── LICENSE # MIT
| Documento | O que cobre |
|---|---|
backend/README.md |
Setup do backend, execução local, arquitetura em camadas, API, banco de dados, testes e observabilidade |
AGENTS.md |
Convenções de desenvolvimento, cadeia de dependências, padrões de código, LGPD, rate limiting e boas práticas para contribuidores e agentes de IA |
frontend/README.md |
Servidor de desenvolvimento Angular, scaffolding, build e execução de testes com Vitest |
docs/ROADMAP.md |
Visão de produto e entregas planejadas |
CHANGELOG.md |
Histórico de mudanças por versão |
-
Faça um fork do repositório e clone localmente.
-
Sincronize com a branch
developmentantes de criar a sua:
git checkout development
git pull origin development
git checkout -b feature/minha-contribuicao-
Implemente a mudança seguindo as convenções descritas em
AGENTS.md. -
Rode lint e testes antes de abrir o PR:
# Backend
cd backend
uv run ruff check .
uv run ruff format --check .
scripts/run_tests.sh
# Frontend
cd frontend
npm test-
Abra um Pull Request contra a branch
development(não contramain). O pipelineci.ymlroda automaticamente — o PR só pode ser mergeado com todos os checks passando. -
Descreva claramente no PR o quê e por quê foi alterado. PRs focados (uma feature ou um fix) são revisados mais rapidamente.
Dúvidas sobre o fluxo de branches? Consulte
.agents/rules/gitflow.md.
Distribuído sob a licença MIT. Consulte o arquivo LICENSE para detalhes.