KOLOS — Especificação Técnica e Operacional
Documentação KOLOS
← Índice docs Início

KOLOS — Especificação Técnica e Operacional

🧭 Contexto

Documento base/blueprint do KOLOS, consolidando missão, módulos, stack, arquitetura e requisitos operacionais.

Missão

Ser o sistema operacional definitivo para o universo do Beach Tennis, conectando arenas, organizadores e a paixão "Foot in the Sand".

Status do Projeto

Este documento segue como especificação base. Neste repositório já existe uma implementação inicial do módulo Documentações (CRUD + editor + busca), e os demais módulos permanecem como roadmap.

Metadados do Projeto

Chave Valor
Produto KOLOS (Beach Tennis Operating System)
Status 🟡 FASE DE IMPLEMENTAÇÃO - Documentações (MVP)
Versão Planejada 1.0.0-alpha
Data de Especificação Janeiro 2026
Licença Proprietária
Features Planejadas Auth, Dashboard, Batalhas, Arenas, Players, Fair Play, Rate Limiting, Métricas, Logs

Módulo 1: Identidade & Visão

1.1 A Marca

  • Nome: KOLOS
  • Slogan: "Rule the Sand."
  • Etimologia:
    • KO (Knock Out): o smash decisivo, a vitória incontestável.
    • LOS (Leaders Of Sand): referência na praia, o gigante da arena.
  • Mitologia: o "Colosso", estrutura imponente que domina o horizonte da praia.

1.2 Vocabulário (Ubiquitous Language)

Termo Comum Termo KOLOS Descrição
Partida ⚔️ Batalha Evento de jogo competitivo
Usuário 🛡️ Atleta / Play Jogador registrado no sistema
Quadra 🏖️ Arena (Box) Unidade física de jogo (areia)
Stats/Skills 📊 Play Card Perfil gamificado do atleta
Matchmaking 🤝 Alliance Sistema de formação de duplas
Grupo 🛡️ Squad Grupo de amigos ou clã de jogadores

1.3 Diretrizes Visuais do Avatar (The Kolos System)

Tokens Obrigatórios (Fixo)

  • Material: Areia compactada (Sandstone) ou pedra bege com textura granulada visível.
  • Estilo: Estátua Greco-Romana + Gladiador Moderno.
  • Físico: Hipertrofiado, divino (God-like physique) com olhos de pedra (sem pupilas).
  • Iluminação: Rim light dramática ou sol de meio-dia com sombras duras.
  • Acessórios: Braceletes de guerra nos dois braços e caneleira de guerra.

Biblioteca de Poses (Contexto)

  • Menu Principal - O Guardião: Atrás do pódio, vigiando a arena, mãos na raquete/espada.
  • Loading - O Smash: No ar, corpo arqueado, areia voando.
  • Vitória - O Conquistador: Braços abertos ao céu, êxtase.
  • Derrota - A Resiliência: De joelhos, punho na areia, tentando levantar.
  • Fair Play - O Juiz: Braços cruzados, autoridade.

1.4 Princípios de Design (UX/UI)

📱 Mobile-First nativo: interfaces projetadas primeiro para uso em movimento, sob luz solar forte e operáveis com "dedos de areia". Desktop é secundário (Mesa de Controle).

Módulo 2: Arquitetura & Tecnologia

2.1 Stack Tecnológica (Janeiro 2026)

Componente Versão Justificativa
Runtime PHP 8.5.1 Stack do projeto
Ambiente Laravel Sail Docker Compose padrão do Laravel
Framework Laravel 12.44.0 Stack do projeto
UI (App Principal) Livewire 4.0 + Alpine.js integrado
UI (Super Admin) Filament v4.5 Back-office SaaS
Base de Dados PostgreSQL 18 Versão mais recente
Cache Redis 7.4 Produção-ready
Real-time Laravel Reverb 1.6.3 WebSocket nativo Laravel
QA - Análise Estática Larastan 3.8.1 Stack do projeto
QA - Testes Pest 4.3.0 Stack do projeto
QA - Code Style Laravel Pint 1.26.0 Stack do projeto
QA - Refatoração Rector 2.3.0 Stack do projeto

Editor recomendado: VS Code com extensões PHP e Laravel.

2.2 Arquitetura (Modular Monolith - DDD)

Mapa Visual de Dependências & Camadas:

[SHARED KERNEL] │ ▼ [IDENTITY] ────────────────────────┐ │ │ ▼ ▼ [VENUE] [PLAYER] ───────────────> [FINANCE] │ │ ▲ └─┬─────┘ │ │ │ ▼ │ [BOOKING] ──────────────────────────┤ │ │ ▼ │ [COMPETITION] ──┬──> [RANKING] │ │ │ └──> [COMMERCE] ──────┘

Detalhamento dos Módulos (por ordem de construção)

