Skip to content

thiago-damasio/Omniware-AI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
.context
.context
 
 
PRDs
PRDs
 
 
apps/api/src
apps/api/src
 
 
infrastructure/docker
infrastructure/docker
 
 
omniware-ai-core
omniware-ai-core
 
 
.gitignore
.gitignore
 
 
AGENTS.md
AGENTS.md
 
 
README.md
README.md
 
 

Repository files navigation

🚀 Omniware AI

Plataforma multicanal de inteligência conversacional generativa com governança, observabilidade e controle total.

TypeScript NestJS PostgreSQL License

📋 Índice

🎯 Sobre o Projeto

Omniware AI resolve o problema de empresas que possuem:

  • Canais de comunicação isolados (WhatsApp, voz, webchat, Instagram)
  • Bots tradicionais incapazes de raciocínio complexo
  • Experiência inconsistente entre canais
  • Dependência de TI para mudanças simples
  • Ausência de governança em conversações com IA

Solução

Uma plataforma completa que oferece:

Capacidade Descrição
IA Generativa Multi-LLM OpenAI, Anthropic, Google Gemini com fallback automático
Multicanalidade WhatsApp, WebChat, Instagram, SMS, Voz, E-mail
Cross-Channel Troca inteligente de canal durante conversação
Skills Engine Integração com APIs REST e agentes MCP
Knowledge Engine RAG com vector store (pgvector)
Cockpit Humano (HITL) Monitoramento real-time e takeover
Observabilidade Logs estruturados, métricas, traces com Grafana
Multi-Tenant Isolamento, RBAC, billing por tenant

🛠 Stack Tecnológica

Backend

  • Runtime: Node.js 20 LTS
  • Framework: NestJS 10.x
  • Linguagem: TypeScript 5.x
  • ORM: Prisma 5.x
  • Validation: Zod + class-validator

Database & Cache

  • Database: PostgreSQL 16 + pgvector (para embeddings)
  • Cache: Redis 7.x
  • Queue: BullMQ

LLM Providers

  • Tier 1: OpenAI GPT-4o, Anthropic Claude 3.5, Google Gemini 2.0
  • Tier 2: Azure OpenAI, Google Vertex AI, AWS Bedrock
  • Tier 3: Ollama (self-hosted)

Monorepo & Build

  • Monorepo: pnpm + Turborepo
  • Package Manager: pnpm 8.x

Observabilidade

  • Logs: Pino (JSON estruturado) → Loki → Grafana
  • Métricas: Prometheus → Grafana
  • Traces: OpenTelemetry → Jaeger/Tempo

Cloud (Produção)

  • Provider: AWS
  • Orquestração: Kubernetes (EKS)
  • IaC: Terraform

📦 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

  • Node.js >= 20.0.0 (Download)
  • pnpm >= 8.0.0 (npm install -g pnpm)
  • Docker >= 24.0.0 (Download)
  • Git >= 2.40.0

Contas Externas Necessárias

  1. Meta Business (WhatsApp Cloud API)

  2. OpenAI (ou outro provider LLM)

  3. Ngrok ou CloudFlare Tunnel (para webhooks locais)

🚀 Setup Inicial

1. Clone o Repositório

git clone <repository-url>
cd omniware-ai

2. Instale as Dependências

cd omniware-ai-core/apps/api
pnpm install

3. Configure Variáveis de Ambiente

# Copie o arquivo de exemplo
cp .env.example .env

# Edite e preencha suas credenciais
nano .env  # ou use seu editor preferido

Variáveis obrigatórias:

  • DATABASE_URL - String de conexão PostgreSQL
  • REDIS_URL - String de conexão Redis
  • OPENAI_API_KEY - Chave da API OpenAI
  • WHATSAPP_TOKEN - Token do WhatsApp Cloud API
  • WHATSAPP_VERIFY_TOKEN - Token customizado para verificação
  • WHATSAPP_PHONE_NUMBER_ID - ID do número WhatsApp

4. Suba a Infraestrutura Local (Docker)

# Do diretório raiz do projeto
docker compose -f infrastructure/docker/docker-compose.dev.yml up -d

# Verifique se os serviços estão rodando
docker compose -f infrastructure/docker/docker-compose.dev.yml ps

Serviços disponíveis:

5. Execute as Migrations

cd omniware-ai-core/apps/api

# Gerar Prisma Client
pnpm prisma generate

# Criar banco e executar migrations
pnpm prisma migrate dev

# (Opcional) Abrir Prisma Studio
pnpm prisma studio  # Abre em http://localhost:5555

6. Inicie a Aplicação

# Modo desenvolvimento (hot reload)
pnpm start:dev

# Ou build + produção local
pnpm build
pnpm start:prod

A API estará disponível em: http://localhost:3000

💻 Desenvolvimento

Comandos Úteis

