# iamtomshaw/project-manager-agent architecture

> Architecture diagram of the GitHub repository iamtomshaw/project-manager-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamtomshaw/project-manager-agent
- Repository: https://github.com/iamtomshaw/project-manager-agent

## Overview

##### Project type and purpose
- This is an AI-driven, agent-based task and meeting management MVP.
- It’s built as a small microservices/full-stack prototype:
– A FastAPI main service exposing REST and WebSocket endpoints (Chat Agent + webhook)
– A separate Task Manager Agent service (WebSocket microservice)
– A simple Streamlit frontend (frontend.py) for manual testing
– A MongoDB data store and optional Notion integration

##### File structure
Top-level files and dirs:
- main.py – FastAPI app entrypoint (mounts routes/chat.py, routes/meetings-webhook.py)
- routes/ – WebSocket and webhook endpoints
– chat.py: `/ws/chat` endpoint implementing the Chat Agent
– meetings-webhook.py: `/webhook` endpoint for meeting notifications
- lib/ – core libraries
– agent.py: orchestrates calls to tools, maintains agent logic
– ws_manager.py & task_manager.py: WebSocket client/server integrations
– tools.py: function tools exposed to the Chat Agent
– mongo.py: MongoDB helpers
– external.py: Notion or other external-service integrations
- frontend.py – Streamlit UI
- requirements.txt, .env.example – dependencies and environment config

##### README for additional insights
- Two cooperating agents: Chat Agent (interactive, WS) and Meeting→Project Agent (specialist, WS)
- Chat Agent calls tools in lib/tools.py for project/task operations or to forward messages to the Task Manager Agent
- Meeting webhook triggers the Meeting→Project Agent to assign transcripts to projects
- MongoDB is the primary data store, Notion is optional

##### Detail level
- Endpoint, tool call, and data store interaction
- Don’t over-aggregate: show lib/tools.py as the “Function Tools” component, lib/mongo.py as “MongoDB Adapter,” etc.
- Related files under their component for clarity

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Frontend["Streamlit UI"]:::client
        CustomClient["Custom WS/REST Client"]:::client
    end

    %% API Gateway / Orchestrator
    subgraph "API Gateway / Orchestrator"
        APIServer["FastAPI Orchestrator"]:::api
        subgraph "Routing"
            ChatEndpoint["/ws/chat WS Endpoint"]:::api
            WebhookEndpoint["/webhook REST Endpoint"]:::api
        end
        subgraph "Agent Logic"
            AgentCore["Chat Agent Logic"]:::agent
            Tools["Function Tools"]:::tool
            WSClientMgr["WebSocket Manager"]:::service
        end
        subgraph "Persistence"
            MongoAdapter["MongoDB Adapter"]:::db
        end
        subgraph "External Integrations"
            NotionExt["Notion Integration"]:::ext
        end
    end

    %% Task Manager Agent Service
    TaskManager["Task Manager Agent Service"]:::service

    %% Connections
    Frontend -->|"/ws/chat"| ChatEndpoint
    CustomClient -->|"REST/WS"| ChatEndpoint

    ChatEndpoint -->|"route to chat logic"| AgentCore
    AgentCore -->|"call tools"| Tools
    Tools -->|"create_project(), get_projects_list()"| MongoAdapter
    AgentCore -->|"query meetings"| MongoAdapter
    AgentCore -->|"communicate_with_task_manager()"| WSClientMgr
    WSClientMgr -->|"ws://localhost:8001"| TaskManager

    WebhookEndpoint ---|"trigger meeting agent"| TaskManager
    TaskManager -->|"update transcripts"| MongoAdapter

    AgentCore -->|"optional Notion sync"| NotionExt
    TaskManager -->|"optional Notion sync"| NotionExt

    %% Click Events
    click Frontend "https://github.com/iamtomshaw/project-manager-agent/blob/main/frontend.py"
    click APIServer "https://github.com/iamtomshaw/project-manager-agent/blob/main/main.py"
    click ChatEndpoint "https://github.com/iamtomshaw/project-manager-agent/blob/main/routes/chat.py"
    click WebhookEndpoint "https://github.com/iamtomshaw/project-manager-agent/blob/main/routes/meetings-webhook.py"
    click AgentCore "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/agent.py"
    click Tools "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/tools.py"
    click WSClientMgr "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/ws_manager.py"
    click MongoAdapter "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/mongo.py"
    click NotionExt "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/external.py"
    click TaskManager "https://github.com/iamtomshaw/project-manager-agent/blob/main/lib/task_manager.py"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000;
    classDef api fill:#90EE90,stroke:#000;
    classDef agent fill:#FFD700,stroke:#000;
    classDef service fill:#FFB6C1,stroke:#000;
    classDef db fill:#FFA500,stroke:#000;
    classDef ext fill:#D3D3D3,stroke:#000;
    classDef tool fill:#FFFACD,stroke:#000;
```
