Rubik's Resolvermapear, resolver, assistir
1 Entrada2 Resolver3 Execução 3D

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.

ScannerMontagem ManualExecução CompletaGuia ESP32Home

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 enviar à máquina e acompanhar o cubo.

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 ESP32 já busca jobs no backend. O próximo passo é ajustar o planner à cinemática final do robô.

1. Visão Geral do Projeto

O sistema lê um cubo 3x3 por câmera, valida o estado, calcula a solução lógica, gera o plano mecânico e acompanha a execução reportada pelo ESP32.

1Scanner
2Validação
3Solver
4Animação
5Planner Mecânico
6ESP32

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, fila/polling ESP32 e fallback mock.

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

Backend no mesmo app

API routes Next.js para validate, solve, registro do ESP32, fila, sessão, start e 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, fila ESP32 e sessão
    • 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, fila ESP32, fallback mock e sessão ativa.

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 visualização deriva o cubo a partir de `logicalMoves` e `initialCubeState`. Quando a máquina reporta progresso, esse índice controla o estado exibido.

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 enviado ao backend e então ao ESP32.

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 usa o backend Next.js como fila pública. O ESP32 busca jobs e reporta progresso, então não precisa receber conexão no IP local.

GET/api/health

status geral da aplicação

POST/api/cube/validate

validar CubeState

POST/api/cube/solve

gerar logicalMoves

POST/api/device/register

registrar presença do ESP32

GET/api/device/jobs/next

ESP32 buscar próximo job

POST/api/device/jobs/status

ESP32 reportar progresso

POST/api/machine/session

assumir operação

POST/api/machine/start

iniciar máquina

GET/api/machine/status

consultar status da execução

Sincronização visual

A UI usa `progress.currentLogicalMoveIndex` retornado por `GET /api/machine/status` para exibir o estado atual do cubo físico.

10. Fluxo Ponta a Ponta

  1. Capturar ou montar o cubo (`/scan` ou `/manual`).
  2. Validar estado no backend (`/api/cube/validate`).
  3. Calcular solução lógica (`/api/cube/solve`).
  4. Criar `SolveSession` com `mechanicalPlan`.
  5. Abrir `/solve` e assumir a operação.
  6. Enfileirar o plano para o ESP32 ou usar o fallback mock.
  7. Acompanhar status e 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.

Visualização baseada em logicalMoves

Permite derivar o estado atual do cubo a partir do progresso físico sem exigir que o ESP32 conheça a lógica do cubo.

Polling ESP32 com fallback mock

Mantém a demo funcionando sem hardware e permite que o ESP32 funcione atrás de NAT, buscando jobs no backend público.

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 de máquina, operador, polling ESP32 e fallback mock

Próxima etapa

  • Ajustar `MechanicalAction[]` à cinemática final
  • Persistir sessão ativa fora da memória do processo
  • Validar o tempo real dos atuadores no robô físico
  • Refinar sensores/feedback para progresso mais preciso