# nstar9/hawkai architecture

> Architecture diagram of the GitHub repository nstar9/hawkai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nstar9/hawkai
- Repository: https://github.com/nstar9/hawkai

## Overview

#### 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.

Main entry points: [`backend/app/agent/intelligence_agent.py`](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/intelligence_agent.py) (Compliance intelligence agent), [`frontend/src/components/terminal/TerminalHome.tsx`](https://github.com/nstar9/hawkai/blob/main/frontend/src/components/terminal/TerminalHome.tsx) (Terminal components), [`backend/app/services/mongodb_service.py`](https://github.com/nstar9/hawkai/blob/main/backend/app/services/mongodb_service.py) (MongoDB access service), [`backend/app/services/investigation_service.py`](https://github.com/nstar9/hawkai/blob/main/backend/app/services/investigation_service.py) (Investigation lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Terminal UI"]
  node_ui_home["Operations dashboard<br/>Next.js page<br/>[page.tsx]"]
  node_ui_detail["Investigation detail<br/>Next.js route<br/>[page.tsx]"]
  node_terminal["Terminal components<br/>React UI<br/>[TerminalHome.tsx]"]
  node_entity_graph["Correlation graph<br/>React visualization<br/>[EntityGraph.tsx]"]
  node_frontend_api["Backend API client<br/>TypeScript client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["FastAPI application<br/>API entry point<br/>[main.py]"]
  node_routes["REST and SSE routes<br/>HTTP boundary<br/>[routes.py]"]
  node_investigation_service["Investigation lifecycle<br/>service layer"]
end

subgraph group_agents["Agent pipeline"]
  node_orchestrator{{"Scout orchestrator<br/>ADK workflow<br/>[orchestrator.py]"}}
  node_research_agent["OSINT research agent<br/>Gemini Flash agent<br/>[research_agent.py]"]
  node_intelligence_agent["Compliance intelligence agent<br/>ADK agent"]
  node_prompts["Prompt contracts<br/>agent prompts<br/>[prompts.py]"]
end

subgraph group_data["Data &amp; intelligence"]
  node_mcp_tools["Entity and sanctions tools<br/>MCP toolset<br/>[mcp_tool.py]"]
  node_entity_tools["Entity profile tools<br/>persistence tools<br/>[entity_tools.py]"]
  node_risk_tools["Risk scoring and reports<br/>risk tools<br/>[risk_tools.py]"]
  node_vector_tools["Vector similarity tools<br/>embedding search<br/>[vector_tools.py]"]
  node_mongodb_service["MongoDB access service<br/>async persistence<br/>[mongodb_service.py]"]
  node_ofac_loader["OFAC SDN loader<br/>data ingestion script<br/>[load_ofac_sdn.py]"]
end

node_atlas[("MongoDB Atlas<br/>system of record")]
node_gemini{{"Google Gemini<br/>AI models"}}

node_ui_home --> node_terminal
node_ui_detail --> node_terminal
node_terminal -->|"renders topology"| node_entity_graph
node_terminal -->|"uses"| node_frontend_api
node_frontend_api -->|"REST + SSE"| node_routes
node_fastapi -->|"mounts"| node_routes
node_routes -->|"investigation commands"| node_investigation_service
node_investigation_service -->|"runs pipeline"| node_orchestrator
node_investigation_service -->|"persists lifecycle"| node_mongodb_service
node_orchestrator -->|"research stage"| node_research_agent
node_orchestrator -->|"intelligence stage"| node_intelligence_agent
node_research_agent -->|"grounded search"| node_gemini
node_intelligence_agent -->|"screen and lookup"| node_mcp_tools
node_intelligence_agent -->|"store profile"| node_entity_tools
node_intelligence_agent -->|"correlate entities"| node_vector_tools
node_intelligence_agent -->|"classify and synthesize"| node_risk_tools
node_intelligence_agent -->|"Pro analysis"| node_gemini
node_mcp_tools -->|"entity + OFAC queries"| node_atlas
node_entity_tools -->|"write entities"| node_mongodb_service
node_risk_tools -->|"write signals and report"| node_mongodb_service
node_vector_tools -->|"$vectorSearch"| node_atlas
node_mongodb_service -->|"Motor access"| node_atlas
node_ofac_loader -->|"seeds SDN collection"| node_atlas
node_prompts -.->|"research contract"| node_research_agent
node_prompts -.->|"intelligence contract"| node_intelligence_agent

click node_ui_home "https://github.com/nstar9/hawkai/blob/main/frontend/src/app/page.tsx"
click node_ui_detail "https://github.com/nstar9/hawkai/blob/main/frontend/src/app/investigations/%5Bid%5D/page.tsx"
click node_terminal "https://github.com/nstar9/hawkai/blob/main/frontend/src/components/terminal/TerminalHome.tsx"
click node_entity_graph "https://github.com/nstar9/hawkai/blob/main/frontend/src/components/terminal/EntityGraph.tsx"
click node_frontend_api "https://github.com/nstar9/hawkai/blob/main/frontend/src/lib/api.ts"
click node_fastapi "https://github.com/nstar9/hawkai/blob/main/backend/app/main.py"
click node_routes "https://github.com/nstar9/hawkai/blob/main/backend/app/api/routes.py"
click node_investigation_service "https://github.com/nstar9/hawkai/blob/main/backend/app/services/investigation_service.py"
click node_orchestrator "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/orchestrator.py"
click node_research_agent "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/research_agent.py"
click node_intelligence_agent "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/intelligence_agent.py"
click node_prompts "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/prompts.py"
click node_mcp_tools "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/mcp_tool.py"
click node_entity_tools "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/entity_tools.py"
click node_risk_tools "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/risk_tools.py"
click node_vector_tools "https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/vector_tools.py"
click node_mongodb_service "https://github.com/nstar9/hawkai/blob/main/backend/app/services/mongodb_service.py"
click node_ofac_loader "https://github.com/nstar9/hawkai/blob/main/backend/scripts/load_ofac_sdn.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_home,node_ui_detail,node_terminal,node_entity_graph,node_frontend_api toneBlue
class node_fastapi,node_routes,node_investigation_service toneAmber
class node_orchestrator,node_research_agent,node_intelligence_agent,node_prompts toneMint
class node_mcp_tools,node_entity_tools,node_risk_tools,node_vector_tools,node_mongodb_service,node_ofac_loader toneRose
class node_atlas,node_gemini toneNeutral
```

## Components

### Terminal UI

- [Operations dashboard](https://github.com/nstar9/hawkai/blob/main/frontend/src/app/page.tsx): Next.js page · `frontend/src/app/page.tsx`
- [Investigation detail](https://github.com/nstar9/hawkai/blob/main/frontend/src/app/investigations/%5Bid%5D/page.tsx): Next.js route · `frontend/src/app/investigations/[id]/page.tsx`
- [Terminal components](https://github.com/nstar9/hawkai/blob/main/frontend/src/components/terminal/TerminalHome.tsx): React UI · Composes the dashboard and correlation topology. · `frontend/src/components/terminal/TerminalHome.tsx`
- [Correlation graph](https://github.com/nstar9/hawkai/blob/main/frontend/src/components/terminal/EntityGraph.tsx): React visualization · `frontend/src/components/terminal/EntityGraph.tsx`
- [Backend API client](https://github.com/nstar9/hawkai/blob/main/frontend/src/lib/api.ts): TypeScript client · `frontend/src/lib/api.ts`

### Backend API

- [FastAPI application](https://github.com/nstar9/hawkai/blob/main/backend/app/main.py): API entry point · `backend/app/main.py`
- [REST and SSE routes](https://github.com/nstar9/hawkai/blob/main/backend/app/api/routes.py): HTTP boundary · Creates investigations and streams progress snapshots. · `backend/app/api/routes.py`
- [Investigation lifecycle](https://github.com/nstar9/hawkai/blob/main/backend/app/services/investigation_service.py): service layer · Coordinates persistence, pipeline execution, and event progression. · `backend/app/services/investigation_service.py`

### Agent pipeline

- [Scout orchestrator](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/orchestrator.py): ADK workflow · Separates search and database tool sessions. · `backend/app/agent/orchestrator.py`
- [OSINT research agent](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/research_agent.py): Gemini Flash agent · `backend/app/agent/research_agent.py`
- [Compliance intelligence agent](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/intelligence_agent.py): ADK agent · Persists intelligence and invokes screening, entity, and risk tools. · `backend/app/agent/intelligence_agent.py`
- [Prompt contracts](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/prompts.py): agent prompts · `backend/app/agent/prompts.py`

### Data & intelligence

- [Entity and sanctions tools](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/mcp_tool.py): MCP toolset · Provides entity lookup and OFAC screening. · `backend/app/agent/tools/mcp_tool.py`
- [Entity profile tools](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/entity_tools.py): persistence tools · `backend/app/agent/tools/entity_tools.py`
- [Risk scoring and reports](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/risk_tools.py): risk tools · Classifies evidence into structured score, findings, and recommendations. · `backend/app/agent/tools/risk_tools.py`
- [Vector similarity tools](https://github.com/nstar9/hawkai/blob/main/backend/app/agent/tools/vector_tools.py): embedding search · Generates 768-dimensional embeddings and queries Atlas vector search. · `backend/app/agent/tools/vector_tools.py`
- [MongoDB access service](https://github.com/nstar9/hawkai/blob/main/backend/app/services/mongodb_service.py): async persistence · Owns Motor writes and database operations. · `backend/app/services/mongodb_service.py`
- [OFAC SDN loader](https://github.com/nstar9/hawkai/blob/main/backend/scripts/load_ofac_sdn.py): data ingestion script · `backend/scripts/load_ofac_sdn.py`

### Other components

- **MongoDB Atlas**: system of record · Stores investigations, entities, signals, notes, and OFAC SDN data.
- **Google Gemini**: AI models · Flash handles orchestration/search; Pro classifies signals and synthesizes reports.

## Connections

- Operations dashboard → Terminal components
- Investigation detail → Terminal components
- Terminal components → Correlation graph: renders topology
- Terminal components → Backend API client: uses
- Backend API client → REST and SSE routes: REST + SSE
- FastAPI application → REST and SSE routes: mounts
- REST and SSE routes → Investigation lifecycle: investigation commands
- Investigation lifecycle → Scout orchestrator: runs pipeline
- Investigation lifecycle → MongoDB access service: persists lifecycle
- Scout orchestrator → OSINT research agent: research stage
- Scout orchestrator → Compliance intelligence agent: intelligence stage
- OSINT research agent → Google Gemini: grounded search
- Compliance intelligence agent → Entity and sanctions tools: screen and lookup
- Compliance intelligence agent → Entity profile tools: store profile
- Compliance intelligence agent → Vector similarity tools: correlate entities
- Compliance intelligence agent → Risk scoring and reports: classify and synthesize
- Compliance intelligence agent → Google Gemini: Pro analysis
- Entity and sanctions tools → MongoDB Atlas: entity + OFAC queries
- Entity profile tools → MongoDB access service: write entities
- Risk scoring and reports → MongoDB access service: write signals and report
- Vector similarity tools → MongoDB Atlas: $vectorSearch
- MongoDB access service → MongoDB Atlas: Motor access
- OFAC SDN loader → MongoDB Atlas: seeds SDN collection
- Prompt contracts → OSINT research agent: research contract
- Prompt contracts → Compliance intelligence agent: intelligence contract