# sathya-mithra-k/planner-agentic-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sathya-mithra-k/planner-agentic-ai
- Repository: https://github.com/sathya-mithra-k/planner-agentic-ai

## Overview

#### Purpose and Entry Points
This is a small planner-oriented agentic AI system with a Python backend and static browser frontend. The backend API entry point is `backend/api/main.py`; the browser entry point is `frontend/index.html`. The README provides no operational detail beyond the project name.

#### API Boundary
`backend/api/main.py` exposes the application-facing interface between clients and the agent workflow. It is the likely request orchestration boundary: frontend or other consumers submit planning prompts, and the API invokes backend coordination before returning a result.

#### Multi-Agent Coordination
`backend/Agents/coordinator.py` is the central control-flow component. It should own the end-to-end agent loop, selecting or sequencing specialist agents and consolidating their outputs. Agent modules are grouped under `backend/Agents/__init__.py`, separating workflow roles from API concerns.

#### Planning Stage
`backend/Agents/planner.py` defines the planning specialist. Its role is to transform an incoming objective and available context into a structured plan, proposed steps, or task decomposition. It is invoked through the coordinator rather than directly by the frontend.

#### Reflection / Revision Stage
`backend/Agents/reflection.py` represents a review stage after planning. It likely evaluates plan quality, identifies gaps or inconsistencies, and supplies feedback for revision. Together with the planner, it forms a generate–critique control loop managed by `backend/Agents/coordinator.py`.

#### LLM Integration Boundary
`backend/core/llm_engine.py` encapsulates language-model invocation. Agent implementations should depend on this module rather than embedding provider calls, making model selection, prompting, and response handling a core infrastructure boundary. External LLM provider details are not present in the repository tree or README.

#### State and Memory
`backend/core/memory.py` provides memory/state management for agent execution. It is the likely boundary for retaining conversation context, intermediate plans, reflection feedback, or prior results across workflow steps. The coordinator and agents should use it to avoid coupling state persistence to API handlers.

#### Client Surface and Runtime
The frontend is a lightweight static UI composed of `frontend/index.html` and `frontend/styles.css`; no frontend application framework is evident. The backend is Python, with dependencies declared in `requirements.txt`. The primary flow is: browser/client → `backend/api/main.py` → coordinator → planner/reflection agents → LLM engine and memory → consolidated API response.

Main entry points: [`backend/Agents/coordinator.py`](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/coordinator.py) (Coordinator), [`backend/Agents/planner.py`](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/planner.py) (Planner Agent), [`backend/Agents/reflection.py`](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/reflection.py) (Reflection Agent), [`backend/api/main.py`](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/api/main.py) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Static Frontend"]
  node_browser(("Browser Client"))
  node_index["Planner UI<br/>HTML entry point<br/>[index.html]"]
  node_styles["UI Styles<br/>CSS stylesheet<br/>[styles.css]"]
end

subgraph group_api["API Layer"]
  node_api_main["Backend API<br/>Python API entry point<br/>[main.py]"]
end

subgraph group_agents["Agent Workflow"]
  node_coordinator["Coordinator<br/>agent orchestrator<br/>[coordinator.py]"]
  node_agents_package["Agent Package<br/>workflow roles<br/>[__init__.py]"]
  node_planner["Planner Agent<br/>planning specialist<br/>[planner.py]"]
  node_reflection["Reflection Agent<br/>review specialist<br/>[reflection.py]"]
end

subgraph group_core["Core Services"]
  node_llm_engine{{"LLM Engine<br/>model integration<br/>[llm_engine.py]"}}
  node_memory[("Memory<br/>execution state<br/>[memory.py]")]
end

node_requirements["Python Dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_browser -->|"loads UI"| node_index
node_index -->|"uses"| node_styles
node_index -->|"submits planning prompt"| node_api_main
node_api_main -->|"invokes workflow"| node_coordinator
node_coordinator -->|"requests plan"| node_planner
node_planner -->|"proposed plan"| node_reflection
node_reflection -->|"review feedback"| node_coordinator
node_coordinator -.->|"revises plan"| node_planner
node_coordinator -->|"reads and writes context"| node_memory
node_planner -->|"generates plan"| node_llm_engine
node_reflection -->|"evaluates plan"| node_llm_engine
node_planner -->|"uses context"| node_memory
node_reflection -->|"uses plan state"| node_memory
node_coordinator -->|"consolidated result"| node_api_main
node_requirements -.->|"runtime dependencies"| node_api_main
node_agents_package -.->|"contains role"| node_coordinator
node_agents_package -.->|"contains role"| node_planner
node_agents_package -.->|"contains role"| node_reflection

click node_index "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/frontend/index.html"
click node_styles "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/frontend/styles.css"
click node_api_main "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/api/main.py"
click node_coordinator "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/coordinator.py"
click node_agents_package "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/__init__.py"
click node_planner "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/planner.py"
click node_reflection "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/reflection.py"
click node_llm_engine "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/core/llm_engine.py"
click node_memory "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/core/memory.py"
click node_requirements "https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/requirements.txt"

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_browser,node_index,node_styles toneBlue
class node_api_main toneAmber
class node_coordinator,node_agents_package,node_planner,node_reflection toneMint
class node_llm_engine,node_memory toneRose
class node_requirements toneNeutral
```

## Components

### Static Frontend

- **Browser Client**: client
- [Planner UI](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/frontend/index.html): HTML entry point · `frontend/index.html`
- [UI Styles](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/frontend/styles.css): CSS stylesheet · `frontend/styles.css`

### API Layer

- [Backend API](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/api/main.py): Python API entry point · Accepts planning prompts and returns workflow results. · `backend/api/main.py`

### Agent Workflow

- [Coordinator](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/coordinator.py): agent orchestrator · Runs the plan–review workflow and consolidates output. · `backend/Agents/coordinator.py`
- [Agent Package](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/__init__.py): workflow roles · `backend/Agents/__init__.py`
- [Planner Agent](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/planner.py): planning specialist · Turns objectives and context into structured plans. · `backend/Agents/planner.py`
- [Reflection Agent](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/Agents/reflection.py): review specialist · Critiques plans and supplies revision feedback. · `backend/Agents/reflection.py`

### Core Services

- [LLM Engine](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/core/llm_engine.py): model integration · Centralizes model invocation, prompting, and response handling. · `backend/core/llm_engine.py`
- [Memory](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/backend/core/memory.py): execution state · Stores workflow context, intermediate plans, and feedback. · `backend/core/memory.py`

### Other components

- [Python Dependencies](https://github.com/sathya-mithra-k/planner-agentic-ai/blob/main/requirements.txt): dependency manifest · `requirements.txt`

## Connections

- Browser Client → Planner UI: loads UI
- Planner UI → UI Styles: uses
- Planner UI → Backend API: submits planning prompt
- Backend API → Coordinator: invokes workflow
- Coordinator → Planner Agent: requests plan
- Planner Agent → Reflection Agent: proposed plan
- Reflection Agent → Coordinator: review feedback
- Coordinator → Planner Agent: revises plan
- Coordinator → Memory: reads and writes context
- Planner Agent → LLM Engine: generates plan
- Reflection Agent → LLM Engine: evaluates plan
- Planner Agent → Memory: uses context
- Reflection Agent → Memory: uses plan state
- Coordinator → Backend API: consolidated result
- Python Dependencies → Backend API: runtime dependencies
- Agent Package → Coordinator: contains role
- Agent Package → Planner Agent: contains role
- Agent Package → Reflection Agent: contains role