Sport Tech Club - Integração com Untopika Workspace

Documentação dos recursos do ecossistema Untopika que serão reutilizados no Sport Tech Club.

Visão Geral

O Sport Tech Club será desenvolvido como parte do ecossistema Untopika, aproveitando toda a infraestrutura, bibliotecas e serviços compartilhados já existentes. Esta abordagem acelera o desenvolvimento, mantém consistência arquitetural e reduz custos operacionais.

Repositórios Untopika Disponíveis

Repositório	Descrição	Status
`untopika-workspace`	Infraestrutura Docker para desenvolvimento local	Produção
`untopika-iam`	Identity & Access Management com Keycloak	Em desenvolvimento
`untopika-wallet`	Plataforma de créditos virtuais multi-tenant	Em desenvolvimento
`untopika-webkit`	Design System Vue 3 + TypeScript	Em desenvolvimento
`untopika-core-mcp`	Core MCP integrations	Planejado

1. untopika-workspace (Infraestrutura)

O que é

Ambiente de desenvolvimento Docker Compose com todos os serviços de infraestrutura necessários.

Serviços Disponíveis

Serviço	Imagem	Porta	IP
PostgreSQL 16	`postgres:16-alpine`	5432	172.30.1.10
pgAdmin 4	`dpage/pgadmin4:9.10`	9000	172.30.100.10
Keycloak 26	`quay.io/keycloak/keycloak:26.0.7`	9090	172.30.100.20
Prometheus	`prom/prometheus:v3.0.1`	9091	172.30.100.30
Grafana	`grafana/grafana:11.4.0`	9092	172.30.100.40
Jaeger	`jaegertracing/all-in-one:1.64.0`	9093	172.30.100.50
RabbitMQ	`rabbitmq:3.13-management-alpine`	5672/15672	172.30.3.10
Redis 7	`redis:7-alpine`	6380	172.30.2.10
Airflow	`apache/airflow:2.10.4-python3.11`	8080	172.30.10.10
Evolution API	`atendai/evolution-api:v2.2.3`	9094	172.30.4.10
Evolution Manager	`atendai/evolution-manager`	9095	172.30.4.20

O que o STC vai reutilizar

PostgreSQL 16
- Banco de dados compartilhado com schemas isolados
- Extensões: uuid-ossp, pg_trgm, btree_gin, btree_gist
- Configuração: UTF-8, pt_BR, timezone São Paulo
Keycloak 26
- Autenticação OAuth 2.0 / OIDC
- Multi-tenancy via atributos de usuário
- Realms e clients pré-configurados
- Themes customizáveis
Redis 7
- Cache de sessão
- Rate limiting
- Cache de dados frequentes
RabbitMQ
- Eventos assíncronos (bookings, payments)
- Notificações em tempo real
- Integração com webhooks
Observabilidade (Prometheus + Grafana + Jaeger)
- Métricas de aplicação
- Dashboards pré-configurados
- Tracing distribuído

Como Usar

bash

# Clone o workspace (se ainda não tiver)
git clone git@github.com:Untopika/untopika-workspace.git
cd untopika-workspace

# Configure variáveis
cp .env.example .env

# Inicie a infraestrutura
./deploy.sh local

# Valide os serviços
./validate.sh

2. untopika-iam (Identity & Access Management)

O que é

Serviços e SDKs para gerenciamento de identidade multi-tenant.

Estrutura

untopika-iam/
├── services/
│   └── identity-admin-service/   # API REST (porta 8081)
├── libs/
│   ├── node/                     # SDK TypeScript
│   └── python/                   # SDK Python
└── docs/                         # Documentação

O que o STC vai reutilizar

Identity Admin Service
- CRUD de usuários via API
- Gestão de roles e permissions
- Audit logging

SDK Node.js (@untopika/id-client)

typescript

import { UntopikaIdClient } from '@untopika/id-client';

const client = new UntopikaIdClient({
  baseUrl: process.env.IAM_SERVICE_URL,
  clientId: 'sport-tech-club',
  clientSecret: process.env.IAM_CLIENT_SECRET,
});

// Criar usuário
const user = await client.users.create({
  email: 'jogador@example.com',
  firstName: 'Rafael',
  lastName: 'Silva',
  attributes: {
    tenant_id: 'arena-copacabana',
  },
});

Modelo de Autorização
- Roles: SUPER_ADMIN, ARENA_OWNER, ARENA_MANAGER, PLAYER
- Scopes por API
- Token claims customizados
Multi-tenancy
- Isolamento por tenant_id no token
- RLS integrado com PostgreSQL

Documentação Relevante

