Routing

O template usa React Router v7 com SSR. A definicao de rotas usa a API @react-router/dev/routes.

Route Registry

O Route Registry e o sistema centralizado de rotas configuraveis por brand. Ele separa a definicao de URLs (paths) da arvore de rotas (route tree), permitindo que brands customizem todos os paths de pagina sem tocar em componentes ou no routes.config.ts.

Arquivos

Arquivo	Descricao
app/types/routes.ts	Tipos: RoutePathMap, RouteParamsMap, StaticRouteKey, DynamicRouteKey
app/config/routes/paths.ts	Mapa padrao de paths (overridavel por brand)
app/utils/routes.ts	Helpers: routeHref(), routePattern(), gameHref(), sportPath(), isRouteActive(), validateRoutePaths()
overrides/<brand-key>/app/config/routes/paths.ts	Override de paths por brand

Helpers — ~/utils/routes

Funcao	Descricao	Exemplo
routePattern(key)	Pattern para route config (sem / inicial)	routePattern('casino.play') → 'games/:provider/:game'
routeHref(key)	URL para rota estatica	routeHref('casino') → '/games'
routeHref(key, params)	URL para rota dinamica	routeHref('casino.play', { provider: 'pgsoft', game: 'tiger' }) → '/games/pgsoft/tiger'
gameHref(slug)	URL de jogo a partir de slug provider/game	gameHref('pgsoft/fortune-tiger') → '/games/pgsoft/fortune-tiger'
sportPath(subPath)	Deep-link prefixado com base do sports	sportPath('/live') → '/sports/live'
isRouteActive(key, pathname)	Verifica se pathname match uma rota	isRouteActive('casino', '/games/category/slots') → true
validateRoutePaths(paths)	Valida RoutePathMap (build-time)	Usado no startup do server

Como app/router/routes.ts resolve o override

O app/router/routes.ts importa routePattern() de ~/utils/routes, que por sua vez importa routePaths de ~/config/routes.paths. O Vite plugin de overrides redireciona ~/config/routes.paths para o arquivo da brand (se existir) baseado em ORIGIN_DOMAIN.

ORIGIN_DOMAIN=state77.com
    → brand-key = state77-com
    → ~/config/routes.paths → overrides/state77-com/app/config/routes/paths.ts
    → routePattern('casino') → 'casino' (sem /)
    → routeHref('casino') → '/casino'

Regras

• Nomes de parametros sao fixos: :slug, :provider, :game, :id, :type, :token — components usam useParams() com esses nomes exatos
• Brands so customizam segmentos estaticos do path
• Rotas de API nao entram no registro — sao endpoints internos do servidor
• Override deve ser completo — TypeScript da erro se faltar alguma chave

---

routes.ts (entry point)

O arquivo app/routes.ts na raiz do app/ e o entry point do routing. Ele importa buildRoutes() do registro de rotas:

// app/routes.ts
import type { RouteConfig } from '@react-router/dev/routes';
import { buildRoutes } from './router/routes';

export default buildRoutes() satisfies RouteConfig;

cuidado

routes.ts usa import relativo ./router/routes — tilde alias (~/router/routes) nao funciona aqui por limitacao do React Router.

app/router/routes.ts (registro de rotas)

O arquivo app/router/routes.ts define toda a arvore de rotas. Usa routePattern() para obter os paths do Route Registry. Forks editam este arquivo diretamente para adicionar/remover paginas.

informação

Este arquivo foi movido de app/config/routes.config.ts para app/router/routes.ts na refatoração do sistema de layout (v0.7). O app/config/ agora contém apenas configuração brand-editável.

A arvore esta organizada em:

1. Resource routes — fora do layout, sem DefaultLayout wrapper
2. API routes — server-only actions, organizadas por dominio
3. Page routes — dentro do layout(), renderizadas com DefaultLayout
4. User area — nested layout com autenticacao obrigatoria

---

Resource Routes (fora do layout)

Rota	Arquivo	Descricao
manifest.json	routes/manifest[.]json.ts	PWA manifest
sitemap.xml	routes/sitemap[.]xml.ts	Sitemap dinamico
robots.txt	routes/robots[.]txt.ts	Robots.txt

Auth API Routes

Rota	Arquivo	Descricao
api/auth/login	routes/api.auth.login.ts	Login
api/auth/register	routes/api.auth.register.ts	Registro
api/auth/social/:provider	routes/api.auth.social.$provider.ts	Inicia/fecha callback de auth social
api/auth/logout	routes/api.auth.logout.ts	Logout
api/auth/profile	routes/api.auth.profile.ts	Perfil do usuario

Validation API Routes

