Arquitetura

Visão Geral

O projeto é dividido em camadas independentes que se comunicam via HTTP/REST.

┌─────────────────────────────────────────────────────┐
│                    Clientes                          │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │ Web Demo │  │ Mobile Demo  │  │ curl / outros │  │
│  │ React    │  │ React Native │  │               │  │
│  └────┬─────┘  └──────┬───────┘  └───────┬───────┘  │
│       │               │                  │          │
│  ┌────v─────┐         │                  │          │
│  │ JS/WASM  │         │                  │          │
│  │ Preview  │         │                  │          │
│  └────┬─────┘         │                  │          │
└───────┼───────────────┼──────────────────┼──────────┘
        │               │                  │
        └───────────────┼──────────────────┘
                        │
                  POST /api/process
                        │
              ┌─────────v──────────┐
              │   FastAPI Backend   │
              │                    │
              │  - Recebe imagem   │
              │  - Valida input    │
              │  - Chama SDK       │
              │  - Retorna JSON    │
              └─────────┬──────────┘
                        │
              ┌─────────v──────────┐
              │   Python SDK       │
              │                    │
              │  1. SkinDetector   │
              │  2. FingerSegmenter│
              │  3. FingerOrienter │
              │  4. FingertipROI   │
              │  5. RidgeEnhancer  │
              │  6. QualityChecker │
              └────────────────────┘

Componentes

Python SDK (sdk/)

Pacote Python puro que executa o pipeline de 6 etapas. Stateless e thread-safe — uma instância de FingerprintExtractor pode processar múltiplas imagens concorrentemente.

Dependências: apenas opencv-python-headless e numpy.

FastAPI Backend (api/)

Camada HTTP fina sobre o SDK. Responsabilidades:

• Receber imagens via multipart/form-data
• Validar tipo e tamanho do arquivo
• Instanciar o extractor como singleton
• Retornar resultado como JSON (com imagem em base64)
• CORS configurável

JS/WASM Preview (js/)

Biblioteca TypeScript leve para guiar o posicionamento do dedo em tempo real no browser. Usa opencv.js para detecção de pele com os mesmos thresholds YCrCb/HSV do SDK Python. Não faz processamento — apenas guia visual.

Web Demo (web/)

Aplicação React/Vite que demonstra o fluxo completo:

1. Captura via câmera ou upload de arquivo
2. Preview em tempo real com guia de posicionamento
3. Envio para API
4. Exibição do resultado com métricas de qualidade

Mobile Demo (mobile/)

Aplicação React Native/Expo que demonstra captura mobile:

1. Câmera fullscreen com guia estático
2. Captura ou seleção da galeria
3. Envio para API
4. Exibição do resultado

Fluxo de Dados

Imagem (JPEG/PNG)
    │
    ▼
[Upload multipart] ──→ FastAPI valida ──→ SDK processa
                                              │
                                              ▼
                                        FingerprintResult
                                              │
                                              ▼
                                    JSON + imagem base64
                                              │
                                              ▼
                                      Cliente renderiza

Estrutura do Projeto

sdk-digital/
├── sdk/                # Python SDK de processamento
│   └── fingerprint_sdk/
│       ├── extractor.py    # FingerprintExtractor (orchestrator)
│       ├── config.py       # ExtractorConfig (40+ parâmetros)
│       ├── models.py       # FingerprintResult, QualityReport
│       └── pipeline/       # 6 estágios do processamento
├── api/                # FastAPI backend
│   └── app/
│       ├── main.py         # App setup + CORS
│       ├── routes.py       # /health, /process
│       ├── schemas.py      # Pydantic models
│       └── settings.py     # Configuração via env
├── js/                 # Preview JS/WASM
├── web/                # Demo React/Vite
├── mobile/             # Demo React Native/Expo
├── site/               # Este site de documentação
└── docs/               # Documentação markdown

Decisões Técnicas

Decisão	Motivo
Python 3.8+	Compatibilidade ampla, disponível em Docker slim
pydantic v1	Compatível com Python 3.8 e FastAPI estável
opencv-python-headless	Sem dependências GUI, menor tamanho
opencv.js no browser	Mesmos algoritmos do SDK Python, roda no client
Processamento no server	Pipeline pesado (GrabCut, Gabor) precisa de CPU
Preview no client	Feedback em tempo real sem latência de rede
Expo para mobile	Setup rápido, funciona iOS + Android