Cogniflow
On-chain Intelligence Agent & Portfolio Analytics Platform
Overview
Cogniflow ingests live Ethereum wallet activity, normalizes it inside Supabase Postgres, enriches each transfer with CoinGecko pricing and OpenAI embeddings, and exposes the insights through a production-ready Next.js dashboard and deterministic API surface. The platform is designed so LLM tooling can safely orchestrate named SQL queries and semantic search without ad-hoc code execution.
The MVP ships a resilient ingestion worker, typed REST APIs, a pgvector-powered semantic search layer, and a UI that surfaces portfolio summaries, transfers, USD valuations, and chat-style analytics. It is deployed on Vercel (`cogniflow-web.vercel.app`) with cron-ready ingestion endpoints.
Key Features
Continuous Wallet Ingestion
ts-node worker streams tracked wallets, retries on RPC failures, and performs idempotent upserts for transfers and blocks.
USD Valuation Pipeline
CoinGecko enrichment job snapshots token prices hourly and decorates every transfer with historical USD context.
Semantic Search & Embeddings
OpenAI embeddings (768-dim pgvector) allow intent-aware transfer search with support for token, amount, and counterparty insights.
Deterministic LLM Tooling
Named SQL queries and typed routes (`/tool/sql`, `/api/chat`) ensure external agents operate within audited guardrails.
Next.js Dashboard
App Router UI shows wallet net flows, holdings, transfer history, sync status, and semantic search results in real time.
Secure Job Triggers
Ingestion, pricing, and embeddings jobs exposed as secret-protected API routes ready for Vercel Cron or GitHub Actions.
Technical Architecture
Worker & Ingestion
ts-node worker iterates wallets, calls Alchemy JSON-RPC with exponential backoff, and syncs transfers via Prisma transactions shared with API routes.
Data Layer
Supabase Postgres plus pgvector hosts normalized tables for transfers, prices, embeddings, wallets, and blocks with deterministic IDs and indexing.
API Surface
Next.js route handlers expose `/api/transfers`, `/api/portfolio`, `/api/search`, `/api/chat`, `/tool/sql`, and health/ingestion endpoints with zod validation.
Frontend Dashboard
App Router UI built with Tailwind and shadcn-inspired components provides summary cards, holdings, transfers table, semantic search, and chat responses.
System Workflow
1. Wallet Tracking
`wallets` table stores addresses, chain metadata, and sync cursors. UI submissions auto-upsert new wallets and queue ingestion runs.
2. Transfer Ingestion
Worker queries `alchemy_getAssetTransfers` in both directions, normalizes transfers, handles missing log indices, and records block metadata.
3. Price & Embedding Enrichment
CoinGecko and OpenAI jobs run on demand or via cron to attach USD valuations and semantic vectors for transfers lacking enrichment.
4. Deterministic APIs & Tools
Dashboard and chat routes read from Postgres, stitch pricing data, call named SQL queries, and expose structured responses to future LLM agents.
Tooling Highlights
Named SQL Library
`/tool/sql` exposes allowlisted queries such as `topCounterparties` and `netFlowSummary`, enabling orchestrators to fetch aggregated data with zod-validated input.
Semantic Search
`/api/search` embeds natural language queries, filters by address/chain, and ranks transfers using cosine similarity, largest-value preference, and recency heuristics.
Impact & Metrics
Production APIs powering dashboard & chat tooling
Embedding dimensions normalized for pgvector search
Automated jobs (ingestion, pricing, embeddings) deployable via cron
Cogniflow has been validated against Sepolia and mainnet wallets, ensuring deterministic ingestion, pricing parity, and semantic insights across diverse token flows.
Challenges & Solutions
Reliable RPC Ingestion
Implemented exponential backoff, retry ceilings, and deterministic transfer IDs (`txHash:logIndex`) to handle reorgs and RPC hiccups without duplicate data.
Consistent USD Context
CoinGecko batching pipeline normalizes pricing snapshots and aligns them with transfer timestamps so holdings and chat summaries stay valuation-aware.
LLM Guardrails
Deterministic tool layer exposes only named SQL and semantic search endpoints, letting future agents perform analytics while keeping database access auditable.