SWF

Como arquiteto de software, enfrentei o desafio de construir um sistema capaz de interpretar informações visuais complexas —especificamente, simbologias geométricas e frequências de onda no contexto das tecnologias Dakila— e cruzá-las com uma base de conhecimento altamente especializada. O problema fundamental estava na dificuldade de processar artefatos visuais não estruturados e correlacioná-los com precisão a extensos registros documentais, reduzindo o risco de alucinações por parte dos modelos de linguagem.

Para resolvê-lo, projetei uma aplicação web progressiva (PWA) que atua como ponte entre a visão computacional e a Geração Aumentada por Recuperação (RAG). O sistema não é um simples chatbot; é um motor de inferência que orquestra modelos multimodais para extrair características das imagens (padrões geométricos, linhas, curvas, cores) e usa esses atributos como vetores de busca em uma base de dados vetorial especializada.

Fluxo Operacional Principal

Do ponto de vista operacional, o sistema executa uma sequência determinística em três fases principais:

1. Ingestão Analítica: O usuário fornece uma imagem e, opcionalmente, um contexto textual. O sistema processa e armazena temporariamente o arquivo visual usando o Vercel Blob, preparando-o para a análise multimodal.
2. Extração e Busca Vetorial (RAG): O agente de IA (baseado no Mastra e em modelos fundacionais) executa uma análise visual inicial para extrair metadados da imagem. Imediatamente depois, o sistema vetoriza esses achados e consulta a base de conhecimento interna. Essa etapa garante que quaisquer afirmações posteriores estejam estritamente ancoradas na literatura oficial.
3. Síntese e Retorno de Estado: O motor consolida os achados visuais com os registros recuperados, gerando uma resposta estruturada. A conversa mantém o estado ao longo da sessão por meio de um sistema de memória dedicado, permitindo iterações de acompanhamento sobre o mesmo artefato visual.

---

Dissecação Arquitetural

Para construir este sistema, optei por uma arquitetura modular desacoplada, priorizando o desempenho e uma clara separação de responsabilidades entre a camada de apresentação e a orquestração cognitiva.

Arquitetura Geral

O projeto segue um padrão de Arquitetura Orientada a Serviços Desacoplada dentro de um ecossistema baseado em Astro. A razão técnica subjacente a essa decisão é isolar a complexidade computacional do agente de IA da renderização da interface do usuário, garantindo escalabilidade e manutenibilidade.

• Camada de Apresentação (Frontend): Construída com Astro e React. Optei pelo Astro por sua filosofia de “ilhas”, que permite hidratar interações complexas (como visualizadores 3D ou a interface de chat) apenas quando necessário. A interface é orquestrada por componentes de alto nível que delegam a renderização a subcomponentes especializados.
• Camada de Orquestração e API: Exposta por meio de rotas de API seguras que atuam como middleware. Essa camada gerencia o upload de arquivos, a verificação de configuração distribuída em tempo real e a delegação de requisições em streaming ao motor cognitivo subjacente.
• Motor Cognitivo (Camada Agêntica): Representa o núcleo do domínio. Configurei um Agente autônomo equipado com ferramentas de consulta vetorial e capacidades multimodais, encapsulando completamente a lógica de inferência e a interação com o RAG.

graph TD
    %% Diagrama de Arquitetura
    User([Usuário]) --> |Carrega Imagem / Mensagem| UI[Camada de Apresentação UI\nReact / Astro]
    UI --> |FormData| API[Middleware de API\n/api/analyze.ts]

    subgraph Infraestrutura Edge
        API --> |Upload| BlobStore[(Vercel Blob)]
        API --> |Verificação de Estado| EdgeConfig[(Edge Config)]
    end

    API --> |Requisição em Stream\nContexto + URL da Imagem| Agent[Motor Cognitivo\nAgente Mastra]

    subgraph Camada Cognitiva
        Agent --> |Extração de Entidades| LLM[Google Gemini Multimodal]
        Agent --> |Consulta Vetorial| VectorTool[Ferramenta de Busca RAG]
        VectorTool --> |Embeddings Text-004| VectorDB[(LibSQL Vector Store)]
        Agent --> |Gerenciamento de Contexto| Memory[(LibSQL Store\nMastra Memory)]
    end

    LLM --> |Resposta Sintetizada| Agent
    Agent --> |Server-Sent Events| API
    API --> |Stream| UI

