Objetivo
Uma base física de alto desempenho
Este documento define a implementação física do banco de dados da K10AI.
Padronizar a estrutura física
Garantir alta performance
Suportar milhões de registros
Facilitar a manutenção
Escalabilidade horizontal dos serviços
Otimizar consultas da IA
Tecnologia Oficial
Stack de dados
Banco principal e componentes complementares.
PostgreSQL 16+
Banco de dados principal
Redis
Cache e filas
pgvector
Banco vetorial no PostgreSQL
S3-compatible
Armazenamento de objetos
Convenções
Padrões de nomenclatura
Tabelas
Sempre no pluralusersprojectscoursesworkflowsai_agents
Colunas
Sempre em snake_casecreated_atupdated_atorganization_id
Chaves Primárias
Sempre UUIDid UUID PRIMARY KEY
Datas
Sempre com timezoneTIMESTAMP WITH TIME ZONE
Padrão de Todas as Tabelas
Toda tabela possui obrigatoriamente:
id UUID PRIMARY KEYorganization_id UUIDworkspace_id UUIDcreated_at TIMESTAMPTZupdated_at TIMESTAMPTZdeleted_at TIMESTAMPTZcreated_by UUIDupdated_by UUIDversion INTEGERstatus VARCHAR(30)
Schemas (Separação Lógica)
Facilita manutenção e permissões:
authcoreprojectsproductsaiworkflowsanalyticsbillingmarketplaceauditintegrationfilesnotificationsadmin
Tabelas Principais
Entidades por schema
Toda tabela herda o padrão base. Abaixo, as tabelas de cada domínio.
AUTH
usersrolespermissionssessionsoauth_accountsapi_keysmfa_devicespassword_resets
CORE
organizationsworkspacesbrandssettingslanguagescountriescurrencies
PROJECTS
projectsproject_membersproject_filesproject_tagsproject_history
PRODUCTS
coursescourse_moduleslessonsebookslanding_pagestemplatesfunnelscertificates
AI
ai_agentspromptsprompt_versionsconversationsmessagesmemoryembeddingsknowledge_nodesknowledge_edgesmodel_usage
WORKFLOWS
workflowsworkflow_stepsworkflow_runsworkflow_logsworkflow_templatesscheduled_jobs
MARKETPLACE
marketplace_itemspluginsplugin_versionsprompt_packsworkflow_packssalesreviews
BILLING
planssubscriptionspaymentsinvoicescreditstransactionsusage_logs
ANALYTICS
eventsmetricsdashboardsreportskpis
AUDIT
audit_logssecurity_logsadmin_logslogin_logs
Tipos de Dados
UUIDIDs
VARCHARCampos pequenos
TEXTConteúdo grande
BOOLEANEstados
JSONBConfigurações, prompts, metadata
NUMERICValores financeiros
TIMESTAMPTZDatas
BYTEAHashes
VECTOREmbeddings IA (pgvector)
Uso de JSONB
Utilizado apenas quando faz sentido — nunca substitui tabelas relacionais sem justificativa.
preferencessettingsmetadatavariablesworkflow_configintegration_configai_context
Índices
Performance de consultas
Obrigatórios
organization_idworkspace_idproject_idstatuscreated_at
Compostos
organization_id + created_atproject_id + statususer_id + organization_idworkflow_id + status
Especiais
GIN — Full Text SearchHNSW / IVFFlat — Embeddings (pgvector)
Estruturas Avançadas
Particionamento, views e automações
Particionamento (Mensal)
Tabelas grandes suportam particionamento:
eventsmessagesaudit_logsworkflow_logsusage_logs
Materialized Views
Dashboard ExecutivoAnalyticsKPIsReceitaConsumo IAPerformance
Views
active_projectsactive_usersactive_workflowsorganization_usagebilling_summary
Triggers Obrigatórias
Atualizar updated_atVersionamentoAuditoriaHistóricoSoft Delete
Stored Procedures
Fechamento financeiroGeração de KPIsLimpeza de cache lógicoArquivamentoExportaçãoConsolidação de analytics
Row Level Security (RLS)
Todas as tabelas multi-tenant utilizam políticas de RLS. Um usuário da Organização A nunca acessa dados da Organização B — mesmo em consultas diretas. Operações críticas usam transações ACID.
Otimização
Evitar SELECT *Paginação obrigatóriaConsultas parametrizadasBatch InsertsBatch UpdatesPrepared Statements
Cache (Redis)
SessõesPrompt CacheAI CacheFeature FlagsDashboard CacheAnalyticsRate Limits
Busca Vetorial
Tabela embeddings
Suporte nativo à IA com pgvector.
Campos
idproject_iddocument_idembedding VECTORmetadata JSONBcontent TEXT
Utilizada para
RAGMemória IABusca SemânticaKnowledge Graph
Operação
Confiabilidade e continuidade
Retenção
Políticas configuráveis para:
LogsConversasAnalyticsMensagensBackupsArquivos temporários
Monitoramento
Consultas lentasLocksDeadlocksÍndicesUso de CPUConexõesCache HitTamanho das tabelas
Backup
Backup diário completoBackups incrementaisSnapshotsReplicaçãoTestes periódicos de restauração
Replicação
Leitura distribuídaRead ReplicasFailoverAlta disponibilidade
Escalabilidade
Preparado para:
Milhões de usuáriosBilhões de registrosMilhões de promptsMilhões de workflowsMilhões de eventos
Migrações Versionadas
Nunca alterar a estrutura manualmente. Cada migração possui número, descrição, rollback e validação.
Convenções SQL
pk_usersfk_projects_workspaceidx_users_emailidx_events_createduq_organization_slug
Modelo de Evolução
Preparado para o futuro
Adição de módulos sem quebra de compatibilidade
Novas entidades sem alterar módulos existentes
Versionamento de schemas
Expansão por microsserviços quando necessário
Critérios de Aprovação
Quando o banco está pronto
A base física só é considerada concluída quando todos os critérios abaixo forem atendidos.
Todas as tabelas normalizadasRLS implementadoÍndices críticos criadosMigrações automatizadasProcedures documentadasTriggers implementadasReplicação suportadaBackup configuradoBusca vetorial funcional