# mohith535/nova-agentic-layer-over-taskflow architecture

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

- Interactive diagram: https://gitdiagram.com/mohith535/nova-agentic-layer-over-taskflow
- Repository: https://github.com/mohith535/nova-agentic-layer-over-taskflow

## Overview

Nova is a local-first AI layer over TaskFlow: a user asks for a briefing, coaching, planning, task action, or opportunity search, and Nova routes the request to a specialist that grounds its response or action in TaskFlow data. The web console also exposes profile onboarding, memory, behavioral context, and the Scout feed; the CLI offers the core agent and MCP entry points. The graph preserves the documented agent and integration branches. Some agent, storage, and web implementation details are unsampled, so uncertain relationships are omitted.

Main entry points: [`nova/web/server.py`](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/web/server.py) (Web console), [`nova/mcp/tools.py`](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/tools.py) (Nova capability layer), [`nova/orchestrator.py`](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/orchestrator.py) (Agent router), [`nova/agents/tools_adk.py`](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/tools_adk.py) (ADK tool wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_web["Web console<br/>[server.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_agents["Agent workflows"]
  node_router{{"Agent router<br/>[orchestrator.py]"}}
  node_brief["Briefing agent<br/>[briefing_agent.py]"]
  node_coach["Coach agent<br/>[coach_agent.py]"]
  node_fastcoach["Fast coach<br/>[fast_coach.py]"]
  node_planner["Planning agent<br/>[planning_agent.py]"]
  node_proposal["Plan proposals<br/>[planner_propose.py]"]
  node_operator["Task operator<br/>[operator_agent.py]"]
  node_scout["Opportunity scout<br/>[scout_agent.py]"]
  node_profile["Profile onboarding<br/>[profile_agent.py]"]
  node_reflection["Reflection"]
  node_patterns["Pattern insights<br/>[pattern_agent.py]"]
  node_greeting["Greeting<br/>[greeting_agent.py]"]
  node_toolwrap["ADK tool wrappers<br/>[tools_adk.py]"]
  node_mcpagents["MCP agent tools<br/>[mcp_backed.py]"]
end

subgraph group_data["TaskFlow and memory"]
  node_tools["Nova capability layer<br/>[tools.py]"]
  node_reader["TaskFlow reader<br/>[taskflow_reader.py]"]
  node_writer["TaskFlow writer<br/>[taskflow_writer.py]"]
  node_memory[("Local memory<br/>[store.py]")]
  node_models["Domain models<br/>[models.py]"]
  node_taskdata[("TaskFlow data<br/>[taskflow_reader.py]")]
end

subgraph group_integrations["MCP and integrations"]
  node_config["Model configuration<br/>[config.py]"]
  node_mcpserver["MCP server<br/>[server.py]"]
  node_hunter["Opportunity Hunter<br/>[hunter_bridge.py]"]
end

node_user(("User"))
node_gemini["Gemini"]
node_taskflow[("TaskFlow user data")]

node_user -->|"uses console"| node_web
node_user -->|"runs commands"| node_cli
node_web -->|"reads context"| node_tools
node_web -->|"runs onboarding"| node_profile
node_web -->|"requests reflection"| node_reflection
node_web -->|"requests greeting"| node_greeting
node_web -->|"routes requests"| node_router
node_cli -->|"builds agent"| node_router
node_cli -->|"runs MCP"| node_mcpserver
node_router -->|"transfers briefing"| node_brief
node_router -->|"transfers coaching"| node_coach
node_router -->|"transfers planning"| node_planner
node_router -->|"transfers task action"| node_operator
node_router -->|"transfers scouting"| node_scout
node_brief -->|"uses tools"| node_toolwrap
node_coach -->|"uses tools"| node_toolwrap
node_planner -->|"uses tools"| node_toolwrap
node_operator -->|"uses tools"| node_toolwrap
node_scout -->|"uses tools"| node_toolwrap
node_web -->|"runs fast coaching"| node_fastcoach
node_web -->|"requests patterns"| node_patterns
node_web -->|"proposes plans"| node_proposal
node_planner -.->|"prepares proposals"| node_proposal
node_toolwrap -->|"calls capabilities"| node_tools
node_coach -->|"uses MCP optionally"| node_mcpagents
node_mcpagents -->|"spawns subprocess"| node_mcpserver
node_mcpserver -->|"wraps capabilities"| node_tools
node_tools -->|"reads task data"| node_reader
node_tools -->|"writes task data"| node_writer
node_tools -->|"recalls and stores"| node_memory
node_tools -->|"uses domain models"| node_models
node_reader -->|"resolves local data"| node_taskdata
node_writer -->|"uses task reader"| node_reader
node_reader -.->|"reads local board"| node_taskflow
node_writer -.->|"updates local board"| node_taskflow
node_tools -->|"delegates hunter actions"| node_hunter
node_config -->|"validates API key"| node_gemini
node_brief -->|"selects model"| node_config
node_coach -->|"selects model"| node_config
node_planner -->|"selects model"| node_config

click node_web "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/web/server.py"
click node_cli "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/main.py"
click node_router "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/orchestrator.py"
click node_brief "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/briefing_agent.py"
click node_coach "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/coach_agent.py"
click node_fastcoach "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/fast_coach.py"
click node_planner "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/planning_agent.py"
click node_proposal "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/planner_propose.py"
click node_operator "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/operator_agent.py"
click node_scout "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/scout_agent.py"
click node_profile "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/profile_agent.py"
click node_reflection "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/reflection_agent.py"
click node_patterns "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/pattern_agent.py"
click node_greeting "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/greeting_agent.py"
click node_toolwrap "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/tools_adk.py"
click node_mcpagents "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/mcp_backed.py"
click node_tools "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/tools.py"
click node_reader "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_reader.py"
click node_writer "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_writer.py"
click node_memory "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/memory/store.py"
click node_models "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/models.py"
click node_config "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/config.py"
click node_mcpserver "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/server.py"
click node_hunter "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/hunter_bridge.py"
click node_taskdata "https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_reader.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_web,node_cli,node_user toneBlue
class node_router,node_brief,node_coach,node_fastcoach,node_planner,node_proposal,node_operator,node_scout,node_profile,node_reflection,node_patterns,node_greeting,node_toolwrap,node_mcpagents,node_taskflow toneAmber
class node_tools,node_reader,node_writer,node_memory,node_models,node_taskdata toneMint
class node_config,node_mcpserver,node_hunter toneRose
class node_gemini toneIndigo
```

## Components

### User entry points

- [Web console](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/web/server.py): `nova/web/server.py`
- [CLI](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/main.py): `nova/main.py`

### Agent workflows

- [Agent router](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/orchestrator.py): `nova/orchestrator.py`
- [Briefing agent](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/briefing_agent.py): `nova/agents/briefing_agent.py`
- [Coach agent](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/coach_agent.py): `nova/agents/coach_agent.py`
- [Fast coach](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/fast_coach.py): `nova/agents/fast_coach.py`
- [Planning agent](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/planning_agent.py): `nova/agents/planning_agent.py`
- [Plan proposals](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/planner_propose.py): `nova/agents/planner_propose.py`
- [Task operator](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/operator_agent.py): `nova/agents/operator_agent.py`
- [Opportunity scout](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/scout_agent.py): `nova/agents/scout_agent.py`
- [Profile onboarding](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/profile_agent.py): `nova/agents/profile_agent.py`
- [Reflection](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/reflection_agent.py): `nova/agents/reflection_agent.py`
- [Pattern insights](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/pattern_agent.py): `nova/agents/pattern_agent.py`
- [Greeting](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/greeting_agent.py): `nova/agents/greeting_agent.py`
- [ADK tool wrappers](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/tools_adk.py): `nova/agents/tools_adk.py`
- [MCP agent tools](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/agents/mcp_backed.py): `nova/agents/mcp_backed.py`

### TaskFlow and memory

- [Nova capability layer](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/tools.py): `nova/mcp/tools.py`
- [TaskFlow reader](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_reader.py): `nova/mcp/taskflow_reader.py`
- [TaskFlow writer](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_writer.py): `nova/mcp/taskflow_writer.py`
- [Local memory](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/memory/store.py): `nova/memory/store.py`
- [Domain models](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/models.py): `nova/models.py`
- [TaskFlow data](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/taskflow_reader.py): `nova/mcp/taskflow_reader.py`

### MCP and integrations

- [Model configuration](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/config.py): `nova/config.py`
- [MCP server](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/server.py): `nova/mcp/server.py`
- [Opportunity Hunter](https://github.com/mohith535/nova-agentic-layer-over-taskflow/blob/main/nova/mcp/hunter_bridge.py): `nova/mcp/hunter_bridge.py`

### Other components

- **User**
- **Gemini**
- **TaskFlow user data**

## Connections

- User → Web console: uses console (evidence: `README.md`)
- User → CLI: runs commands (evidence: `README.md`)
- Web console → Nova capability layer: reads context (evidence: `nova/web/server.py`)
- Web console → Profile onboarding: runs onboarding (evidence: `nova/web/server.py`)
- Web console → Reflection: requests reflection (evidence: `nova/web/server.py`)
- Web console → Greeting: requests greeting (evidence: `nova/web/server.py`)
- Web console → Agent router: routes requests (evidence: `nova/web/server.py`)
- CLI → Agent router: builds agent (evidence: `nova/main.py`)
- CLI → MCP server: runs MCP (evidence: `nova/main.py`)
- Agent router → Briefing agent: transfers briefing (evidence: `nova/orchestrator.py`)
- Agent router → Coach agent: transfers coaching (evidence: `nova/orchestrator.py`)
- Agent router → Planning agent: transfers planning (evidence: `nova/orchestrator.py`)
- Agent router → Task operator: transfers task action (evidence: `nova/orchestrator.py`)
- Agent router → Opportunity scout: transfers scouting (evidence: `nova/orchestrator.py`)
- Briefing agent → ADK tool wrappers: uses tools (evidence: `nova/agents/briefing_agent.py`)
- Coach agent → ADK tool wrappers: uses tools (evidence: `nova/agents/coach_agent.py`)
- Planning agent → ADK tool wrappers: uses tools (evidence: `nova/agents/planning_agent.py`)
- Task operator → ADK tool wrappers: uses tools (evidence: `nova/agents/operator_agent.py`)
- Opportunity scout → ADK tool wrappers: uses tools (evidence: `nova/agents/scout_agent.py`)
- Web console → Fast coach: runs fast coaching (evidence: `nova/web/server.py`)
- Web console → Pattern insights: requests patterns (evidence: `nova/web/server.py`)
- Web console → Plan proposals: proposes plans (evidence: `nova/web/server.py`)
- Planning agent → Plan proposals: prepares proposals
- ADK tool wrappers → Nova capability layer: calls capabilities (evidence: `nova/agents/tools_adk.py`)
- Coach agent → MCP agent tools: uses MCP optionally (evidence: `nova/agents/coach_agent.py`)
- MCP agent tools → MCP server: spawns subprocess (evidence: `nova/agents/mcp_backed.py`)
- MCP server → Nova capability layer: wraps capabilities (evidence: `nova/mcp/server.py`)
- Nova capability layer → TaskFlow reader: reads task data (evidence: `nova/mcp/tools.py`)
- Nova capability layer → TaskFlow writer: writes task data (evidence: `nova/mcp/tools.py`)
- Nova capability layer → Local memory: recalls and stores (evidence: `nova/mcp/tools.py`)
- Nova capability layer → Domain models: uses domain models (evidence: `nova/mcp/tools.py`)
- TaskFlow reader → TaskFlow data: resolves local data (evidence: `nova/mcp/taskflow_reader.py`)
- TaskFlow writer → TaskFlow reader: uses task reader (evidence: `nova/mcp/taskflow_writer.py`)
- TaskFlow reader → TaskFlow user data: reads local board
- TaskFlow writer → TaskFlow user data: updates local board
- Nova capability layer → Opportunity Hunter: delegates hunter actions (evidence: `nova/mcp/tools.py`)
- Model configuration → Gemini: validates API key (evidence: `nova/config.py`)
- Briefing agent → Model configuration: selects model (evidence: `nova/agents/briefing_agent.py`)
- Coach agent → Model configuration: selects model (evidence: `nova/agents/coach_agent.py`)
- Planning agent → Model configuration: selects model (evidence: `nova/agents/planning_agent.py`)
