# hackerai-tech/hackerai architecture

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

- Interactive diagram: https://gitdiagram.com/hackerai-tech/hackerai
- Repository: https://github.com/hackerai-tech/hackerai

## Overview

HackerAI is an AI-powered penetration-testing assistant. A user opens the chat UI, selects a conversational or Agent mode, submits prompts and files, and receives streamed model reasoning, tool activity, and results. Agent runs are dispatched through API endpoints and a durable Trigger.dev runtime, using model providers and isolated sandboxes for terminal, web, file, and subagent work. Convex persists chats, messages, files, usage, and teams; WorkOS authenticates users, while Stripe supports subscriptions and usage billing. Sampled files show storage and sandbox coordination; some broader routes are represented from the repository tree and README.

Main entry points: [`lib/chat/chat-processor.ts`](https://github.com/hackerai-tech/hackerai/blob/main/lib/chat/chat-processor.ts) (Chat Processor), [`lib/ai/tools/index.ts`](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/index.ts) (Agent Tools), [`convex/schema.ts`](https://github.com/hackerai-tech/hackerai/blob/main/convex/schema.ts) (Convex Backend), [`app/hooks/useChatHandlers.ts`](https://github.com/hackerai-tech/hackerai/blob/main/app/hooks/useChatHandlers.ts) (Chat Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_chat_ui["Chat Interface<br/>[HomePageClient.tsx]"]
  node_chat_handlers["Chat Handlers<br/>[useChatHandlers.ts]"]
  node_message_stream["Streamed Results"]
end

subgraph group_orchestration["AI Orchestration"]
  node_agent_api["Agent API<br/>[route.ts]"]
  node_long_agent_api["Long Agent API<br/>[route.ts]"]
  node_agent_runner["Agent Stream Runner"]
  node_chat_processor["Chat Processor<br/>[chat-processor.ts]"]
  node_ai_providers["Model Providers<br/>[providers.ts]"]
  node_trigger["Durable Agent Runtime<br/>[route.ts]"]
end

subgraph group_execution["Execution Tools"]
  node_tool_registry["Agent Tools<br/>[index.ts]"]
  node_sandbox_manager["Hybrid Sandbox Manager"]
  node_terminal_tools["Terminal Tools"]
  node_web_tools["Web Tools<br/>[web-search.ts]"]
  node_subagents["Subagent Runtime<br/>[agent-handle.ts]"]
end

subgraph group_data["Product Data"]
  node_convex[("Convex Backend<br/>[schema.ts]")]
  node_chat_data["Chats Messages Projects<br/>[chats.ts]"]
  node_file_data[("File Storage Records<br/>[fileStorage.ts]")]
end

subgraph group_platform["Identity Billing"]
  node_workos["WorkOS Identity"]
  node_billing_api["Billing Routes<br/>[route.ts]"]
  node_usage[("Usage Accounting<br/>[usageLogs.ts]")]
end

node_user(("Security User"))
node_s3[("Amazon S3")]
node_stripe["Stripe"]
node_e2b["E2B Sandbox"]
node_miosa["MIOSA Sandbox"]
node_perplexity["Perplexity Search"]
node_redis["Redis Streams"]

node_user -->|"uses"| node_chat_ui
node_chat_ui -->|"submits prompts"| node_chat_handlers
node_chat_handlers -->|"starts agent"| node_agent_api
node_chat_handlers -->|"starts long run"| node_long_agent_api
node_chat_handlers -->|"updates stream"| node_message_stream
node_agent_api -->|"dispatches run"| node_agent_runner
node_long_agent_api -->|"dispatches run"| node_agent_runner
node_agent_runner -->|"runs durably"| node_trigger
node_agent_runner -->|"processes chat"| node_chat_processor
node_chat_processor -->|"requests completion"| node_ai_providers
node_chat_processor -->|"dispatches tools"| node_tool_registry
node_chat_processor -->|"persists messages"| node_chat_data
node_chat_processor -->|"records usage"| node_usage
node_tool_registry -->|"dispatches terminal"| node_terminal_tools
node_tool_registry -->|"dispatches web"| node_web_tools
node_tool_registry -->|"controls workspace"| node_sandbox_manager
node_tool_registry -->|"starts subagents"| node_subagents
node_sandbox_manager -->|"uses cloud sandbox"| node_e2b
node_sandbox_manager -.->|"uses native sandbox"| node_miosa
node_sandbox_manager -->|"reads connections"| node_convex
node_chat_data -->|"stores domain data"| node_convex
node_file_data -->|"stores metadata"| node_convex
node_file_data -->|"stores file objects"| node_s3
node_chat_ui -->|"uploads files"| node_file_data
node_ai_providers -.->|"searches web"| node_perplexity
node_chat_processor -.->|"resumes streams"| node_redis
node_agent_api -->|"checks identity"| node_workos
node_billing_api -->|"resolves user"| node_workos
node_billing_api -->|"creates checkout"| node_stripe
node_stripe -->|"sends webhooks"| node_billing_api
node_billing_api -->|"updates billing state"| node_convex
node_usage -->|"persists charges"| node_convex

click node_chat_ui "https://github.com/hackerai-tech/hackerai/blob/main/app/(chat)/HomePageClient.tsx"
click node_chat_handlers "https://github.com/hackerai-tech/hackerai/blob/main/app/hooks/useChatHandlers.ts"
click node_message_stream "https://github.com/hackerai-tech/hackerai/blob/main/app/components/DataStreamProvider.tsx"
click node_agent_api "https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent/route.ts"
click node_long_agent_api "https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent-long/route.ts"
click node_agent_runner "https://github.com/hackerai-tech/hackerai/blob/main/lib/api/agent-stream-runner.ts"
click node_chat_processor "https://github.com/hackerai-tech/hackerai/blob/main/lib/chat/chat-processor.ts"
click node_ai_providers "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/providers.ts"
click node_trigger "https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent/route.ts"
click node_tool_registry "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/index.ts"
click node_sandbox_manager "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/utils/hybrid-sandbox-manager.ts"
click node_terminal_tools "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/run-terminal-cmd.ts"
click node_web_tools "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/web-search.ts"
click node_subagents "https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/subagents/agent-handle.ts"
click node_convex "https://github.com/hackerai-tech/hackerai/blob/main/convex/schema.ts"
click node_chat_data "https://github.com/hackerai-tech/hackerai/blob/main/convex/chats.ts"
click node_file_data "https://github.com/hackerai-tech/hackerai/blob/main/convex/fileStorage.ts"
click node_billing_api "https://github.com/hackerai-tech/hackerai/blob/main/app/api/subscribe/route.ts"
click node_usage "https://github.com/hackerai-tech/hackerai/blob/main/convex/usageLogs.ts"

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_chat_ui,node_chat_handlers,node_message_stream,node_user toneBlue
class node_agent_api,node_long_agent_api,node_agent_runner,node_chat_processor,node_ai_providers,node_trigger,node_s3,node_redis toneAmber
class node_tool_registry,node_sandbox_manager,node_terminal_tools,node_web_tools,node_subagents toneMint
class node_convex,node_chat_data,node_file_data toneRose
class node_workos,node_billing_api,node_usage,node_stripe,node_e2b,node_miosa,node_perplexity toneIndigo
```

## Components

### User Experience

- [Chat Interface](https://github.com/hackerai-tech/hackerai/blob/main/app/(chat)/HomePageClient.tsx): `app/(chat)/HomePageClient.tsx`
- [Chat Handlers](https://github.com/hackerai-tech/hackerai/blob/main/app/hooks/useChatHandlers.ts): `app/hooks/useChatHandlers.ts`
- [Streamed Results](https://github.com/hackerai-tech/hackerai/blob/main/app/components/DataStreamProvider.tsx): `app/components/DataStreamProvider.tsx`

### AI Orchestration

- [Agent API](https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent/route.ts): `app/api/agent/route.ts`
- [Long Agent API](https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent-long/route.ts): `app/api/agent-long/route.ts`
- [Agent Stream Runner](https://github.com/hackerai-tech/hackerai/blob/main/lib/api/agent-stream-runner.ts): `lib/api/agent-stream-runner.ts`
- [Chat Processor](https://github.com/hackerai-tech/hackerai/blob/main/lib/chat/chat-processor.ts): `lib/chat/chat-processor.ts`
- [Model Providers](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/providers.ts): `lib/ai/providers.ts`
- [Durable Agent Runtime](https://github.com/hackerai-tech/hackerai/blob/main/app/api/agent/route.ts): `app/api/agent/route.ts`

### Execution Tools

- [Agent Tools](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/index.ts): `lib/ai/tools/index.ts`
- [Hybrid Sandbox Manager](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/utils/hybrid-sandbox-manager.ts): `lib/ai/tools/utils/hybrid-sandbox-manager.ts`
- [Terminal Tools](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/run-terminal-cmd.ts): `lib/ai/tools/run-terminal-cmd.ts`
- [Web Tools](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/tools/web-search.ts): `lib/ai/tools/web-search.ts`
- [Subagent Runtime](https://github.com/hackerai-tech/hackerai/blob/main/lib/ai/subagents/agent-handle.ts): `lib/ai/subagents/agent-handle.ts`

### Product Data

- [Convex Backend](https://github.com/hackerai-tech/hackerai/blob/main/convex/schema.ts): `convex/schema.ts`
- [Chats Messages Projects](https://github.com/hackerai-tech/hackerai/blob/main/convex/chats.ts): `convex/chats.ts`
- [File Storage Records](https://github.com/hackerai-tech/hackerai/blob/main/convex/fileStorage.ts): `convex/fileStorage.ts`

### Identity Billing

- **WorkOS Identity**
- [Billing Routes](https://github.com/hackerai-tech/hackerai/blob/main/app/api/subscribe/route.ts): `app/api/subscribe/route.ts`
- [Usage Accounting](https://github.com/hackerai-tech/hackerai/blob/main/convex/usageLogs.ts): `convex/usageLogs.ts`

### Other components

- **Security User**
- **Amazon S3**
- **Stripe**
- **E2B Sandbox**
- **MIOSA Sandbox**
- **Perplexity Search**
- **Redis Streams**

## Connections

- Security User → Chat Interface: uses
- Chat Interface → Chat Handlers: submits prompts
- Chat Handlers → Agent API: starts agent
- Chat Handlers → Long Agent API: starts long run
- Chat Handlers → Streamed Results: updates stream
- Agent API → Agent Stream Runner: dispatches run
- Long Agent API → Agent Stream Runner: dispatches run
- Agent Stream Runner → Durable Agent Runtime: runs durably
- Agent Stream Runner → Chat Processor: processes chat
- Chat Processor → Model Providers: requests completion
- Chat Processor → Agent Tools: dispatches tools
- Chat Processor → Chats Messages Projects: persists messages
- Chat Processor → Usage Accounting: records usage
- Agent Tools → Terminal Tools: dispatches terminal
- Agent Tools → Web Tools: dispatches web
- Agent Tools → Hybrid Sandbox Manager: controls workspace
- Agent Tools → Subagent Runtime: starts subagents
- Hybrid Sandbox Manager → E2B Sandbox: uses cloud sandbox
- Hybrid Sandbox Manager → MIOSA Sandbox: uses native sandbox
- Hybrid Sandbox Manager → Convex Backend: reads connections
- Chats Messages Projects → Convex Backend: stores domain data
- File Storage Records → Convex Backend: stores metadata
- File Storage Records → Amazon S3: stores file objects
- Chat Interface → File Storage Records: uploads files
- Model Providers → Perplexity Search: searches web
- Chat Processor → Redis Streams: resumes streams
- Agent API → WorkOS Identity: checks identity
- Billing Routes → WorkOS Identity: resolves user
- Billing Routes → Stripe: creates checkout
- Stripe → Billing Routes: sends webhooks
- Billing Routes → Convex Backend: updates billing state
- Usage Accounting → Convex Backend: persists charges