# pathwiseee/pathwiseagenticassistant architecture

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

- Interactive diagram: https://gitdiagram.com/pathwiseee/pathwiseagenticassistant
- Repository: https://github.com/pathwiseee/pathwiseagenticassistant

## Overview

Pathwise is a learning assistant that turns a learner’s technology-learning request into a researched, reviewed, interactive lesson, then answers follow-up questions grounded in that lesson. The principal flow runs through chat intake, research, lesson compilation, and persistence; tutoring is the follow-up branch. The graph also shows the web research and lesson-review stages, safety gates, and the Gradio presentation layer. Evidence is limited to the supplied excerpts and SOURCE INDEX; unsampled UI wiring and other unshown connections are omitted or marked unverified.

Main entry points: [`src/pathwiseagenticassistant/agents/research/research_manager.py`](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/research_manager.py) (Research manager), [`src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/pathwiseWorkflow.py) (Lesson workflow), [`src/pathwiseagenticassistant/ui/app.py`](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/app.py) (Gradio app), [`src/pathwiseagenticassistant/chat/chat_service.py`](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/chat/chat_service.py) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_ui["Gradio app<br/>[app.py]"]
  node_chat["Chat service<br/>[chat_service.py]"]
  node_intake["Request intake<br/>[intake_agent.py]"]
  node_tutor["Lesson tutor<br/>[tutor_agent.py]"]
  node_help["Help agent<br/>[help_agent.py]"]
  node_renderer["Lesson renderer<br/>[renderer.py]"]
  node_uiwidgets["UI components<br/>[components.py]"]
end

subgraph group_research["Research"]
  node_research_manager["Research manager"]
  node_topic_planner["Topic planning"]
  node_web_search["Web search"]
  node_relevance["Relevance judging<br/>[relevance_judge.py]"]
  node_summarizer["Source summaries<br/>[summarizer.py]"]
  node_research_critic["Gap analysis<br/>[critic_agent.py]"]
end

subgraph group_lesson["Lesson compilation"]
  node_workflow["Lesson workflow"]
  node_compiler["Compilation orchestrator"]
  node_planner["Lesson planning"]
  node_reviewer["Plan review"]
  node_writer["Lesson writing"]
  node_verifier["Page verification"]
  node_lesson_tree["Lesson structure<br/>[ui_component.py]"]
end

subgraph group_platform["Shared services"]
  node_link_check["Link verification<br/>[link_verifier.py]"]
  node_guardrails["Safety guardrails<br/>[guardrails.py]"]
  node_storage[("Chat and lesson store<br/>[db.py]")]
  node_schemas["Domain schemas<br/>[schemas.py]"]
end

node_learner(("Learner"))

node_learner -.->|"uses"| node_ui
node_ui -.->|"dispatches messages"| node_chat
node_ui -->|"renders lessons"| node_renderer
node_ui -.->|"requests help"| node_help
node_ui -->|"loads and saves"| node_storage
node_chat -->|"classifies requests"| node_intake
node_chat -->|"answers follow-ups"| node_tutor
node_chat -->|"starts lesson workflow"| node_workflow
node_chat -->|"reads and attaches"| node_storage
node_intake -->|"checks input"| node_guardrails
node_tutor -->|"checks answers"| node_guardrails
node_workflow -->|"requests research"| node_research_manager
node_workflow -->|"streams compilation"| node_compiler
node_workflow -->|"provides search agent"| node_web_search
node_workflow -->|"provides summarizer"| node_summarizer
node_research_manager -->|"plans queries"| node_topic_planner
node_research_manager -->|"searches queries"| node_web_search
node_research_manager -->|"filters articles"| node_relevance
node_research_manager -->|"summarizes sources"| node_summarizer
node_research_manager -->|"finds topic gaps"| node_research_critic
node_compiler -->|"drafts plan"| node_planner
node_compiler -->|"reviews plan"| node_reviewer
node_compiler -->|"writes lesson"| node_writer
node_compiler -->|"verifies page"| node_verifier
node_reviewer -->|"verifies links"| node_link_check
node_writer -->|"builds components"| node_lesson_tree
node_verifier -->|"checks structure"| node_lesson_tree
node_renderer -->|"uses components"| node_uiwidgets
node_renderer -.->|"starts lesson creation"| node_workflow

click node_ui "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/app.py"
click node_chat "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/chat/chat_service.py"
click node_intake "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/intake_agent.py"
click node_tutor "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/tutor_agent.py"
click node_help "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/help_agent.py"
click node_renderer "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/renderer.py"
click node_uiwidgets "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/components.py"
click node_workflow "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/pathwiseWorkflow.py"
click node_research_manager "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/research_manager.py"
click node_topic_planner "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/topic_planning_agent.py"
click node_web_search "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/web_search_agent.py"
click node_relevance "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/relevance_judge.py"
click node_summarizer "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/summarizer.py"
click node_research_critic "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/critic_agent.py"
click node_compiler "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py"
click node_planner "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_planning_agent.py"
click node_reviewer "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_reviewer_agent.py"
click node_writer "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_writing_agent.py"
click node_verifier "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/page_verifier_agent.py"
click node_lesson_tree "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/ui_component.py"
click node_link_check "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/link_verifier.py"
click node_guardrails "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/guardrails.py"
click node_storage "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/storage/db.py"
click node_schemas "https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/schemas.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,node_chat,node_intake,node_tutor,node_help,node_renderer,node_uiwidgets toneBlue
class node_research_manager,node_topic_planner,node_web_search,node_relevance,node_summarizer,node_research_critic toneAmber
class node_workflow,node_compiler,node_planner,node_reviewer,node_writer,node_verifier,node_lesson_tree toneMint
class node_link_check,node_guardrails,node_storage,node_schemas toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [Gradio app](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/app.py): `src/pathwiseagenticassistant/ui/app.py`
- [Chat service](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/chat/chat_service.py): `src/pathwiseagenticassistant/chat/chat_service.py`
- [Request intake](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/intake_agent.py): `src/pathwiseagenticassistant/agents/front_door/intake_agent.py`
- [Lesson tutor](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/tutor_agent.py): `src/pathwiseagenticassistant/agents/front_door/tutor_agent.py`
- [Help agent](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/front_door/help_agent.py): `src/pathwiseagenticassistant/agents/front_door/help_agent.py`
- [Lesson renderer](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/renderer.py): `src/pathwiseagenticassistant/ui/renderer.py`
- [UI components](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/ui/components.py): `src/pathwiseagenticassistant/ui/components.py`

### Research

- [Research manager](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/research_manager.py): `src/pathwiseagenticassistant/agents/research/research_manager.py`
- [Topic planning](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/topic_planning_agent.py): `src/pathwiseagenticassistant/agents/research/topic_planning_agent.py`
- [Web search](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/web_search_agent.py): `src/pathwiseagenticassistant/tools/web_search_agent.py`
- [Relevance judging](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/relevance_judge.py): `src/pathwiseagenticassistant/agents/research/relevance_judge.py`
- [Source summaries](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/summarizer.py): `src/pathwiseagenticassistant/tools/summarizer.py`
- [Gap analysis](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/research/critic_agent.py): `src/pathwiseagenticassistant/agents/research/critic_agent.py`

### Lesson compilation

- [Lesson workflow](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/pathwiseWorkflow.py): `src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`
- [Compilation orchestrator](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py): `src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py`
- [Lesson planning](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_planning_agent.py): `src/pathwiseagenticassistant/agents/compilation/lesson_planning_agent.py`
- [Plan review](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_reviewer_agent.py): `src/pathwiseagenticassistant/agents/compilation/lesson_reviewer_agent.py`
- [Lesson writing](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/lesson_writing_agent.py): `src/pathwiseagenticassistant/agents/compilation/lesson_writing_agent.py`
- [Page verification](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/page_verifier_agent.py): `src/pathwiseagenticassistant/agents/compilation/page_verifier_agent.py`
- [Lesson structure](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/agents/compilation/ui_component.py): `src/pathwiseagenticassistant/agents/compilation/ui_component.py`

### Shared services

- [Link verification](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/tools/link_verifier.py): `src/pathwiseagenticassistant/tools/link_verifier.py`
- [Safety guardrails](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/guardrails.py): `src/pathwiseagenticassistant/guardrails.py`
- [Chat and lesson store](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/storage/db.py): `src/pathwiseagenticassistant/storage/db.py`
- [Domain schemas](https://github.com/pathwiseee/pathwiseagenticassistant/blob/main/src/pathwiseagenticassistant/schemas.py): `src/pathwiseagenticassistant/schemas.py`

### Other components

- **Learner**

## Connections

- Learner → Gradio app: uses
- Gradio app → Chat service: dispatches messages (evidence: `src/pathwiseagenticassistant/ui/app.py`)
- Gradio app → Lesson renderer: renders lessons (evidence: `src/pathwiseagenticassistant/ui/app.py`)
- Gradio app → Help agent: requests help (evidence: `src/pathwiseagenticassistant/ui/app.py`)
- Gradio app → Chat and lesson store: loads and saves (evidence: `src/pathwiseagenticassistant/ui/app.py`)
- Chat service → Request intake: classifies requests (evidence: `src/pathwiseagenticassistant/chat/chat_service.py`)
- Chat service → Lesson tutor: answers follow-ups (evidence: `src/pathwiseagenticassistant/chat/chat_service.py`)
- Chat service → Lesson workflow: starts lesson workflow (evidence: `src/pathwiseagenticassistant/chat/chat_service.py`)
- Chat service → Chat and lesson store: reads and attaches (evidence: `src/pathwiseagenticassistant/chat/chat_service.py`)
- Request intake → Safety guardrails: checks input (evidence: `src/pathwiseagenticassistant/agents/front_door/intake_agent.py`)
- Lesson tutor → Safety guardrails: checks answers (evidence: `src/pathwiseagenticassistant/agents/front_door/tutor_agent.py`)
- Lesson workflow → Research manager: requests research (evidence: `src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`)
- Lesson workflow → Compilation orchestrator: streams compilation (evidence: `src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`)
- Lesson workflow → Web search: provides search agent (evidence: `src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`)
- Lesson workflow → Source summaries: provides summarizer (evidence: `src/pathwiseagenticassistant/agents/pathwiseWorkflow.py`)
- Research manager → Topic planning: plans queries (evidence: `src/pathwiseagenticassistant/agents/research/research_manager.py`)
- Research manager → Web search: searches queries (evidence: `src/pathwiseagenticassistant/agents/research/research_manager.py`)
- Research manager → Relevance judging: filters articles (evidence: `src/pathwiseagenticassistant/agents/research/research_manager.py`)
- Research manager → Source summaries: summarizes sources (evidence: `src/pathwiseagenticassistant/agents/research/research_manager.py`)
- Research manager → Gap analysis: finds topic gaps (evidence: `src/pathwiseagenticassistant/agents/research/research_manager.py`)
- Compilation orchestrator → Lesson planning: drafts plan (evidence: `src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py`)
- Compilation orchestrator → Plan review: reviews plan (evidence: `src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py`)
- Compilation orchestrator → Lesson writing: writes lesson (evidence: `src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py`)
- Compilation orchestrator → Page verification: verifies page (evidence: `src/pathwiseagenticassistant/agents/compilation/compilation_orchestrator.py`)
- Plan review → Link verification: verifies links (evidence: `src/pathwiseagenticassistant/agents/compilation/lesson_reviewer_agent.py`)
- Lesson writing → Lesson structure: builds components (evidence: `src/pathwiseagenticassistant/agents/compilation/lesson_writing_agent.py`)
- Page verification → Lesson structure: checks structure (evidence: `src/pathwiseagenticassistant/agents/compilation/page_verifier_agent.py`)
- Lesson renderer → UI components: uses components (evidence: `src/pathwiseagenticassistant/ui/renderer.py`)
- Lesson renderer → Lesson workflow: starts lesson creation (evidence: `src/pathwiseagenticassistant/ui/renderer.py`)