Apresentação Técnica Interativa

Arquitetura do Rubik's Cube Resolver Bot

Guia visual para onboarding: organização do código, fluxo ponta a ponta, contratos de integração e decisões de arquitetura já aplicadas no projeto.

Scanner Montagem Manual Execução Completa Guia ESP32 Home

Comece por aqui

Esta página ficou organizada para onboarding. Antes de mergulhar nos detalhes, use estes três blocos para saber por onde ler.

Se você quer usar o produto

Comece em Scanner ou Manual. Depois siga para Execução para ver máquina mock e animação.

Se você quer entender o código

Leia nesta ordem: Visão Geral, Arquitetura, Pastas, Domínio do Cubo e Integração da Máquina.

Se você quer saber o que falta

O backend, o planner e o mock já estão prontos. O próximo passo é trocar o mock pelo firmware real do ESP32.

1. Visão Geral do Projeto

O sistema lê um cubo 3x3 por câmera, valida o estado, calcula a solução lógica, anima a resolução e já prepara o plano mecânico para integração futura com ESP32.

1Scanner

2Validação

3Solver

4Animação

5Planner Mecânico

6ESP32 (futuro)

2. Arquitetura do Sistema

Frontend e backend convivem no mesmo app Next.js. A separação é feita por camadas e contratos tipados, não por múltiplos repositórios.

UI e Experiência

Páginas App Router e componentes para scanner, edição manual, execução e onboarding técnico.

src/app + src/components

Domínio do Cubo

Modelagem do estado, validação semântica, aplicação de movimentos e serialização para solver.

src/lib/cube

Camada de Execução

Sessão consolidada de execução e player de animação baseado em logicalMoves.

src/lib/solve-session + src/hooks

Camada de Máquina

Planejamento mecânico abstrato, contratos tipados e gateway mock para troca futura pelo ESP32.

src/lib/machine + src/types/machine.ts

Backend no mesmo app

API routes Next.js para validate, solve, machine start e machine status.

src/app/api

3. Estrutura de Pastas

A árvore abaixo reflete os diretórios mais importantes da base atual.

DIRsrc
- DIRappPáginas e API routes
  - FILEpage.tsxHome e navegação principal
  - FILEscan/page.tsxFluxo de scanner
  - FILEmanual/page.tsxMontagem manual
  - FILEsolve/page.tsxExecução completa
  - FILEarchitecture/page.tsxApresentação técnica
  - DIRapi/Endpoints internos
- DIRcomponentsUI por contexto de uso
  - DIRscanner/Captura guiada e revisão
  - DIRsolve/Player e sessão de execução
  - DIRcube/Viewer 2D do cubo
- DIRlibLógica de domínio e integração
  - DIRcube/Domínio do cubo
  - DIRscanner/Leitura de cor da câmera
  - DIRsolve-session/Sessão consolidada de execução
  - DIRmachine/Planner, contratos e mock
- DIRtypesContratos TypeScript compartilhados
DIRdocsDocumentação técnica consolidada

src/app

Rotas visuais e endpoints API no padrão App Router.

src/components

Componentes focados em UX para cada fluxo do produto.

src/lib/cube

Domínio puro do cubo: estado, regras, movimentos e solver.

src/lib/machine

Planejamento mecânico abstrato, mock e contratos de gateway.

src/types

Tipos compartilhados entre interface, APIs e domínio.

docs

Documentação de arquitetura, scanner, solver, animação e máquina.

4. Domínio do Cubo

Esta camada existe separada da interface para garantir previsibilidade, testes e reuso entre scanner, manual, API e animação.

CubeState representa o cubo completo com 6 faces. Cada face tem exatamente 9 stickers.

type Face = "U" | "R" | "F" | "D" | "L" | "B";
type Color = "white" | "red" | "green" | "yellow" | "orange" | "blue";
type FaceStickers = [Color, Color, Color, Color, Color, Color, Color, Color, Color];
type CubeState = Record<Face, FaceStickers>;

Por que separar domínio da UI?