/docs/architecture.md - Arquitetura do IAM
/docs/authorization-model.md - Modelo de autorização
/docs/tenants.md - Multi-tenancy
/docs/sdk-usage.md - Uso dos SDKs

3. untopika-wallet (Créditos Virtuais)

O que é

Plataforma de créditos virtuais (pontos, tokens) multi-tenant.

Estrutura (Clean Architecture)

untopika-wallet/
├── src/
│   ├── domain/           # Regras de negócio
│   ├── application/      # Casos de uso
│   ├── infrastructure/   # Frameworks
│   └── presentation/     # Controllers
├── prisma/               # Schema do banco
└── docs/                 # Documentação

O que o STC vai reutilizar

Sistema de Wallet
- Créditos para reservas (pré-pago)
- Pontos de fidelidade (gamificação)
- Cashback de reservas

API de Transações

typescript

// Creditar wallet do jogador
POST /v1/transactions/credit
{
  "walletId": "w_abc123",
  "amount": 10000,  // R$ 100.00 em centavos
  "referenceType": "BOOKING_PAYMENT",
  "referenceId": "booking_xyz"
}

// Debitar para reserva
POST /v1/transactions/debit
{
  "walletId": "w_abc123",
  "amount": 5000,
  "referenceType": "BOOKING",
  "referenceId": "booking_123"
}

Ledger Imutável
- Histórico completo de transações
- Auditoria e compliance (LGPD)
- Idempotência obrigatória
Webhooks
- Eventos de transação
- Notificações em tempo real

Funcionalidades Aplicadas ao STC

Funcionalidade Wallet	Uso no Sport Tech Club
Crédito	Recarga de saldo para reservas
Débito	Pagamento de reserva
Transferência	Dividir pagamento entre jogadores
Cashback	Recompensa por frequência
Pontos	Sistema de XP e níveis

Documentação Relevante

/docs/architecture/ARCHITECTURE.md - ADRs
/docs/api/openapi.yaml - Especificação da API
/docs/requirements/USE-CASES.md - Casos de uso

4. untopika-webkit (Design System)

O que é

Biblioteca de componentes Vue 3 + TypeScript com sistema de temas.

Estrutura

untopika-webkit/
├── packages/
│   ├── untopika-core/    # Biblioteca de componentes
│   └── docs/             # Documentação interativa

O que o STC vai reutilizar

Componentes Base
- Buttons, Cards, Inputs, Selects
- DockContainer (layout master page)
- Modals, Toasts, Alerts
Sistema de Temas
- 6 temas pré-definidos (Dark, Light, Midnight, Ocean, Sunset, Forest)
- CSS Variables para customização
- Suporte a tema claro/escuro

Uso no STC

typescript

// Instalação
import { createUntopikaCore } from '@untopika/core';
import '@untopika/core/style.css';

const app = createApp(App);
app.use(createUntopikaCore({
  theme: 'ocean', // Tema azul mar para esportes de praia
}));

Customização para STC

css

:root {
  /* Brand Sport Tech Club */
  --utk-primary: #00A86B;      /* Verde Arena */
  --utk-secondary: #1E88E5;    /* Azul Mar */
  --utk-accent: #FF6B35;       /* Laranja Sol */
}

Tecnologias

Vue 3.5 (Composition API + <script setup>)
TypeScript 5.7
Vite 6
Bootstrap 5.3 (utilities)

Matriz de Reutilização

Recurso	Origem	Uso no STC	Customização
PostgreSQL	workspace	Sim	Schemas próprios
Keycloak	workspace + iam	Sim	Realm STC, themes
Redis	workspace	Sim	Prefixo `stc:`
RabbitMQ	workspace	Sim	Exchanges próprios
Prometheus/Grafana	workspace	Sim	Dashboards STC
Jaeger	workspace	Sim	Service name
Identity Service	iam	Sim	Roles STC
SDK @untopika/id-client	iam	Sim	Nenhuma
Wallet API	wallet	Sim	Namespace STC
@untopika/core	webkit	Sim	Tema customizado

Configuração do Sport Tech Club

Variáveis de Ambiente (referenciando Untopika)

env

# ===========================================
# UNTOPIKA WORKSPACE SERVICES
# ===========================================

# PostgreSQL (untopika-workspace)
DATABASE_URL=postgresql://untopika:untopikalocal_password@localhost:5432/stc_dev

# Keycloak (untopika-workspace)
KEYCLOAK_URL=http://localhost:9090
KEYCLOAK_REALM=sport-tech-club
KEYCLOAK_CLIENT_ID=stc-api
KEYCLOAK_CLIENT_SECRET=<secret>

# Redis (untopika-workspace)
REDIS_URL=redis://:untopika_redis_local@localhost:6380

