Visão Geral da Arquitetura
Plataforma multi-tenant de apostas esportivas (Cactus Gaming). ~30 sites clientes, cada um com seu fork do template base.
Repositórios
| Repo | Descrição |
|---|---|
front-cactus-core | SDK TypeScript — pacotes @cactus-agents/* (monorepo) |
front-web-base | Template React Router v7 (SSR / Cloudflare Workers) |
front-cactus-docs | Esta documentação (Docusaurus) |
front-web-{marca} | Forks de marca (ex: front-web-vera-bet-br) |
front-web-panel | Painel admin (vault + deploys) |
front-ops | Vault de envs + scripts de build/deploy |
Stack
| Camada | Tecnologia |
|---|---|
| Framework | React Router v7 (SSR nativo no Cloudflare Workers) |
| Build/bundler | Vite (via React Router v7) |
| Styling | Tailwind CSS v3 + CSS custom properties para tokens de tema por cliente |
| State (client) | Zustand |
| State (server) | React Router loaders |
| Data fetching | TanStack Query (cache client) + loaders (SSR) |
| Linter/formatter | Biome (todos os repos) |
| Testes | Vitest + React Testing Library |
| Pre-commit | Husky + lint-staged → biome check --write |
| Commits | Conventional Commits (commitlint) |
| Package manager | pnpm (enforced) |
| Node | >=20.14.0 (recomendado: 22.18.0) |
Deploy
- SSR via Cloudflare Workers (React Router v7)
- Assets estáticos → Cloudflare R2
- Workers: render (SSR + static) + api-proxy
- Scripts de deploy →
front-ops
Pacotes privados
- GitHub Packages como registry privado
- Token de leitura por cliente (acesso apenas a
@cactus-agents/*, sem código-fonte)
Modelo de fork
O fork é uma cópia completa do front-web-base. O cliente tem liberdade total para personalizar: criar componentes, páginas, regras, redesenhar o tema inteiro.
Pontos rápidos de customização (já preparados no template):
app/config/theme.config.ts— paleta de coresapp/config/routes.config.ts— árvore de rotasapp/config/layout.config.ts— componente de layout
Mas o cliente não está limitado a esses arquivos. Pode modificar qualquer coisa no fork.
Única restrição: não alterar pacotes @cactus-agents/* diretamente — eles são dependências npm atualizáveis via pnpm update.
Decisões técnicas
| Decisão | Motivo |
|---|---|
| Cookie JS-readable (não httpOnly) | Token precisa ser lido no client para headers. |
| AuthService singleton client-side | Um único ApiClient pro browser, separado do SSR. |
| Zustand sem persist para auth | Token persiste via cookie, não localStorage. Store rehidratado no mount. |
| Token refresh 6h via pure functions | Lógica testável isolada. Store chama checkTokenRefresh(callback). |
| Modais controlados por Zustand | authModal: 'login' | 'register' | null. Qualquer componente abre/fecha. |
| EnvProvider separado do BrandProvider | clientEnv (API_BASE_URL etc.) precisa existir antes de qualquer chamada API client-side. |
| Fork = cópia completa + liberdade total | Config files são atalhos rápidos, não limites. Cliente pode personalizar o que quiser. |
| Biome em vez de ESLint | Mais rápido, config única pra lint + format, sem plugins. |