Porque a regra do cubo é a mesma em qualquer entrada (scanner/manual). A UI apenas coleta dados e exibe resultados; a verdade do negócio fica em `src/lib/cube`.

5. Scanner por Câmera

O scanner usa `getUserMedia`, guia visual 3x3 e revisão manual obrigatória. O cubo pode estar resolvido ou bagunçado.

Captura guiada

Uma face por vez em ordem `U/R/F/D/L/B`, com confirmação explícita.

Leitura de cores

Heurística leve com confiança por face, sem visão computacional pesada no MVP.

Correção manual

Usuário edita qualquer sticker antes de enviar para validação/solve.

6. Validação e Solver

O backend garante que só estados coerentes cheguem ao solver. Isso evita falhas silenciosas e melhora mensagens para o usuário.

Validação

Checa estrutura, cores, contagem e centros.

POST /api/cube/validate
{ "cubeState": { ... } }

Solve

Recebe CubeState válido e retorna movimentos lógicos.

POST /api/cube/solve
{
  "jobId": "cube-001",
  "initialCubeState": { ... },
  "logicalMoves": ["R", "U", "R'", "U'", "F2"]
}

7. Animação da Solução

A animação usa apenas `logicalMoves` e `initialCubeState`. Ela não depende de comandos mecânicos para avançar frame a frame.

Estado inicial

applyMove/applyMoves

Atualização visual 2D

Progresso e movimento atual

Estado final resolvido

8. Planner Mecânico

O planner converte solução lógica em um plano físico serializável para integração futura com a máquina.

logicalMoves

Semântica do cubo, independente de hardware.

["R", "U", "R'", "U'", "F2"]

mechanicalPlan

Ações executáveis por uma controladora física.

{
  "jobId": "cube-001",
  "actions": [
    { "type": "home", "target": "all" },
    { "type": "clamp", "name": "A", "state": "close" },
    { "type": "turn_face", "actuator": "right", "degrees": 90 }
  ]
}

9. Integração com a Máquina

A integração já está preparada por contrato e mock. O firmware real ainda não foi implementado.

GET/api/health

status geral da aplicação

POST/api/cube/validate

validar CubeState

POST/api/cube/solve

gerar logicalMoves

POST/api/machine/start

iniciar máquina mock

GET/api/machine/status

consultar status da execução

Trigger da animação

A UI inicia a animação quando `GET /api/machine/status` retorna `started`. O restante da animação roda localmente com os movimentos lógicos já calculados.

10. Fluxo Ponta a Ponta

Capturar ou montar o cubo (`/scan` ou `/manual`).
Validar estado no backend (`/api/cube/validate`).
Calcular solução lógica (`/api/cube/solve`).
Criar `SolveSession` com `mechanicalPlan`.
Abrir `/solve` e iniciar execução da máquina mock.
Receber status `started` e disparar animação.
Concluir visualização com progresso até o final.

11. Decisões de Arquitetura

Projeto único em Next.js (frontend + backend)

Reduz fricção de desenvolvimento e facilita demo, mantendo tipagem compartilhada e deploy simplificado.

Scanner guiado em vez de visão avançada no MVP

Priorizou confiabilidade prática com revisão manual, sem criar dependência de modelos pesados para esta fase.

Animação baseada em logicalMoves

Mantém a experiência visual desacoplada do hardware e permite teste completo mesmo sem ESP32 real.

Integração futura via contrato + mock

Permite trocar apenas o gateway da máquina quando firmware estiver pronto, preservando páginas, endpoints e tipos centrais.

12. Resumo Final

Já implementado

Modelagem e validação do cubo
Solver lógico e serialização
Scanner guiado com revisão manual
Animação em tempo real baseada em logicalMoves
Planner mecânico abstrato
API e mock de máquina

Próxima etapa (ESP32)

Firmware para executar `MechanicalAction[]`
Canal de comunicação real com o backend
Publicação de status `queued/started/finished/error`
Substituição do mock sem quebrar contratos