Fundação (Kernel):

  • Shared: Serviços globais, Value Objects (CPF, Money) e DTOs base.

Acesso & Atores (Generic/Core):

  • Identity: [Generic] Auth, ACL, KYC básico.
  • Player: [Core] Play Card, Biometria, XP, Histórico.
  • Venue: [Core] Quadras, Iluminação, Ativos.

Motores de Negócio (Core Engines):

  • Booking: [Core] Agendamento, Conflitos, Recorrência. Depende de Venue e Player.
  • Competition: [Core] Torneios, Chaves, Súmulas. Depende de Booking.

Satélites & Extensões (Supporting/Generic):

  • Academy: [Supporting] Coaches, Turmas. Extensão do Booking.
  • Ranking: [Supporting] Temporadas, Ladders. Processa dados de Competition.
  • Commerce: [Generic] POS, Aluguel. Venda avulsa.
  • Finance: [Generic] Wallets, Split, Gateway. Recebe ordens de todos.

Organização de Diretórios

app/ ├── Actions/ # Lógica de negócio (Commands) ├── DTOs/ # Data Transfer Objects ├── Domain/ # Entidades e Value Objects ├── Filament/ # Painéis Administrativos (Super Admin) ├── Livewire/ # Componentes UI (App Principal) ├── Repositories/ # Acesso a dados └── Support/ ├── Enums/ # Enumerações └── ActionResponse.php

Princípios Arquiteturais

  • Separação clara de responsabilidades (DDD).
  • Bounded Contexts bem definidos.
  • Event-Driven onde aplicável.
  • CQRS para leitura/escrita quando necessário.

2.3 Segurança & Atores (ACL) - Visão Geral

Ator Chave Interface Descrição
👑 Super Admin super_admin Filament Panel Dono do SaaS - Acesso irrestrito
🏟️ Arena Owner venue_owner App Custom (Flux) Gerencia negócio, quadras e staff
🏆 Organizer organizer App Custom (Flux) Produtor de torneios
🎓 Coach coach App Custom (Flux) Professor, pode certificar nível técnico
🛡️ Staff staff App Custom (Flux) Portaria e validação
🏃 Athlete player App Custom (Flux) Usuário final

(Detalhamento completo da ACL no Módulo 9)

2.4 Estratégia de Integração (Hardware & API)

IoT & Automação (MQTT/HTTP)

  • Protocolo: Webhooks seguros (HMAC Signed) disparados pelo Scheduler do Laravel.
  • Luzes: POST /api/device/light/on { court_id: 1 } (Trigger: 5 min antes da reserva).
  • Catracas: Integração via API de fabricantes (Intelbras/Hikvision) para whitelist temporária.

API Externa (Aggregators)

  • Padrão: RESTful API com rate limiting estrito.
  • Gympass/Wellhub: POST /api/integrations/wellhub/checkin.

2.5 KOLOS Design System

2.5.1 Identidade Visual: Dark Stone Gladiator

  • Fundo: bg-stone-950
  • Superfícies: bg-stone-900, border-stone-800
  • Destaque: text-amber-500, bg-amber-600
  • Texto principal: text-stone-200
  • Texto secundário: text-stone-500

Tipografia

  • Font Family: Sans-serif (font-sans)
  • Títulos: uppercase, font-black/font-bold, tracking-widest
  • Subtítulos: font-semibold, text-lg/text-xl
  • Corpo: font-normal, text-base
  • Metadados: font-light, text-sm, text-stone-500

Componentes

  • Cards: rounded-xl, border border-stone-800, shadow-lg/2xl, p-6/p-4
  • Glassmorphism: bg-stone-900/95, backdrop-blur-md, border-b border-stone-800/50
  • Ícones: Lucide (size 20/24), metáforas Crown/Swords/Shield/Trophy
  • Botões:
    • Primário: bg-amber-600, text-stone-950, hover:bg-amber-500
    • Secundário: border-stone-700, bg-stone-800, text-stone-200, hover:bg-stone-700

2.5.3 Layout Responsivo

  • Mobile-first: Bottom Bar fixa
  • Desktop: Sidebar em lg

2.5.4 Detalhes Avançados

  • Degradês sutis: bg-gradient-to-br from-amber-500 to-amber-700
  • Animações: pulse para "Ao Vivo" e hover:scale-105

Módulo 3: Gestão de Arena (Venue Ops)

3.1 Maintenance

  • Hard Lock: bloqueio mais forte, nada sobrescreve.
  • Escopo: quadra específica ou arena inteira.
  • Tipos: PREVENTIVE, EMERGENCY, WEATHER.
  • Governança: Arena Owner/Staff (auto-aprovado).
  • Automação Chuva: cancela reservas, reembolsa, envia push.