Rota	Arquivo	Descricao
api/validation/email/send	routes/api.validation.email.send.ts	Envia codigo por email
api/validation/email/verify	routes/api.validation.email.verify.ts	Verifica codigo de email
api/validation/email/change	routes/api.validation.email.change.ts	Altera email
api/validation/sms/send	routes/api.validation.sms.send.ts	Envia codigo por SMS
api/validation/sms/verify	routes/api.validation.sms.verify.ts	Verifica codigo de SMS
api/validation/sms/change	routes/api.validation.sms.change.ts	Altera telefone
api/validation/docs/submit	routes/api.validation.docs.submit.ts	Submete documentos
api/validation/address/submit	routes/api.validation.address.submit.ts	Submete endereco
api/validation/terms/accept	routes/api.validation.terms.accept.ts	Aceita termos

User API Routes

Rota	Arquivo	Descricao
api/user/update-address	routes/api.user.update-address.ts	Atualiza endereco
api/user/update-limits	routes/api.user.update-limits.ts	Atualiza limites
api/user/check-password	routes/api.user.check-password.ts	Verifica senha atual
api/user/add-phone	routes/api.user.add-phone.ts	Adiciona telefone

Wallet API Routes

Rota	Arquivo	Descricao
api/wallet/refresh	routes/api.wallet.refresh.ts	Atualiza saldo
api/wallet/transactions	routes/api.wallet.transactions.ts	Historico de transacoes
api/wallet/action	routes/api.wallet.action.ts	Acoes de bonus/cashback
api/wallet/receipt	routes/api.wallet.receipt.ts	Comprovante de saque

Payments API Routes

Rota	Arquivo	Descricao
api/payments/providers	routes/api.payments.providers.ts	Lista providers de pagamento
api/payments/deposit	routes/api.payments.deposit.ts	Deposito
api/payments/deposit-status	routes/api.payments.deposit-status.ts	Status do deposito
api/payments/withdraw	routes/api.payments.withdraw.ts	Saque
api/payments/bank-list	routes/api.payments.bank-list.ts	Lista de bancos
api/payments/pix-key	routes/api.payments.pix-key.ts	Chave PIX
api/payments/coupon	routes/api.payments.coupon.ts	Validacao de cupom

Games API Routes

Rota	Arquivo	Descricao
api/games/search	routes/api.games.search.ts	Busca server-side contra cache
api/games/start	routes/api.games.start.ts	Start-game (autenticado)
api/games/vote	routes/api.games.vote.ts	Like/dislike (autenticado)
api/cache/games/purge	routes/api.cache.games.purge.ts	Invalidacao de cache via webhook

Sports API Routes

Rota	Arquivo	Descricao
api/sports/search	routes/api.sports.search.ts	Busca no sportsbook
api/sports/launch	routes/api.sports.launch.ts	Launch autenticado
api/sports/anonymous-launch	routes/api.sports.anonymous-launch.ts	Launch anonimo
api/sports/betby-jwt	routes/api.sports.betby-jwt.ts	JWT para Betby
api/sports/altenar-token	routes/api.sports.altenar-token.ts	Token para Altenar

KYC API Routes

Rota	Arquivo	Descricao
api/kyc/start	routes/api.kyc.start.ts	Inicia KYC
api/kyc/status	routes/api.kyc.status.ts	Status do KYC

Search API

Rota	Arquivo	Descricao
api/search/unified	routes/api.search.unified.ts	Busca unificada (games + sports)

Dev Tools

Rota	Arquivo	Descricao
api/dev/cache-clear	routes/api.dev.cache-clear.ts	Limpa cache (dev only)

Rota Embeddable

Rota	Arquivo	Descricao
_/footer	routes/_._footer.tsx	Footer embeddable para iframe do First

---

Page Routes (dentro do layout)

Todas as rotas abaixo sao renderizadas dentro do layout("routes/_layout.tsx"), que carrega DefaultLayout com Header, Sidebar, Footer e providers.

:::info Route Registry Os paths mostrados abaixo sao os defaults. Brands podem customizar todos os paths via override em overrides/<brand-key>/app/config/routes/paths.ts. O routes.config.ts usa routePattern(key) para resolver o path correto. :::

Paginas Gerais

Chave	Path padrao	Arquivo	Descricao
home	/	routes/_index.tsx	Homepage com carrosseis de jogos por categoria (SSR)
search	/search	routes/search.tsx	Pagina de busca
debug	/debug	routes/debug.tsx	Pagina de debug (dev)

Games / Casino

Chave	Path padrao	Arquivo	Descricao
casino	/games	routes/games/_index.tsx	Listagem geral de games
casino.live	/games/live	routes/games/live.tsx	Casino ao vivo
casino.category	/games/category/:slug	routes/games/category.$slug.tsx	Jogos de uma categoria (SSR + SEO)
casino.providers	/games/providers	routes/games/providers._index.tsx	Listagem de providers (SSR)
casino.provider	/games/providers/:slug	routes/games/providers.$slug.tsx	Jogos de um provider (SSR + SEO)
casino.play	/games/:provider/:game	routes/games/$provider.$game.tsx	Detalhe do jogo com iframe, votos, stats (SSR + SEO + JSON-LD)

Sports

O sportsbook usa um nested layout (routes/sports/_layout.tsx) para manter o componente do sportsbook montado entre sub-rotas.

Chave	Path padrao	Arquivo	Descricao
sports	/sports	routes/sports/_index.tsx	Pagina principal do sportsbook
sports.catchAll	/sports/*	routes/sports/$.tsx	Catch-all para rotas internas do sportsbook
sports.test	/sports-test	routes/sports-test.tsx	Sportsbook de teste (opcional)

VIP / Gamificacao

Chave	Path padrao	Arquivo	Descricao
gamification	/vip	routes/vip/_index.tsx	Hub VIP (Smartico)
gamification.missions	/vip/missions	routes/vip/missions.tsx	Missoes
gamification.tournaments	/vip/tournaments	routes/vip/tournaments.tsx	Torneios
gamification.tournament	/vip/tournaments/:id	routes/vip/tournaments.$id.tsx	Detalhe de torneio
gamification.store	/vip/store	routes/vip/store.tsx	Loja VIP
gamification.miniGames	/vip/mini-games	routes/vip/mini-games.tsx	Mini-games
gamification.levels	/vip/levels	routes/vip/levels.tsx	Niveis VIP
gamification.badges	/vip/badges	routes/vip/badges.tsx	Badges
gamification.bonuses	/vip/bonuses	routes/vip/bonuses.tsx	Bonus VIP

Legal e Help Center

Chave	Path padrao	Arquivo	Descricao
legal.page	/page/:slug	routes/page.$slug.tsx	Paginas legais dinamicas (termos, privacidade, etc.)
helpCenter	/ajuda	routes/ajuda.tsx	Central de ajuda

User (fora do user layout)

Chave	Path padrao	Arquivo	Descricao
user.notifications	/user/notifications	routes/user/notifications.tsx	Notificacoes (full width)
user.validate	/user/validate/:type/:token	routes/user/validate.$type.$token.tsx	Validacao por link (email/sms)

User Area (auth-protected, navegacao em abas)

Estas rotas sao renderizadas dentro do nested layout routes/user/_layout.tsx, que implementa navegacao em abas e exige autenticacao.

:::info Novo modelo de abas A area do usuario foi refatorada para um modelo de abas. As rotas user.account, user.security, user.loginHistory, user.accountProtection e user.irpf foram removidas e substituidas pelas rotas abaixo. :::

Chave	Path padrao	Arquivo	Descricao
user.data	/user/data	routes/user/data.tsx	Dados pessoais e seguranca
user.wallet	/user/wallet	routes/user/wallet.tsx	Carteira e metodos de pagamento
user.history	/user/history	routes/user/history.tsx	Historico de transacoes e logins
user.config	/user/config	routes/user/config.tsx	Configuracoes e jogo responsavel
user.protection	/user/protection	routes/user/protection.tsx	Protecao de conta e limites
user.refers	/user/refers	routes/user/refers.tsx	Indique e ganhe (referral)

---

_layout.tsx (loader)

O _layout.tsx e um layout route que:

1. Carrega a configuracao de brand no server (loader)
2. Monta clientEnv com variaveis necessarias no browser
3. Carrega auth (user + userInfo) se existir sessao
4. Renderiza o DefaultLayout (que usa layoutConfig do sistema de composição)

export async function loader({ context }: Route.LoaderArgs) {
  const env = context.cloudflare?.env ?? process.env;
  const brand = await loadBrandConfig(env);
  const clientEnv = { API_BASE_URL: env.API_BASE_URL, ... };
  return { brand, clientEnv };
}

Dicas

• Edite app/router/routes.ts para adicionar/remover paginas — o app/routes.ts apenas importa buildRoutes() dali
• Use routePattern(key) no app/router/routes.ts ao inves de strings hardcoded — assim os paths sao resolvidos pelo Route Registry
• Use routeHref(key) ou gameHref(slug) para links em componentes — nunca paths hardcoded
• Use layout() para nested layouts e index() para a pagina default de um grupo
• Forks podem criar qualquer pagina nova em app/routes/ e registra-la em app/router/routes.ts
• API routes sao server-only — nao geram bundle client-side e nao fazem parte do Route Registry
• Resource routes (manifest.json, sitemap.xml, robots.txt) ficam fora do layout