Modelagem de Dados e Gerenciamento de Estado

A aplicação exige controle estrito sobre o estado conversacional e os artefatos processados. Para isso, implementei um modelo de persistência baseado em threads de execução.

• Gerenciamento de Estado no Frontend: Tratado de forma centralizada por meio de hooks do React e contêineres de contexto, mantendo um fluxo de dados estritamente unidirecional para os componentes de renderização (chat, visualizador interativo, feedback visual).
• Gerenciamento de Estado no Backend: O framework agêntico utiliza módulos de memória transacional para persistir de forma autônoma o histórico de mensagens em um banco de dados embarcado, vinculando-as por meio de identificadores únicos.

erDiagram
    %% Modelo de Dados
    THREAD {
        string threadId PK
        datetime createdAt
    }
    MESSAGE {
        string messageId PK
        string role "user | assistant"
        text content
        string threadId FK
    }
    RESOURCE {
        string resourceId PK
        string publicUrl "URL de acesso ao Blob Storage"
    }
    KNOWLEDGE_CHUNK {
        string chunkId PK
        vector embedding "Dimensão: 768"
        text content
        string source
    }

    THREAD ||--o{ MESSAGE : contém
    THREAD ||--o| RESOURCE : contextualiza

Stack Tecnológico

A seleção de ferramentas neste projeto equilibra inovação, velocidade de desenvolvimento e eficiência de execução.

Camada / Domínio	Tecnologia	Justificativa Técnica e Papel
Framework Principal	Astro + React 19	O Astro fornece roteamento eficiente e um modelo de renderização otimizado. O React gerencia o estado reativo nas ilhas interativas.
Estilos e Interface	Tailwind CSS v4, shadcn/ui, Framer Motion	Sistema de design utilitário, componentes acessíveis sem acoplamento e animações declarativas de alto desempenho.
Renderização 3D	react-three-fiber, @react-three/postprocessing	Abstração declarativa de WebGL para renderizar cenas complexas e efeitos visuais vinculados às características analisadas.
Motor Cognitivo	Mastra Framework (@mastra/core)	Orquestrador de agentes de IA e fluxos de trabalho. Define o esquema de ferramentas, o gerenciamento de memória e as instruções base de análise.
Modelos de IA	Google Gemini (2.0 Flash / 3.0 Pro)	Motores fundacionais responsáveis pela análise visual, pela geração de embeddings de alta dimensionalidade e pela síntese em linguagem natural.
Inferência e RAG	Mistral AI (OCR)	Processamento da ingestão documental com reconhecimento óptico avançado para estruturar PDFs antes da vetorização.
Persistência de Dados	LibSQL / Vercel Edge Config / Vercel Blob	O LibSQL opera de forma dual como motor transacional e vetorial. O Edge Config e o Blob gerenciam configurações distribuídas e binários estáticos.

Impacto Arquitetural

A implementação deste design consolidou um ecossistema coeso no qual a análise multimodal opera de forma integrada, melhorando a fidelidade das respostas por meio de uma arquitetura de Geração Aumentada por Recuperação. Ao transferir a lógica de inferência para um ambiente de agentes autônomos e abstrair o armazenamento por meio de bancos de dados embarcados nativos do Edge, isolei a camada de apresentação dos gargalos computacionais típicos dos sistemas de IA generativa. O resultado é um sistema que escala de forma previsível e mantém a consistência arquitetural em seus fluxos de dados.