docs(governance): establish repository policies

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @YannLeao @MClaraFerreira5 @EllenRocha1

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Contexto
+
+<!-- Qual problema esta mudança resolve? Inclua a issue ou o card relacionado. -->
+
+Closes #
+
+## Alterações
+
+-
+
+## Validação
+
+- [ ] Testes relevantes executados localmente.
+- [ ] Lint e checagem de tipos executados, quando aplicável.
+- [ ] Documentação, configuração e variáveis de ambiente atualizadas, quando aplicável.
+- [ ] Não foram incluídos segredos, dados de treinamento ou artefatos de modelo.
+
+## Impacto operacional
+
+<!-- Compatibilidade de API, dados, modelo, CI/CD, Docker ou deploy. Use “Nenhum” se não houver. -->
+
+Nenhum.

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contribuindo
+
+Este é um repositório acadêmico privado do projeto MedTrack. Somente integrantes
+autorizados da organização podem criar branches e pull requests.
+
+## Fluxo de contribuição
+
+1. Crie uma branch a partir de `main` para uma issue ou card específico.
+2. Faça mudanças pequenas, testáveis e com escopo explícito.
+3. Use Conventional Commits e referencie a issue no corpo do commit, por exemplo
+   `Refs #123`.
+4. Abra um pull request, descreva a motivação, os testes executados e impactos de
+   configuração ou deploy.
+5. Aguarde os checks obrigatórios e a aprovação de outro integrante antes do merge.
+
+Não faça push direto em `main`, force push em branches protegidas, nem inclua
+dados de treinamento, pesos de modelos, segredos ou arquivos `.env` no Git.
+
+## Revisão
+
+Os responsáveis técnicos atuais são:
+
+| Integrante | Papel |
+| --- | --- |
+| [@YannLeao](https://github.com/YannLeao) | Maintainer e responsável final por releases e merge. |
+| [@MClaraFerreira5](https://github.com/MClaraFerreira5) | Integrante e revisora. |
+| [@EllenRocha1](https://github.com/EllenRocha1) | Integrante e revisora. |
+
+Todo pull request requer pelo menos uma aprovação de um integrante diferente do
+autor. Alterações em API, infraestrutura, segurança, modelo ou dados devem
+explicar a compatibilidade e o plano de validação.
+
+## Convenções
+
+- Prefira `feat`, `fix`, `docs`, `test`, `build`, `ci` e `chore` como tipos de
+  commit.
+- Mantenha documentação operacional em `docs/` e decisões relevantes como ADRs
+  em `docs/adr/`.
+- Não altere o contrato HTTP sem atualizar `docs/contracts/api-v1.md` e alinhar
+  a mudança com os consumidores do ecossistema MedTrack.
+- Execute os checks indicados em [docs/TESTING.md](docs/TESTING.md) antes de
+  solicitar revisão.
+
+Consulte [docs/GOVERNANCE.md](docs/GOVERNANCE.md) para as regras de integração e
+responsabilidades do projeto.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MedTrack Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,167 +1,85 @@
-# MedTrack AI 🧠💊
-### Motor de Visão Computacional e OCR
+# MedTrack AI
 
-O **MedTrack AI** é o motor de inteligência artificial do ecossistema MedTrack. O sistema utiliza um modelo híbrido que combina **YOLOv8** (detecção e localização dos campos na embalagem) e **EasyOCR** (extração textual inteligente), servindo dados estruturados em JSON para o aplicativo mobile em Kotlin via **FastAPI**.
+Serviço de inferência de visão computacional do ecossistema acadêmico MedTrack.
+Ele expõe uma API HTTP com FastAPI e organiza o ciclo de vida do modelo de
+detecção e extração de texto, além das ferramentas de treinamento associadas.
 
----
+O projeto é um protótipo acadêmico. Suas previsões não substituem a conferência
+humana ou a orientação de profissionais de saúde.
 
-## 📦 Estrutura do Repositório
+## Componentes
 
-```
-MedTrack-IA/
-├── src/
-│   ├── api/
-│   │   ├── api.py              # Servidor FastAPI com suporte a medicamentos genéricos
-│   │   ├── ocr_extration.py    # Módulo de processamento de crops e chamadas ao EasyOCR
-│   │   ├── labeling.py         # Ferramenta de anotação manual do dataset via OpenCV
-│   │   └── augmentation.py     # Pipeline de Data Augmentation
-│   └── training/
-│       └── train.py            # Script de fine-tuning do YOLOv8
-├── config/
-│   └── campos.yaml             # Configuração das 6 classes do dataset
-├── data/                       # Imagens brutas (não versionadas no Git)
-├── dataset/                    # Dataset gerado pelo labeling (não versionado no Git)
-├── requirements.txt
-└── README.md
-```
-
----
-
-## 🎯 Classes Detectadas
-
-| ID | Classe | Descrição |
-|----|--------|-----------|
-| 0 | `nome` | Nome comercial do medicamento |
-| 1 | `agente_ativo` | Princípio ativo |
-| 2 | `dosagem` | Concentração/dosagem |
-| 3 | `validade` | Data de validade |
-| 4 | `quantidade` | Quantidade de unidades |
-| 5 | `generico` | Tarja/logo de medicamento genérico |
-
----
-
-## 🛠️ Como Rodar Localmente
-
-### 1. Pré-requisitos
-
-- **Python 3.10 ou superior**
-- Drivers NVIDIA + **CUDA Toolkit** (opcional, recomendado para GTX 1650+)
-
-### 2. Clonar e instalar dependências
-
-```bash
-git clone https://github.com/MClaraFerreira5/MedTrack-IA.git
-cd MedTrack-IA
-pip install -r requirements.txt
-```
+| Área | Responsabilidade |
+| --- | --- |
+| `src/medtrack_ai/api` | Aplicação FastAPI, contrato HTTP, health checks e observabilidade. |
+| `src/medtrack_ai/inference` | Carregamento e execução do modelo de inferência. |
+| `src/medtrack_ai/model_registry` | Leitura e validação do manifesto do artefato de modelo. |
+| `src/training` | Ferramentas de treinamento e aumento de dados. |
+| `config/training` | Configuração versionada do dataset e das classes de treinamento. |
+| `tests` | Testes unitários, de integração e smoke tests opcionais do modelo. |
 
-### 3. Baixar os pesos do modelo (`best.pt`)
+Dados de treinamento, pesos e resultados de execução não são versionados. O
+artefato de inferência é recuperado de um GitHub Release e validado por checksum.
 
-Os pesos do modelo treinado **não são versionados no Git** por boas práticas. Para obtê-los:
+## Início rápido
 
-1. Acesse a aba **Releases** deste repositório
-2. Baixe o arquivo `best.pt` da última versão estável
-3. Coloque o arquivo no caminho:
+O caminho recomendado para desenvolvimento da API é Docker Compose. São
+necessários Docker Desktop, Python 3.11 e `uv` para recuperar o modelo local.
 
-```
-src/training/runs/detect/medtrack_yolo_train/weights/best.pt
+```powershell
+Copy-Item .env.example .env
+uv run --group dev python scripts/fetch_model.py
+docker compose up --build
 ```
 
-### 4. Iniciar o servidor
+Após a inicialização:
 
-```bash
-python src/api/api.py
+```powershell
+Invoke-WebRequest http://localhost:8000/healthz
+Invoke-WebRequest http://localhost:8000/readyz
 ```
 
-A API estará disponível em:
-- **Swagger UI:** [http://localhost:8000/docs](http://localhost:8000/docs)
-- **Endpoint principal:** `POST http://localhost:8000/detect`
-
----
-
-## 📱 Integração com o App Mobile (Kotlin)
+Para encerrar o ambiente:
 
-O celular físico ou emulador não enxerga `localhost` diretamente. Use as configurações abaixo no seu cliente Retrofit:
-
-| Ambiente | URL Base |
-|----------|----------|
-| Emulador Android nativo | `http://10.0.2.2:8000` |
-| Celular físico (Wi-Fi) | URL gerada pelo [Ngrok](https://ngrok.com) |
-
-**Para usar o Ngrok:**
-```bash
-ngrok http 8000
-# Use a URL gerada: https://xxxx.ngrok-free.app/detect
+```powershell
+docker compose down
 ```
 
----
-
-## 🔁 Pipeline de IA
+Consulte o [guia de contêiner](docs/CONTAINER.md) para os pré-requisitos,
+execução sem Compose e detalhes do modelo local.
 
-```
-[Imagem do App Mobile]
-        │
-        ▼ (resize para 640px)
-[Imagem Otimizada]
-        │
-        ▼
-┌─────────────────────────┐
-│   YOLOv8 Nano (GPU)     │ ──► Detecta campos + tarja genérico
-└─────────────────────────┘
-        │
-        ├──► [Tarja genérico detectada] ──► nome = "Medicamento Genérico"
-        │
-        └──► [Crops dos outros campos]
-                    │
-                    ▼
-        ┌───────────────────────┐
-        │   EasyOCR (GPU/CPU)   │ ──► Extrai texto de cada campo
-        └───────────────────────┘
-                    │
-                    ▼
-             JSON estruturado
-```
+## Desenvolvimento e qualidade
 
-**Exemplo de resposta:**
-```json
-{
-  "status": "success",
-  "data": {
-    "nome": "Astro",
-    "agente_ativo": "Sinvastatina",
-    "dosagem": "500mg",
-    "validade": "10/2026",
-    "quantidade": "30 comprimidos",
-    "is_generico": false
-  }
-}
+```powershell
+uv sync --group dev
+uv run --group dev pytest
+uv run --group dev ruff check src tests scripts
+uv run --group dev pyright src/medtrack_ai tests scripts
 ```
-## 📊 Governança de Dados e Dataset (YOLOv8)
-
-Para cumprir os requisitos de reprodutibilidade científica e técnica do modelo, o dataset completo utilizado para o treinamento do `best.pt` foi estruturado e disponibilizado externamente (evitando inflar o tamanho do repositório Git).
-
-* 🔗 **Link de Acesso ao Dataset Estruturado (.zip):** [Link_do_Google_Drive](https://drive.google.com/file/d/1kFx1Vbpx1E5vtfPsAJBaApEtnxy1iSfs/view?usp=sharing)
-
-### 🧬 Estrutura do Arquivo Disponibilizado
-O arquivo compactado segue rigorosamente a arquitetura de diretórios do ecossistema Ultralytics, emparelhando cada imagem ao seu respectivo arquivo de anotação bounding-box (`.txt`):
-* `/train/images/` e `/train/labels/` (Conjunto de treino)
-* `/val/images/` e `/val/labels/` (Conjunto de validação e métricas de acurácia)
-* `campos.yaml` (Mapeamento de caminhos relativos e indexação das classes de fármacos)
----
-
-## ⚠️ Aviso de Uso Responsável
 
-O **MedTrack AI** é um protótipo assistivo desenvolvido para fins **acadêmicos**. O processamento visual e a extração de dados de embalagens são baseados em previsões probabilísticas.
+A estratégia de testes e os comandos opcionais estão em
+[docs/TESTING.md](docs/TESTING.md). Pull requests são validados pelos workflows
+descritos em [docs/CI_CD.md](docs/CI_CD.md).
 
-Este sistema **NÃO substitui**, em nenhuma hipótese:
-- A conferência visual humana da receita médica e da embalagem física
-- A orientação de profissionais de saúde qualificados (médicos, farmacêuticos, enfermeiros)
+## Documentação
 
-Qualquer utilização em cenários reais deve contar com **dupla checagem humana** para garantir a segurança na administração de medicamentos.
+| Tema | Documento |
+| --- | --- |
+| Contrato HTTP | [docs/contracts/api-v1.md](docs/contracts/api-v1.md) |
+| Artefato e versão do modelo | [docs/models/README.md](docs/models/README.md) |
+| Contêiner local | [docs/CONTAINER.md](docs/CONTAINER.md) |
+| CI/CD e versionamento | [docs/CI_CD.md](docs/CI_CD.md) |
+| Deploy de staging | [docs/RAILWAY.md](docs/RAILWAY.md) |
+| Decisões arquiteturais | [docs/adr/README.md](docs/adr/README.md) |
+| Governança | [docs/GOVERNANCE.md](docs/GOVERNANCE.md) |
 
----
+## Contribuição e segurança
 
+O repositório é restrito aos integrantes do projeto MedTrack. As regras de
+contribuição, revisão e responsáveis estão em [CONTRIBUTING.md](CONTRIBUTING.md).
+Relatos de vulnerabilidade devem seguir [SECURITY.md](SECURITY.md), e não ser
+publicados em issues.
 
-## 📄 Licença
+## Licença
 
-Projeto acadêmico — Engenharia da Computação · 2026
+O código está licenciado sob a [MIT License](LICENSE).

SECURITY.md

@@ -0,0 +1,25 @@
+# Política de segurança
+
+## Versões suportadas
+
+O projeto oferece correções de segurança apenas para a versão em desenvolvimento
+na branch `main`. Por ser um protótipo acadêmico, não há garantia de suporte para
+versões históricas ou disponibilidade clínica.
+
+## Relato responsável
+
+Não abra uma issue pública para relatar uma vulnerabilidade. Envie uma mensagem
+para [yann.kjleao@ufrpe.br](mailto:yann.kjleao@ufrpe.br) com:
+
+- descrição e impacto potencial;
+- passos mínimos para reproduzir;
+- versão, commit ou ambiente afetado;
+- sugestão de mitigação, se houver.
+
+O mantenedor confirmará o recebimento em até cinco dias úteis e combinará a
+divulgação e a correção com o relator. Não envie imagens de prescrições, dados
+pessoais, credenciais, tokens ou outros dados sensíveis no relato.
+
+Falhas de qualidade do modelo ou divergências de OCR não são, por si só,
+vulnerabilidades de segurança. Elas devem ser registradas no canal interno do
+projeto, sem anexar dados sensíveis.

docs/GOVERNANCE.md

@@ -0,0 +1,48 @@
+# Governança do repositório
+
+## Escopo e acesso
+
+O MedTrack AI é um projeto acadêmico mantido pela organização MedTrack Project.
+O repositório é fechado a contribuições externas; mudanças são realizadas pelos
+integrantes autorizados e integradas por pull request.
+
+| Responsável | Atribuição |
+| --- | --- |
+| [@YannLeao](https://github.com/YannLeao) | Maintainer, aprovação final, releases e operação. |
+| [@MClaraFerreira5](https://github.com/MClaraFerreira5) | Desenvolvimento e revisão. |
+| [@EllenRocha1](https://github.com/EllenRocha1) | Desenvolvimento e revisão. |
+
+## Integração em `main`
+
+A branch `main` é protegida por rulesets. O fluxo obrigatório é branch de
+trabalho, pull request, checks automatizados e revisão por outra pessoa.
+
+Configuração esperada no GitHub:
+
+- bloquear exclusão e force push;
+- exigir pull request e resolução de conversas;
+- exigir branches atualizadas e status checks aprovados;
+- exigir ao menos uma aprovação;
+- exigir revisão de CODEOWNERS, quando os três integrantes tiverem acesso de
+  escrita confirmado.
+
+`CODEOWNERS` define os três integrantes como responsáveis pelo repositório. O
+arquivo apenas aponta responsáveis; a exigência efetiva de aprovação depende dos
+dois últimos controles no ruleset do GitHub.
+
+## Decisões e mudanças
+
+Mudanças que afetem contratos, modelo, segurança, dados ou operação devem ter
+issue/card associado, validação explícita e, quando envolverem uma decisão
+duradoura, uma ADR em `docs/adr/`.
+
+Os commits seguem Conventional Commits e mencionam a issue relacionada no corpo,
+por exemplo `Refs #123`. As instruções práticas estão em
+[CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Segurança e dados
+
+Vulnerabilidades seguem [SECURITY.md](../SECURITY.md). Dados de treinamento,
+pesos de modelos, segredos e arquivos de ambiente não pertencem ao Git; suas
+regras de armazenamento e recuperação são documentadas nos guias de modelo e
+de operação.