# Desenvolvimento
pnpm dev                    # Inicia em watch mode
pnpm build                  # Build de produção
pnpm start:debug            # Debug mode

# Database
pnpm prisma studio          # Interface visual do banco
pnpm prisma migrate dev     # Criar nova migration
pnpm prisma db seed         # Popular banco com dados de teste

# Testes
pnpm test                   # Testes unitários
pnpm test:e2e               # Testes end-to-end
pnpm test:cov               # Cobertura de código

# Qualidade de Código
pnpm lint                   # ESLint
pnpm format                 # Prettier
pnpm typecheck              # Verificação de tipos

Workflow de Desenvolvimento

  1. Crie uma branch a partir de develop:

    git checkout develop
git pull origin develop
git checkout -b feature/sua-feature

  2. Desenvolva seguindo conventional commits:

    git commit -m "feat(channels): add Instagram DM connector"
git commit -m "fix(llm): handle timeout in OpenAI provider"

  3. Push e abra PR:

    git push origin feature/sua-feature
# Abrir Pull Request no GitHub

Estrutura de Commits (Conventional Commits)

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore, perf

🏗 Arquitetura

Diagrama de Alto Nível

┌─────────────────────────────────────────┐
│         CHANNELS LAYER                  │
│  WhatsApp │ Voice │ WebChat │ Instagram │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│       CHANNEL NORMALIZER                │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         ORCHESTRATOR                    │
│  • Deterministic Orchestrator           │
│  • Generative Orchestrator (LLM)        │
└─────┬──────────────────┬─────────┬──────┘
      │                  │         │
┌─────▼──────┐  ┌────────▼───┐  ┌─▼─────────┐
│  PROMPT    │  │  LLM HUB   │  │  SKILLS   │
│  ENGINE    │  │  Multi-LLM │  │  ENGINE   │
└────────────┘  └────────────┘  └───────────┘

Módulos Principais

Módulo Responsabilidade
channels/ Conectores de canais (WhatsApp, WebChat, etc.)
conversation/ Session Manager, Orchestrators
llm/ LLM Hub, Prompt Engine, providers
guardrails/ PII detection, policies, safety
skills/ Skills Engine, tool execution
knowledge/ Vector Store, RAG, document processing
observability/ Logs, métricas, traces

Veja mais: .context/docs/architecture.md

📚 Documentação

Toda a documentação está centralizada em .context/docs/:

Documentos Principais

Documento Descrição
Quick Start ⚡ Guia de arranque (Dia 1-30)
Readiness Checklist ✅ Checklist de prontidão
Phase 1 Plan 📋 Plano detalhado Fase 1 (MVP 0.1)
Architecture 🏗 Arquitetura completa
Tech Decisions ADR 📝 Decisões técnicas (ADRs)
PRD Master 📄 Product Requirements
Backlog 📊 Backlog por EPIC
Development Workflow 🔄 Git workflow, CI/CD

Para Iniciantes

  1. 📖 Leia: Project Overview
  2. ✅ Complete: Readiness Checklist
  3. 🚀 Siga: Phase 1 Foundation Plan

Para AI Agents

Consulte: AGENTS.md para guia contextual completo.

🗺 Roadmap

Fase 1: Fundação (MVP 0.1) - 2 semanas ✅

  • Conector WhatsApp funcional
  • Session Manager básico (Redis)
  • Prompt Engine configurável
  • Orchestrator simples
  • Integração LLM (OpenAI)
  • Logging estruturado
  • Primeira skill REST
  • Guardrails básicos (PII)
  • Testes E2E

Fase 2: Multicanal (v0.2) - 2 semanas

  • WebChat connector
  • Instagram DM connector
  • Voice (ASR/TTS)
  • Channel normalization completa

Fase 3: Intelligence (v0.3) - 3 semanas

  • Knowledge Engine (RAG)
  • Skills Engine (REST + MCP)
  • Flow Builder básico

Fase 4: Observability & Control (v0.4) - 2 semanas

  • Cockpit Humano (HITL)
  • Dashboards completos
  • Alerting

Fase 5: Enterprise (v1.0) - 4 semanas

  • Multi-tenant completo
  • RBAC avançado
  • Billing
  • SSO (SAML/OIDC)

Veja detalhes: .context/docs/roadmap.md

🤝 Contribuindo

Contribuições são muito bem-vindas! Por favor:

  1. Leia o Development Workflow
  2. Siga os padrões de código (ESLint + Prettier)
  3. Use Conventional Commits
  4. Adicione testes para novas features
  5. Atualize a documentação quando necessário

Code Review

Todos os PRs passam por:

  • ✅ Lint (ESLint)
  • ✅ Type check (TypeScript)
  • ✅ Tests (Jest)
  • ✅ Build validation
  • ✅ Code review (2 aprovações mínimas)

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

📞 Suporte

Construído com ❤️ usando TypeScript e NestJS

About

Omniware AI - Multi-channel AI Orchestrator

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages