Itera
Companion web de progressão para MMORPGs que ajuda o jogador a decidir seu próximo passo com base no personagem, objetivo, level, vocação, acesso e risco.
Status: MVP web com Path Engine determinístico local. As recomendações usam um catálogo pequeno e regras auditáveis, sem backend ou IA.
Visão do produto
Guias tradicionais apresentam muitas opções, mas raramente explicam qual delas faz sentido para o momento atual do personagem. O Itera organiza caminhos possíveis, evidencia requisitos e comunica por que cada rota é adequada.
O produto não automatiza ações, não lê memória, não controla o cliente do jogo e não joga pelo usuário. Consulte a visão detalhada do produto.
Funcionalidades atuais
- Formulário de personagem com nome, mundo, vocação, level, conta e estilo de jogo.
- Escolha de objetivo entre XP, lucro, tasks, bestiário e exploração.
- Validação inline com React Hook Form e Zod.
- Estado inicial que explica como a recomendação será construída.
- Filtro de elegibilidade por level, vocação, conta e estilo de jogo.
- Ranking determinístico por objetivo, faixa de level e preferência de estilo.
- Até três rotas compatíveis com foco, risco, requisitos, próximo marco e razões do ranking.
- Destaque calculado para a melhor escolha do momento.
- Resumo do perfil usado na recomendação.
- Interface responsiva com navegação por teclado e foco visível.
Escopo do MVP
A primeira entrega cobre a jornada do Itera Path desde a abertura da aplicação até a comparação de três rotas. O objetivo é validar se o jogador entende as alternativas e confia em recomendações explicadas.
Ficam fora deste MVP:
- backend e API;
- banco de dados e persistência;
- autenticação;
- IA ou conteúdo gerado dinamicamente;
- integrações com clientes de jogos;
- automação de ações;
- módulos Chronicle, Guild, Lore e Companion.
Arquitetura geral
flowchart LR
A["React + TypeScript"] --> B["React Hook Form + Zod"]
B --> C["Estado local"]
C --> D["Route Repository local"]
D --> E["Path Engine"]
E --> F["Eligibility + Score"]
F --> G["Recommendation Cards"]
A web atual utiliza React, TypeScript estrito, Vite e Sass. O repositório é um monorepo pnpm workspaces, sem Turborepo enquanto há poucos projetos e nenhuma necessidade real de cache distribuído ou pipeline complexo.
A evolução prevista adiciona Fastify + Zod na API, PostgreSQL + Prisma na persistência e regras TypeScript auditáveis antes de qualquer camada de IA. Veja docs/architecture.md.
User Flow
Abrir Itera Path → Informar perfil → Escolher objetivo → Gerar caminho
→ Comparar três rotas → Escolher rota → Preparar sessão
→ Registrar resultado → Atualizar próximo marco
Esta entrega termina em Comparar três rotas. O fluxo completo está em docs/user-flow.mmd.
Data Flow
No MVP, os dados permanecem inteiramente no navegador:
Character Form → CharacterProfile → Route Repository
→ Eligibility → Score → Recommendation[] → Recommendation Cards
O fluxo atual e o desenho futuro com API e banco estão em docs/data-flow.mmd.
Estrutura
itera/
├── apps/
│ ├── web/
│ │ ├── public/
│ │ ├── src/
│ │ │ ├── app/
│ │ │ ├── components/
│ │ │ ├── data/
│ │ │ │ ├── routeRepository.ts
│ │ │ │ └── routes.ts
│ │ │ ├── domain/ # tipos, regras e testes do Path Engine
│ │ │ ├── pages/
│ │ │ └── styles/
│ │ ├── .dockerignore
│ │ ├── Dockerfile
│ │ └── package.json
│ └── api/ # reservado para Fastify
├── packages/
│ ├── contracts/ # contratos web/API futuros
│ ├── domain/ # regras compartilhadas futuras
│ └── ui/ # componentes compartilhados futuros
├── docs/
│ ├── decisions/
│ │ └── 001-web-first.md
│ ├── architecture.md
│ ├── data-flow.mmd
│ ├── product.md
│ └── user-flow.mmd
├── .env.example
├── compose.yaml
├── package.json
├── pnpm-lock.yaml
└── pnpm-workspace.yaml
Como executar
Pré-requisitos
Para execução manual:
- Node.js 20 ou superior;
- pnpm 10 ou superior.
Para execução containerizada:
Execução rápida com Docker
Na raiz do repositório:
docker compose up --build
A aplicação ficará disponível em http://localhost:5173.
Para encerrar:
docker compose down
O Compose possui somente o serviço web. Os serviços api e db serão adicionados depois que a jornada inicial e os respectivos modelos estiverem validados.
Para publicar outra porta no host, copie .env.example para .env e altere WEB_PORT.
Execução manual com pnpm
Na raiz do repositório:
pnpm install
pnpm dev
A aplicação ficará disponível em http://localhost:5173.
Comandos de qualidade:
pnpm lint
pnpm build
pnpm test
Decisões técnicas
React + Vite
React fornece composição de interface e um ecossistema maduro, enquanto o Vite mantém o ciclo local simples e rápido para a vertical web atual.
Sass co-localizado
Cada página e componente mantém seu próprio arquivo .scss. Tokens e regras globais ficam em src/styles, evitando um arquivo central grande e facilitando localizar a origem de cada estilo.
pnpm workspaces sem Turborepo
O workspace já estabelece limites entre aplicações e pacotes. Turborepo será considerado apenas quando pipelines, cache ou paralelismo entre vários projetos justificarem a camada adicional.
API e persistência futuras
A API futura usará Fastify + Zod. A persistência prevista é PostgreSQL + Prisma. Nenhuma dessas dependências faz parte da entrega atual.
Regras antes de IA
O primeiro motor de recomendação será escrito em TypeScript, com regras determinísticas, testáveis e auditáveis. Uma camada futura de IA poderá usar RAG sobre conteúdo curado para explicar resultados, sem fine-tuning no início.
Docker Compose
O Compose padroniza a execução local do frontend sem substituir o fluxo manual. Volumes separados preservam dependências do container enquanto o código local permanece montado para atualização durante o desenvolvimento.
Acessibilidade
- Campos associados a labels reais.
- Mensagens de validação exibidas junto ao campo correspondente.
- Indicadores de foco visíveis em campos, selects e ação principal.
- HTML semântico para header, main, sections, formulário, cards e listas.
- Contraste alto entre texto, superfícies e estados de destaque.
- Layout responsivo sem depender de interação exclusiva por mouse.
- Linha de progresso identificada com rótulo acessível.
Testes e validações
pnpm lint
pnpm build
pnpm test
docker compose config
A suíte Vitest cobre elegibilidade, ranking por objetivo e a regressão do perfil padrão. Também foram inspecionados manualmente o estado inicial em desktop e mobile, a responsividade do formulário e a renderização da textura visual. Ainda não existe suíte automatizada de componentes ou fluxo ponta a ponta.
Limitações conhecidas
- Catálogo local pequeno, com metadados curados apenas para validar o motor.
- Perfil preenchido manualmente, sem normalização por uma fonte externa.
- Estado mantido somente em memória e perdido ao recarregar.
- Nenhuma ação de escolher rota ou registrar sessão foi implementada.
- Sem backend, banco, conta de usuário ou sincronização entre dispositivos.
- Sem testes automatizados de componentes e navegador.
- O score inicial usa poucos critérios e ainda não considera acesso confirmado, supplies ou tolerância de risco do jogador.
Roadmap
- Expandir o catálogo curado e validar os pesos do Path Engine com jogadores.
- Implementar API com Fastify + Zod.
- Adicionar PostgreSQL + Prisma ao ambiente e ao Compose.
- Definir e implementar autenticação.
- Evoluir Itera Chronicle para histórico de sessões.
- Evoluir Itera Guild para comunidade e formação de party.
- Introduzir explicações apoiadas por RAG sobre conteúdo curado.
- Adicionar testes de componentes, domínio e fluxos ponta a ponta.
Documentação