Template — front-web-base
O front-web-base é o template React que todos os forks herdam. Roda SSR via React Router v7 no
Cloudflare Workers.
Estrutura de arquivos
app/
├── analytics/ # Registry tipado de eventos + dispatch + destinations
│ └── analayer/ # Subsistema AnaLayer (contexto + fan-out)
├── components/ # 35 pastas por domínio hoje (auth, games, payments, kyc,
│ # validation, user, sheets, smartico, sports, ui, …)
├── config/ # Configuração brand-editável — 22 subpastas semânticas
│ # + 4 arquivos soltos. Ver "Config map"
├── constants/ # breakpoints.ts, z-index.ts
├── context/ # EnvProvider, BrandProvider, CountryProvider,
│ # TranslationProvider, DeviceProvider, ComponentVariants
├── dev/ # Ferramentas só de dev (mock seeder, skeleton preview)
├── hooks/ # Hooks de feature (useAuthGate, useFavorites, useSportsConfig, …)
├── icons/custom/ # SVGs custom consumidos via unplugin-icons
├── layouts/ # Maquinário estrutural de layout (NÃO overrideable)
│ ├── DefaultLayout.tsx # Orchestrator: providers + initializers + slots
│ ├── layout.defaults.ts # Defaults + helper defineLayoutConfig()
│ ├── layout-registry.ts # Catálogo: string key → componente de variante
│ ├── shells/ # HeaderTopShell, SplitShell, MainContent, registry.ts
│ └── variants/ # header, header-secondary, sidebar, footer, mobile-bottom-nav
├── locales/ # brand-overrides.ts (file-replaced por brand) + overrides/
├── modules/register/ # Fluxo de registro extraído em módulo
├── router/ # Maquinário de rotas (NÃO overrideable)
│ └── routes.ts # Árvore completa de rotas (buildRoutes)
├── routes/ # Rotas de página + resource routes + api/ (nested)
├── services/ # *.server.ts (loaders/actions) e *.client.ts (browser)
├── store/ # 28 stores Zustand (estado de UI/sessão do base)
├── styles/ # brand-fonts.css
├── test/ # setup.ts do Vitest
├── types/ # Tipos compartilhados (NÃO overrideable)
├── utils/ # routes, cookie.client/server, proxy-error.server, …
├── widgets/ # 17 widgets opcionais + shared/. Ver "Widgets catalog"
├── entry.client.tsx
├── entry.server.tsx
├── root.tsx
├── routes.ts # Entry point do routing (importa buildRoutes)
└── tailwind.css
overrides/ # Overrides por brand (13 brands) — no ROOT do repo
├── <brand-key>/app/config/… # Substituição de arquivo INTEIRO
└── README.md
workers/
├── entry.ts # Gateway: extração de geo, de-auth, forward
├── app.ts # Entry de dev
├── app.deploy.ts # Entry de prod (WorkerEntrypoint `Ssr`)
├── middleware.ts # SSR cache, asset cache, Smartico proxy
├── cache-warmer.ts # Lógica do warm (handler `scheduled`)
├── charset.ts
└── preview.ts
pwa/ # config.ts + generate.sh (ícones/manifest)
vite-plugins/ # brand-overrides.ts, brand-resolver.mjs, dev-proxy-mirror.ts
scripts/ # dev.mjs, typecheck.mjs, check-prod-bundle.mjs, sync-assets-r2.mjs, …
:::caution app/config/ não é flat e não usa sufixo .config
A pasta foi reorganizada em 22 subpastas semânticas por domínio. Os imports são
~/config/<dir>/X — por exemplo ~/config/theme/colors, ~/config/routes/paths,
~/config/sports/sports, ~/config/widgets/sidebar-buttons. Qualquer caminho no formato
~/config/theme.config ou app/config/sports.config.ts está desatualizado.
Os overrides de brand vivem em overrides/<brand-key>/ na raiz do repositório, não em
app/config/overrides/.
:::
Mapa completo dos domínios de config em Config map; inventário dos widgets em Widgets catalog.
Layout
O layout é composto por shell + estrutura + slots + variantes, escolhidos por marca em
app/config/layout/composition.ts. A sidebar tem dois estados (expandido/colapsado) cujas larguras
vêm de layoutConfig.sidebar.widths, controlados via useLayoutStore() (sidebarOpen,
toggleSidebar). Detalhes em Layout.
Comandos
cd front-web-base
pnpm dev # node scripts/dev.mjs — a porta vem de DEV_PORT (.env.local), NÃO é sempre 5173
pnpm build # react-router build
pnpm quality # lint + check + check:dev-vars + typecheck + test (o mesmo que o CI roda)
pnpm typecheck # typegen + typecheck (source-first, resolve o core do source)
pnpm typecheck:ci # typegen + tsc -p tsconfig.ci.json (só node_modules — o que o package.json declara)
pnpm test # vitest run
pnpm lint # biome lint
pnpm format # biome format --write
pnpm bundle:guard # check-prod-bundle.mjs (roda junto em build:check)
pnpm preview # wrangler dev --config wrangler.preview.toml
pnpm check:dev-vars # sincroniza a policy de cache local com a do front-ops (--write aplica)
pnpm sync:assets:r2 # popula o bucket R2 de arquivo de assets
pnpm generate-pwa # gera ícones/manifest do PWA
Dependências do SDK
O template consome estes 15 pacotes @cactus-agents/* via GitHub Packages. As versões vivem em
front-web-base/package.json — consulte o arquivo em vez de pinar número em documentação.
| Pacote | Papel |
|---|---|
accounts | Auth + conta do usuário + wallet (unificou os antigos auth, user e wallet, que foram removidos) |
api-client | ApiClient/createCactusServerClient, headers Cactus, extractApiError |
brand | createBrandFromClient → BrandConfig |
country-config | Catálogo de países, locale, moeda, máscaras |
games | Tipos e serviços de catálogo de jogos |
gamification | Integração Smartico |
i18n | Locales base (7 diretórios) |
kyc | Serviço de KYC |
payments | Depósito/saque |
platform-cache | Engine de cache (memory → CF Cache API → KV snapshot) |
sports | Abstração de sportsbook e tipos de provider |
sports-rogue | SDK do provider rogue. Não é publicado pelo front-cactus-core |
types | Tipos compartilhados |
utils | Helpers |
validations | fetchAllValidations, buildValidationSnapshot e regras |
:::warning Pacotes que não existem mais
@cactus-agents/auth, @cactus-agents/user e @cactus-agents/wallet foram removidos do core e
unificados em @cactus-agents/accounts. Não há nenhum import deles em app/ nem em overrides/.
@cactus-agents/mocks está deprecado (stubs vazios) — as integrações reais de API o
substituíram.
:::
O pnpm dev/typecheck/test resolvem @cactus-agents/* direto do source do
../front-cactus-core via aliases; o pnpm build (produção) ignora os aliases e sempre resolve do
registry.