# RabbitMQ (untopika-workspace)
RABBITMQ_URL=amqp://untopika:untopika_rabbitmq_local@localhost:5672/untopika

# Jaeger (untopika-workspace)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# ===========================================
# UNTOPIKA SERVICES
# ===========================================

# Identity Admin Service (untopika-iam)
IAM_SERVICE_URL=http://localhost:8081
IAM_CLIENT_ID=sport-tech-club
IAM_CLIENT_SECRET=<secret>

# Wallet Service (untopika-wallet)
WALLET_SERVICE_URL=http://localhost:3000
WALLET_NAMESPACE_ID=ns_sport_tech_club

Docker Compose (Extensão do Workspace)

yaml

# sport-tech-club/docker-compose.yml
# Estende o untopika-workspace

networks:
  untopika-network:
    external: true

services:
  stc-api:
    build: ./apps/api
    container_name: stc-api-local
    environment:
      DATABASE_URL: postgresql://untopika:untopikalocal_password@untopika-postgres-local:5432/stc_dev
      KEYCLOAK_URL: http://untopika-keycloak-local:8080
      REDIS_URL: redis://:untopika_redis_local@untopika-redis-local:6379
    networks:
      - untopika-network
    ports:
      - "3001:3000"
    depends_on:
      - untopika-postgres-local  # via network externa

Fluxo de Desenvolvimento

Benefícios da Integração

1. Time-to-Market Reduzido

Infraestrutura pronta (weeks → hours)
Autenticação pronta (months → days)
Wallet pronta (months → days)
UI components prontos (weeks → days)

2. Consistência

Mesmos padrões de código
Mesma arquitetura (Clean Architecture)
Mesmas práticas (TDD, GitFlow)
Mesma observabilidade

3. Custo Operacional

Infraestrutura compartilhada
Menos código para manter
Menos bugs (código testado)
Menos deploy (serviços centralizados)

4. Escalabilidade

Serviços já otimizados
Padrões multi-tenant prontos
RLS implementado
Cache configurado

Próximos Passos

[ ] Configurar realm sport-tech-club no Keycloak
[ ] Criar namespace no Wallet Service
[ ] Criar tema STC no webkit
[ ] Configurar schemas no PostgreSQL
[ ] Criar exchanges no RabbitMQ
[ ] Configurar dashboards no Grafana

Última atualização: 2025-01-09

Sport Tech Club - Integração com Untopika Workspace ​

Visão Geral ​

Repositórios Untopika Disponíveis ​

1. untopika-workspace (Infraestrutura) ​

O que é ​

Serviços Disponíveis ​

O que o STC vai reutilizar ​

Como Usar ​

2. untopika-iam (Identity & Access Management) ​

O que é ​

Estrutura ​

O que o STC vai reutilizar ​

Documentação Relevante ​

3. untopika-wallet (Créditos Virtuais) ​

O que é ​

Estrutura (Clean Architecture) ​

O que o STC vai reutilizar ​

Funcionalidades Aplicadas ao STC ​

Documentação Relevante ​

4. untopika-webkit (Design System) ​

O que é ​

Estrutura ​

O que o STC vai reutilizar ​

Tecnologias ​

Matriz de Reutilização ​

Configuração do Sport Tech Club ​

Variáveis de Ambiente (referenciando Untopika) ​

Docker Compose (Extensão do Workspace) ​

Fluxo de Desenvolvimento ​

Benefícios da Integração ​

1. Time-to-Market Reduzido ​

2. Consistência ​

3. Custo Operacional ​

4. Escalabilidade ​

Próximos Passos ​

Sport Tech Club - Integração com Untopika Workspace

Visão Geral

Repositórios Untopika Disponíveis

1. untopika-workspace (Infraestrutura)

O que é

Serviços Disponíveis

O que o STC vai reutilizar

Como Usar

2. untopika-iam (Identity & Access Management)

O que é

Estrutura

O que o STC vai reutilizar

Documentação Relevante

3. untopika-wallet (Créditos Virtuais)

O que é

Estrutura (Clean Architecture)

O que o STC vai reutilizar

Funcionalidades Aplicadas ao STC

Documentação Relevante

4. untopika-webkit (Design System)

O que é

Estrutura

O que o STC vai reutilizar

Tecnologias

Matriz de Reutilização

Configuração do Sport Tech Club

Variáveis de Ambiente (referenciando Untopika)

Docker Compose (Extensão do Workspace)

Fluxo de Desenvolvimento

Benefícios da Integração

1. Time-to-Market Reduzido

2. Consistência

3. Custo Operacional

4. Escalabilidade

Próximos Passos