Directory Structure
Relevant source files
The following files were used as context for generating this wiki page:
OpenPoke is organized into a clear multi-agent orchestration stack divided into a FastAPI backend and a Next.js frontend. The project structure separates concerns between user interaction (Poke), task execution (Execution Engines), and shared services like conversation logging and external integrations via Composio.
Sources: README.md:6-12
Core Repository Layout
The repository follows a standard full-stack split with dedicated directories for the backend server, the web frontend, and local runtime data.
| Directory | Primary Purpose | Key Technologies |
|---|---|---|
server/ | FastAPI application, multi-agent logic, and services | Python, FastAPI, OpenRouter |
web/ | User interface and frontend proxy logic | Next.js, React, Tailwind CSS |
server/data/ | Persistent runtime data (logs, summaries) | Plain text logs, JSON |
Sources: README.md:67-69, web/package.json:11-15
High-Level Component Flow
The following diagram illustrates how the major directories interact during a user request:
Backend Architecture (server/)
The server/ directory contains the logic for the dual-agent system. It is structured into agents and services to maintain modularity.
Agents (server/agents/)
OpenPoke utilizes a "Interaction/Execution" split. The interaction_agent (Poke) handles the user-facing dialogue and personality, while the execution_agent performs technical tasks.
interaction_agent/: Containsruntime.pyfor managing LLM interaction loops and tool-calling orchestration. It utilizessystem_prompt.mdto define the persona (Poke).execution_agent/: Containsruntime.pyand specific task subdirectories (e.g.,tasks/search_email/). It executes tool calls directly and reports back to the interaction agent.
Sources: server/agents/interaction_agent/runtime.py:25, server/agents/execution_agent/runtime.py:27, server/agents/interaction_agent/system_prompt.md:1-10
Services (server/services/)
The services directory provides shared infrastructure used by both agents.
conversation/: Managespoke_conversation.log. It includes asummarization/submodule responsible for maintaining the "working memory" of the assistant.gmail/: Handles interactions with the Gmail API via Composio, includingimportance_classifier.pyfor proactive notifications.
Sources: server/services/conversation/log.py:21-23, server/services/conversation/summarization/working_memory_log.py:19-21, server/services/gmail/importance_classifier.py:1-5
Data Persistence (server/data/)
The system stores runtime state in a data/ directory, which is ignored by version control to ensure user privacy.
| File Path | Description | Format |
|---|---|---|
data/conversation/poke_conversation.log | Raw append-only transcript of all user and agent turns. | XML-tagged Text |
data/conversation/poke_working_memory.log | Summarized state and "unsummarized" recent context. | XML-tagged Text + JSON |
Sources: server/services/conversation/log.py:23, server/services/conversation/summarization/working_memory_log.py:21
Data Flow Diagram
The following sequence shows how data is moved between files during a conversation:
Frontend Structure (web/)
The web/ directory is a standard Next.js 14 application using the App Router.
app/: Contains the main page logic (page.tsx) and global styles (globals.css,layout.tsx).components/: Modular UI elements likeSettingsModal.tsx(for API keys and Gmail Oauth) and thechat/UI components.package.json: Defines dependencies includingnext,react, andtailwindcss.
Sources: web/package.json:1-25, web/app/page.tsx:32-40, web/components/SettingsModal.tsx:103-115
Summary
The OpenPoke directory structure is designed to isolate the high-level LLM orchestration (interaction_agent) from the low-level tool execution (execution_agent). This separation is supported by a robust services layer for data persistence in server/data and a responsive frontend in web/ that interacts with the backend through a unified API proxy.
Sources: README.md:67-69, server/agents/interaction_agent/runtime.py:171-176