SENTE-AI [WIP]

Plataforma de análise acústica que traduz áudio em feedback háptico: extração de features acústicas, geração de anotações de vibração por zona e visualização 3D da cadeira.

---

Documentação

Documento	Descrição
docs/README.md	Índice geral da documentação
docs/DATASET.md	Pipeline DVC e estrutura do dataset
docs/security_credentials_guide.md	Guia de segurança e credenciais
backend/src/ARCHITECTURE.md	Arquitetura do pipeline de ML
backend/src/MODELS.md	Modelos de redes neurais
backend/src/PIPELINE.md	Fluxo de dados ponta a ponta

---

Stack

Camada	Tecnologias
Frontend	Next.js 14, TypeScript, Three.js, Tailwind CSS
Backend	Python 3.10+, FastAPI, librosa, PyTorch, nnAudio
Dataset	DVC (local), NumPy, pandas
Infra	Docker, Docker Compose

---

Como rodar (recomendado: Docker)

Requisitos

• Docker e Docker Compose
• (Opcional, para dev local sem Docker) Python 3.10+ e Node.js 18+

Passos rápidos

# 1. Configure as variáveis de ambiente
cp .env.example .env
# Edite .env com seus valores locais

# 2. Suba todos os serviços
docker compose up --build

Serviços disponíveis após o build:

Serviço	URL	Descrição
Frontend	http://localhost:3000	Interface Next.js
Backend	http://localhost:8000	API FastAPI
Health	http://localhost:8000/health	Health check

# Parar os serviços
docker compose down

Variáveis de ambiente (.env)

Variável	Padrão	Descrição
NEXT_PUBLIC_BACKEND_URL	http://localhost:8000	URL da API vista pelo navegador
ALLOWED_ORIGINS	http://localhost:3000	CORS do backend
MAX_FILE_SIZE_MB	200	Tamanho máximo de upload (MB)

Segurança: nunca commite o arquivo .env real. Veja docs/security_credentials_guide.md.

---

Desenvolvimento local (sem Docker)

Backend (Python / FastAPI)

# Na raiz do projeto
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
# ou .venv\Scripts\activate    # Windows

pip install -e ".[full]"       # instala librosa, pandas, dvc, torch, etc.

# Sobe a API
uvicorn backend.api.main:app --reload --host 0.0.0.0 --port 8000

Frontend (Next.js)

cd frontend
npm install
npm run dev

O frontend espera o backend em http://localhost:8000 (configurável via .env).

---

Smoke test (visualizador 3D)

Para verificar apenas o frontend sem depender do backend:

cd frontend
npm install
npm run dev

Abra http://localhost:3000/chair, faça upload de um arquivo de áudio e pressione Play. A poltrona deve colorir em tons pastéis conforme as bandas de frequência (bass / mid / treble).

O projeto inclui uma poltrona low-poly CC0 em public/models/recliner_cc0.obj.

---

Dataset (vibrações para treino)

Pipeline que transforma stems em matrizes de vibração densas (.npy, shape [N, 4] a cada 100 ms para as 4 zonas) e um manifest.csv.

Documentação completa em → docs/DATASET.md

Comandos diários (de dentro de dataset/):

cd dataset
dvc repro generate_vibrations build_manifest
git add dvc.lock
git commit -m "chore: atualiza dvc.lock"

---

Estrutura do repositório

.
├── backend/
│   ├── api/            # FastAPI — endpoints /analyze e /analyze/stream
│   ├── core/           # Extração de features, geração de anotações, color mapper
│   ├── src/            # Pipeline de ML: config, áudio, modelos, engine
│   │   ├── ARCHITECTURE.md
│   │   ├── MODELS.md
│   │   ├── PIPELINE.md
│   │   ├── audio_processing.py
│   │   ├── config.py
│   │   ├── dataset_loader.py
│   │   ├── engine/
│   │   └── models/
│   └── notebooks/      # Experimentos e prototipagem
├── frontend/           # Next.js — upload, relatório, visualizador 3D
├── dataset/            # Pipeline DVC (dvc.yaml + scripts/)
├── docs/               # Documentação centralizada
├── docker-compose.yml
├── .env.example
└── pyproject.toml

---

Segurança

Nunca commite secrets.

Leia o guia em docs/security_credentials_guide.md e a política em SECURITY.md.

Pontos principais:

• .env gitignored; use .env.example como template
• Containers rodando com usuário não-root
• Cache DVC local e gitignored
• Checklist para novos membros no guia de segurança

---

Contribuindo

1. Leia docs/README.md para o índice completo da documentação.
2. Configure .env a partir de .env.example.
3. Para o dataset, use DVC local — veja docs/DATASET.md.
4. Siga as práticas de segurança descritas em docs/security_credentials_guide.md.