3.2 Tournament

  • Venue Takeover: bloqueia múltiplas quadras.
  • Mass Cancellation: pode cancelar aulas/locações.
  • Governança: Organizer/Arena Owner; aprovação do Owner.
  • Handshake: SOFT_LOCK → análise impacto → HARD_LOCK.
  • Mitigação: realocação automática.

3.3 Class

  • Recorrência e vagas limitadas.
  • Token de reposição.
  • Governança: Coach solicita, Owner aprova.
  • Presença: tokens para faltas justificadas.

3.4 Ladder Match

  • Vínculo obrigatório com match_id de desafio.
  • Regras de tempo/preço.
  • Pós-jogo: confirmação de placar e auto-aceite.

3.5 Booking

  • Exclusividade do slot.
  • Buffer time configurável.
  • Split Payment com timeout.

3.6 Day Use

  • Smart Cap: tickets por capacidade.
  • Fila virtual FIFO.
  • Termômetro de lotação.

3.7 Open Match

  • Venda de vaga por posição.
  • Restrição de nível.
  • Cancelamento automático se não completar.

Módulo 4: Motor de Competição

4.1 Formatos de Chaveamento

  • Single Elimination
  • Round Robin + Eliminatória
  • Crossover Olímpico
  • Swiss System
  • Consolação automática

4.2 Smart Scheduler

  • Otimiza distribuição com base em quadras, duração e restrições.
  • Previsão e mitigação de atrasos.

4.3 Live Desk

  • Drag & drop para quadras.
  • Integração com WhatsApp.
  • Gestão de W.O. com timer.

4.4 Regras de Pontuação

  • 1 Set (padrão torneios)
  • Melhor de 3
  • Short Set
  • Configuração granular por fase.

Módulo 5: Experiência do Jogador

5.1 Play Card

  • Radar Chart (0-99)
  • Decay system

Matriz de Avaliação

  • Fundamentos Técnicos: saque, devolução, smash, defesa, curta, movimentação.
  • Aspectos Mentais: disciplina, tática, esportividade.

5.2 Social & Matchmaking

  • Alliance (duplas)
  • Histórico unificado
  • Painel financeiro

5.3 Squads & LFG

  • Squads com split automático
  • Vamos Jogar (Day Use/LFG)

Módulo 6: Ecossistema Competitivo

  • KOLOS Titles
  • Ladder
  • Americano
  • Rei/Rainha da Praia
  • Guerra de Clãs

Módulo 7: Inovação & Viralização

  • Filma Eu (ONVIF/ISAPI)
  • Insta-Ready cards
  • Arena TV Mode
  • Pick a Side
  • Hype Meter

Módulo 8: Roadmap de Desenvolvimento

  • Fase 0: Setup & Fundação
  • Fase 1: Core Features (MVP)
  • Fase 2: Competição & Social
  • Fase 3: Comercialização
  • Fase 4: Inovação
  • Fase 5: Mobile Apps
  • Fase 6: Escala

Módulo 9: Matriz de Controle de Acesso (ACL)

📌 Detalhamento completo: KOLOS — Matriz de Atores e Acesso (ACL)

9.1 Definição dos Atores

Role Chave Interface Descrição
👑 Super Admin super_admin Filament Panel Dono do SaaS (Back-office)
🏟️ Arena Owner venue_owner App Custom Gerencia arena e staff
🏆 Organizer organizer App Custom Produtor de torneios
🎓 Coach coach App Custom Professor (credenciado)
🛡️ Staff staff App Custom Operacional/Portaria
🏃 Athlete player App Custom Usuário final

9.2 Regras de Escopo (Tenancy Rules)

  • venue_owner: vê dados onde venue_id corresponde.
  • organizer: edita torneios onde creator_id.
  • staff: vinculado ao venue_id.
  • coach: avalia com is_credentialed.
  • player: clipe se match_participants.

Total de permissões planejadas (Fase 1): 24.

Módulo 10: Requisitos Não-Funcionais e Compliance

10.1 Confiabilidade

  • SLA: 99.9% (43 min downtime/mês)
  • PITR no PostgreSQL (últimos 7 dias)
  • Snapshots diários em região distinta
  • Failover < 60s

10.2 Proteção de Dados (LGPD/GDPR)

  • Direito ao esquecimento: anonimização com integridade financeira
  • Dados sensíveis criptografados em repouso

10.3 Performance & Escalabilidade

  • 10.000 conexões simultâneas (WebSocket)
  • API < 100ms para operações críticas

Considerações Finais

Filosofia: "Isso aproxima ou afasta o atleta da areia?"

Princípios Fundamentais:

  • Mobile-First obrigatório
  • Performance crítica
  • Multitenancy seguro
  • Gamificação inteligente
  • Design System "Dark Stone Gladiator"

"Rule the Sand" — Do papel ao código, do código à areia 🏖️