# Arquitetura e Visão — API-Scardua

> Documento da **ideia** do projeto: o quê, o porquê e o roadmap. Salvo pra não
> reexplicar toda sessão. Atualizar quando a visão evoluir.

## Em uma frase

Uma API que **recebe** dados do Holmes do cliente, **trata**, e **envia** de volta
pro banco do cliente — hospedada na infra do dev (FLS), não na do cliente.

## Os atores

- **FLS Tecnologia (dev / nós)** — constrói e hospeda a API na **própria VPS**
  (`api-scardua.flstecnologia.tech`). A infra e o código são nossos.
- **Comercial Scardua (cliente)** — tem a conta no **Holmes** e um banco **Oracle**
  (IP privado, `10.16.x` — não acessível pela internet).
- **Holmes** — SaaS externo de workflow de documentos; dispara os dados (webhook)
  pra nossa API.

## O fluxo

```
Holmes  --webhook-->  [API na VPS da FLS]  --trata-->  [Conector no server do cliente]  -->  [Oracle do cliente]
```

1. O Holmes envia os dados pra nossa API (URL pública, TLS).
2. A API recebe e **trata** os dados.
3. A API fala com o **banco do cliente** através de um **conector que roda no
   servidor do cliente** (que tem acesso à rede privada do Oracle).

## As decisões e o PORQUÊ (o mais importante)

A API fica na **nossa VPS**, e não no servidor do cliente, por 2 motivos:

1. **Não depender de o cliente ter domínio / rota pública.** O Holmes precisa de
   um endpoint público e estável pra mandar os webhooks — damos isso nós, com
   domínio + TLS próprios.
2. **Não deixar nosso código Python no servidor do cliente.** A lógica fica sob
   nosso controle, na nossa infra.

**Consequência técnica:** como o Oracle do cliente está numa rede privada
(`10.16.x`), a VPS **não alcança o banco direto**. Por isso existe o **conector no
server do cliente** — ele é a ponte entre a API (pública) e o Oracle (privado).

## Roadmap

| # | Fase | Estado |
|---|---|---|
| 1 | **Receber dados** — esqueleto da API, rota de teste, deploy na VPS | ✅ feito |
| 2 | **Lógica do Holmes** — ligar os endpoints `/v1/holmes/...` ao serviço `app/services/holmes.py` (hoje `obter_dados_compras` é stub) | ⏳ em andamento (dev) |
| 3 | **Conector no cliente** — a ponte API (VPS) ↔ Oracle do cliente (rede privada) | ⬜ a fazer |
| 4 | **CI/CD** — Forgejo Actions (valida no PR/main) + registry + auto-update pull-based (ver [deploy.md](deploy.md)) | ⬜ desenhado |

## Pontos em aberto

- **Como** o conector no cliente vai funcionar — duas abordagens possíveis:
  - **Túnel/VPN reverso**: o server do cliente abre um túnel e a VPS passa a
    alcançar o `10.16.x` → a API conecta no Oracle direto (é o que o código de
    hoje assume: `oracledb` com o DSN privado em `configs.json`).
  - **Agente HTTP no cliente**: um serviço no server do cliente que a API chama;
    ele consulta o Oracle **localmente** e devolve o resultado (aí a API nunca
    toca no Oracle direto).
- Essa escolha decide o destino do `app/infra/database.py` (hoje faltando):
  conexão direta via túnel, ou um cliente HTTP pro agente.