nstar9/hawkai

Purpose and Entry Points

HawkAI is an autonomous KYC/AML investigation system: it researches entities, identifies adverse-risk signals, scores them, and stores a structured report. The backend FastAPI entry point is backend/app/main.py; REST/SSE endpoints are defined in backend/app/api/routes.py. The Next.js terminal UI starts at frontend/src/app/page.tsx, with investigation detail routing in frontend/src/app/investigations/[id]/page.tsx.

API, Investigation Lifecycle, and Streaming

A client creates an investigation through /api/v1/investigations; the backend persists lifecycle state, invokes the agent pipeline, and exposes the resulting investigation, entities, signals, and notes. The service layer coordinates creation, retrieval, deletion, and event progression in backend/app/services/investigation_service.py. SSE from backend/app/api/routes.py is the live control/data boundary: frontend receives agent steps, tool activity, and completed snapshots instead of awaiting a final report.

Sequential Agent Pipeline

backend/app/agent/orchestrator.py defines the ScoutOrchestrator/Google ADK sequential workflow. It deliberately separates live-search research from database/tool work because Google Search and database tools cannot share an ADK session. backend/app/agent/research_agent.py performs targeted, grounded OSINT using Gemini Flash; backend/app/agent/intelligence_agent.py converts research into persisted compliance intelligence and invokes downstream tools. Prompt contracts live in backend/app/agent/prompts.py.

Intelligence and Risk Stages

The intelligence stage first looks up known entities and screens OFAC sanctions, then extracts/stores an entity profile, generates an embedding, finds similar/correlated entities, classifies risk signals, and synthesizes the final report. Key implementations are backend/app/agent/tools/mcp_tool.py, backend/app/agent/tools/entity_tools.py, and backend/app/agent/tools/risk_tools.py. Gemini Flash is the orchestration/search model; Gemini Pro is used for high-quality signal classification and report synthesis.

Persistence, MCP, and Vector Search

MongoDB Atlas is the system of record for investigations, entity profiles, risk signals, notes, and the seeded OFAC SDN collection. backend/app/services/mongodb_service.py owns async Motor access and write-oriented database operations. backend/app/agent/tools/mcp_tool.py provides ADK MCPToolset access for entity lookup and sanctions screening, while backend/app/agent/tools/vector_tools.py performs 768-dimensional embedding/vector similarity operations against Atlas $vectorSearch. OFAC data is loaded by backend/scripts/load_ofac_sdn.py.

Domain Contracts and Scoring Boundary

Typed request/persistence/report contracts are represented by backend/app/schemas/investigation.py, backend/app/schemas/entity.py, and backend/app/schemas/risk.py. The risk boundary is evidence-oriented: classified signals across compliance categories feed a 0–100 score, level, findings, confidence, and recommendations. These structured artifacts—not raw model text—are what the API and UI consume.

Terminal Frontend and Deployment

The Next.js 14 App Router frontend calls backend APIs through frontend/src/lib/api.ts; shared API-facing types are in frontend/src/lib/types.ts. frontend/src/components/terminal/TerminalHome.tsx composes the operational dashboard, while frontend/src/components/terminal/EntityGraph.tsx renders client-side correlation topology from stored entities/signals. Docker composition is rooted at docker-compose.yml; separate images are defined in backend/Dockerfile and frontend/Dockerfile. Intended deployment is Cloud Run for FastAPI and Vercel for Next.js, with Google AI/Gemini and MongoDB Atlas as required external services.