# lovingocean/nova-ai architecture

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

- Interactive diagram: https://gitdiagram.com/lovingocean/nova-ai
- Repository: https://github.com/lovingocean/nova-ai

## Overview

Nova is a browser-based multi-agent business-task assistant. A user submits a request through the app; the hook delegates it to the master agent, which analyzes intent, plans work, executes specialized agents, verifies results, and exposes progress and output in the UI. The repository also contains a standalone payment-oriented variant; its payment screen is included, but the sampled evidence does not establish how it is routed or backed. The graph focuses on the root application; unsampled tools and integration wiring are not inferred.

Main entry points: [`src/App.tsx`](https://github.com/lovingocean/nova-ai/blob/master/src/App.tsx) (Nova app), [`src/nova/NovaMasterAgent.ts`](https://github.com/lovingocean/nova-ai/blob/master/src/nova/NovaMasterAgent.ts) (Master agent), [`src/nova/engine/executor.ts`](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/executor.ts) (Plan executor), [`src/nova/engine/planner.ts`](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/planner.ts) (Plan creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Nova app<br/>[App.tsx]"]
  node_landing["Landing page<br/>[Landing.tsx]"]
  node_chat["Chat panel<br/>[ChatPanel.tsx]"]
  node_agentlist["Agent list<br/>[AgentList.tsx]"]
  node_executionui["Execution view<br/>[ExecutionPanel.tsx]"]
  node_result["Result panel<br/>[ResultPanel.tsx]"]
  node_standalone_payment["Standalone auth and payment<br/>[AuthPayment.tsx]"]
end

subgraph group_orchestration["Task orchestration"]
  node_hook["Nova hook<br/>[useNova.ts]"]
  node_master["Master agent<br/>[NovaMasterAgent.ts]"]
  node_intent["Intent analysis<br/>[intentAnalyzer.ts]"]
  node_planner["Plan creation<br/>[planner.ts]"]
  node_verifier["Output verification<br/>[verifier.ts]"]
  node_contracts["Core contracts<br/>[types.ts]"]
end

subgraph group_execution["Agent execution"]
  node_executor["Plan executor<br/>[executor.ts]"]
  node_agents["Specialized agents<br/>[agents.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
end

subgraph group_services["Providers and persistence"]
  node_provider["LLM providers<br/>[providers.ts]"]
  node_persistence["Task persistence<br/>[persistence.ts]"]
  node_database[("Database adapter<br/>[db.ts]")]
end

node_user(("User"))
node_external_llm(("External LLM"))

node_user -->|"submits task"| node_app
node_app -->|"renders"| node_landing
node_app -->|"uses"| node_hook
node_app -->|"renders"| node_chat
node_app -->|"renders"| node_agentlist
node_app -->|"renders"| node_executionui
node_app -->|"renders"| node_result
node_hook -->|"delegates to"| node_master
node_master -->|"records tasks"| node_persistence
node_master -->|"analyzes intent"| node_intent
node_master -->|"creates plan"| node_planner
node_master -->|"executes plan"| node_executor
node_master -->|"verifies results"| node_verifier
node_executor -->|"looks up agents"| node_agents
node_executor -->|"runs agent"| node_provider
node_executor -->|"resolves order"| node_planner
node_planner -->|"selects from registry"| node_agents
node_persistence -->|"uses adapter"| node_database
node_provider -.->|"calls when configured"| node_external_llm

click node_app "https://github.com/lovingocean/nova-ai/blob/master/src/App.tsx"
click node_landing "https://github.com/lovingocean/nova-ai/blob/master/src/Landing.tsx"
click node_chat "https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ChatPanel.tsx"
click node_agentlist "https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/AgentList.tsx"
click node_executionui "https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ExecutionPanel.tsx"
click node_result "https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ResultPanel.tsx"
click node_hook "https://github.com/lovingocean/nova-ai/blob/master/src/nova/useNova.ts"
click node_master "https://github.com/lovingocean/nova-ai/blob/master/src/nova/NovaMasterAgent.ts"
click node_intent "https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/intentAnalyzer.ts"
click node_planner "https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/planner.ts"
click node_verifier "https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/verifier.ts"
click node_contracts "https://github.com/lovingocean/nova-ai/blob/master/src/nova/types.ts"
click node_executor "https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/executor.ts"
click node_agents "https://github.com/lovingocean/nova-ai/blob/master/src/nova/agents.ts"
click node_tools "https://github.com/lovingocean/nova-ai/blob/master/src/nova/tools.ts"
click node_provider "https://github.com/lovingocean/nova-ai/blob/master/src/nova/providers.ts"
click node_persistence "https://github.com/lovingocean/nova-ai/blob/master/src/nova/persistence.ts"
click node_database "https://github.com/lovingocean/nova-ai/blob/master/src/nova/db.ts"
click node_standalone_payment "https://github.com/lovingocean/nova-ai/blob/master/nova-ai-with-payments/nova-standalone/src/AuthPayment.tsx"

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_app,node_landing,node_chat,node_agentlist,node_executionui,node_result,node_standalone_payment,node_user toneBlue
class node_hook,node_master,node_intent,node_planner,node_verifier,node_contracts toneAmber
class node_executor,node_agents,node_tools toneMint
class node_provider,node_persistence,node_database toneRose
class node_external_llm toneIndigo
```

## Components

### User experience

- [Nova app](https://github.com/lovingocean/nova-ai/blob/master/src/App.tsx): `src/App.tsx`
- [Landing page](https://github.com/lovingocean/nova-ai/blob/master/src/Landing.tsx): `src/Landing.tsx`
- [Chat panel](https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ChatPanel.tsx): `src/nova/ui/ChatPanel.tsx`
- [Agent list](https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/AgentList.tsx): `src/nova/ui/AgentList.tsx`
- [Execution view](https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ExecutionPanel.tsx): `src/nova/ui/ExecutionPanel.tsx`
- [Result panel](https://github.com/lovingocean/nova-ai/blob/master/src/nova/ui/ResultPanel.tsx): `src/nova/ui/ResultPanel.tsx`
- [Standalone auth and payment](https://github.com/lovingocean/nova-ai/blob/master/nova-ai-with-payments/nova-standalone/src/AuthPayment.tsx): `nova-ai-with-payments/nova-standalone/src/AuthPayment.tsx`

### Task orchestration

- [Nova hook](https://github.com/lovingocean/nova-ai/blob/master/src/nova/useNova.ts): `src/nova/useNova.ts`
- [Master agent](https://github.com/lovingocean/nova-ai/blob/master/src/nova/NovaMasterAgent.ts): `src/nova/NovaMasterAgent.ts`
- [Intent analysis](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/intentAnalyzer.ts): `src/nova/engine/intentAnalyzer.ts`
- [Plan creation](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/planner.ts): `src/nova/engine/planner.ts`
- [Output verification](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/verifier.ts): `src/nova/engine/verifier.ts`
- [Core contracts](https://github.com/lovingocean/nova-ai/blob/master/src/nova/types.ts): `src/nova/types.ts`

### Agent execution

- [Plan executor](https://github.com/lovingocean/nova-ai/blob/master/src/nova/engine/executor.ts): `src/nova/engine/executor.ts`
- [Specialized agents](https://github.com/lovingocean/nova-ai/blob/master/src/nova/agents.ts): `src/nova/agents.ts`
- [Agent tools](https://github.com/lovingocean/nova-ai/blob/master/src/nova/tools.ts): `src/nova/tools.ts`

### Providers and persistence

- [LLM providers](https://github.com/lovingocean/nova-ai/blob/master/src/nova/providers.ts): `src/nova/providers.ts`
- [Task persistence](https://github.com/lovingocean/nova-ai/blob/master/src/nova/persistence.ts): `src/nova/persistence.ts`
- [Database adapter](https://github.com/lovingocean/nova-ai/blob/master/src/nova/db.ts): `src/nova/db.ts`

### Other components

- **User**
- **External LLM**

## Connections

- User → Nova app: submits task (evidence: `src/App.tsx`)
- Nova app → Landing page: renders (evidence: `src/App.tsx`)
- Nova app → Nova hook: uses (evidence: `src/App.tsx`)
- Nova app → Chat panel: renders (evidence: `src/App.tsx`)
- Nova app → Agent list: renders (evidence: `src/App.tsx`)
- Nova app → Execution view: renders (evidence: `src/App.tsx`)
- Nova app → Result panel: renders (evidence: `src/App.tsx`)
- Nova hook → Master agent: delegates to (evidence: `src/nova/useNova.ts`)
- Master agent → Task persistence: records tasks (evidence: `src/nova/NovaMasterAgent.ts`)
- Master agent → Intent analysis: analyzes intent (evidence: `src/nova/NovaMasterAgent.ts`)
- Master agent → Plan creation: creates plan (evidence: `src/nova/NovaMasterAgent.ts`)
- Master agent → Plan executor: executes plan (evidence: `src/nova/NovaMasterAgent.ts`)
- Master agent → Output verification: verifies results (evidence: `src/nova/NovaMasterAgent.ts`)
- Plan executor → Specialized agents: looks up agents (evidence: `src/nova/engine/executor.ts`)
- Plan executor → LLM providers: runs agent (evidence: `src/nova/engine/executor.ts`)
- Plan executor → Plan creation: resolves order (evidence: `src/nova/engine/executor.ts`)
- Plan creation → Specialized agents: selects from registry (evidence: `src/nova/engine/planner.ts`)
- Task persistence → Database adapter: uses adapter (evidence: `src/nova/persistence.ts`)
- LLM providers → External LLM: calls when configured (evidence: `src/nova/providers.ts`)
