# kaiwenchen6627/corporate-event-agent architecture

> Architecture diagram of the GitHub repository kaiwenchen6627/corporate-event-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaiwenchen6627/corporate-event-agent
- Repository: https://github.com/kaiwenchen6627/corporate-event-agent

## Overview

This is a bounded corporate-event collaboration agent: customer messages create or update an opportunity, trigger requirement interpretation and gap analysis, retrieve knowledge, and lead either to a follow-up question or proposed solution options. Humans approve commercial terms and options, review staged replies before sending, and review knowledge before it can inform retrieval. Reflection and historical-thread import feed candidate principles or cases back into the knowledge base. The main workflow and store are evidenced in sampled source; several additional endpoint behaviors are documented in the README, so their wiring is shown only where supported.

Main entry points: [`agent.py`](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py) (Agent service), [`infrastructure/knowledge_store.py`](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py) (Knowledge store), [`ingestion/importer.py`](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/ingestion/importer.py) (Historical thread import), [`review/opportunities_browser.html`](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/review/opportunities_browser.html) (Opportunity browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Opportunity workflow"]
  node_agent["Agent service<br/>[agent.py]"]
  node_state["Opportunity state<br/>[agent.py]"]
  node_interpret["Message interpretation<br/>[agent.py]"]
  node_gapplan["Gap analysis and plan<br/>[agent.py]"]
  node_evidence["Evidence retrieval<br/>[agent.py]"]
  node_solution["Solution options<br/>[agent.py]"]
  node_reply["Staged reply<br/>[agent.py]"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_knowledge_store[("Knowledge store<br/>[knowledge_store.py]")]
  node_importer["Historical thread import<br/>[importer.py]"]
  node_cases[("Historical cases<br/>[knowledge_store.py]")]
  node_capabilities[("Capabilities<br/>[knowledge_store.py]")]
  node_principles[("Principles<br/>[knowledge_store.py]")]
end

subgraph group_human["Human review"]
  node_review_api["Knowledge review<br/>[agent.py]"]
  node_approval["Option and terms approval<br/>[agent.py]"]
  node_reflection["Human reflection<br/>[agent.py]"]
  node_reply_approval["Reply send approval<br/>[agent.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_opportunity_ui["Opportunity browser"]
  node_knowledge_ui["Knowledge browser"]
end

node_customer(("Customer"))
node_llm["LLM provider"]
node_reviewer(("Human reviewer"))

node_customer -->|"sends message"| node_agent
node_agent -->|"updates state"| node_state
node_agent -->|"interprets message"| node_interpret
node_interpret -.->|"interprets context"| node_llm
node_agent -->|"checks gaps"| node_gapplan
node_agent -->|"requests evidence"| node_evidence
node_evidence -->|"searches records"| node_knowledge_store
node_knowledge_store -->|"reads approved cases"| node_cases
node_knowledge_store -->|"reads approved capabilities"| node_capabilities
node_knowledge_store -->|"filters approved principles"| node_principles
node_agent -->|"builds options"| node_solution
node_agent -.->|"drafts customer text"| node_llm
node_agent -->|"stages draft"| node_reply
node_customer -->|"provides thread"| node_importer
node_importer -->|"extracts timeline and case"| node_llm
node_importer -->|"adds pending case"| node_knowledge_store
node_reviewer -->|"reviews records"| node_review_api
node_knowledge_ui -->|"submits review actions"| node_review_api
node_review_api -->|"approves or rejects"| node_knowledge_store
node_reviewer -->|"approves option or terms"| node_approval
node_approval -->|"records approval"| node_state
node_reviewer -->|"submits edits"| node_reflection
node_reflection -.->|"summarizes lessons"| node_llm
node_reflection -->|"appends lessons"| node_state
node_reflection -->|"adds pending principles"| node_knowledge_store
node_reviewer -->|"approves send"| node_reply_approval
node_reply_approval -->|"promotes reply"| node_state
node_opportunity_ui -->|"browses opportunities"| node_agent

click node_agent "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_state "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_interpret "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_gapplan "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_evidence "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_solution "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_reply "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_knowledge_store "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py"
click node_importer "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/ingestion/importer.py"
click node_cases "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py"
click node_capabilities "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py"
click node_principles "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py"
click node_review_api "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_approval "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_reflection "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_reply_approval "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py"
click node_opportunity_ui "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/review/opportunities_browser.html"
click node_knowledge_ui "https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/review/knowledge_browser.html"

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_agent,node_state,node_interpret,node_gapplan,node_evidence,node_solution,node_reply,node_reviewer toneBlue
class node_knowledge_store,node_importer,node_cases,node_capabilities,node_principles toneAmber
class node_review_api,node_approval,node_reflection,node_reply_approval toneMint
class node_opportunity_ui,node_knowledge_ui toneRose
class node_customer,node_llm toneIndigo
```

## Components

### Opportunity workflow

- [Agent service](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Opportunity state](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Message interpretation](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Gap analysis and plan](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Evidence retrieval](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Solution options](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Staged reply](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`

### Knowledge lifecycle

- [Knowledge store](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py): `infrastructure/knowledge_store.py`
- [Historical thread import](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/ingestion/importer.py): `ingestion/importer.py`
- [Historical cases](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py): `infrastructure/knowledge_store.py`
- [Capabilities](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py): `infrastructure/knowledge_store.py`
- [Principles](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/infrastructure/knowledge_store.py): `infrastructure/knowledge_store.py`

### Human review

- [Knowledge review](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Option and terms approval](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Human reflection](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`
- [Reply send approval](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/agent.py): `agent.py`

### User interfaces

- [Opportunity browser](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/review/opportunities_browser.html): `review/opportunities_browser.html`
- [Knowledge browser](https://github.com/kaiwenchen6627/corporate-event-agent/blob/main/review/knowledge_browser.html): `review/knowledge_browser.html`

### Other components

- **Customer**
- **LLM provider**
- **Human reviewer**

## Connections

- Customer → Agent service: sends message
- Agent service → Opportunity state: updates state
- Agent service → Message interpretation: interprets message
- Message interpretation → LLM provider: interprets context
- Agent service → Gap analysis and plan: checks gaps
- Agent service → Evidence retrieval: requests evidence
- Evidence retrieval → Knowledge store: searches records
- Knowledge store → Historical cases: reads approved cases
- Knowledge store → Capabilities: reads approved capabilities
- Knowledge store → Principles: filters approved principles
- Agent service → Solution options: builds options
- Agent service → LLM provider: drafts customer text
- Agent service → Staged reply: stages draft
- Customer → Historical thread import: provides thread
- Historical thread import → LLM provider: extracts timeline and case
- Historical thread import → Knowledge store: adds pending case
- Human reviewer → Knowledge review: reviews records
- Knowledge browser → Knowledge review: submits review actions
- Knowledge review → Knowledge store: approves or rejects
- Human reviewer → Option and terms approval: approves option or terms
- Option and terms approval → Opportunity state: records approval
- Human reviewer → Human reflection: submits edits
- Human reflection → LLM provider: summarizes lessons
- Human reflection → Opportunity state: appends lessons
- Human reflection → Knowledge store: adds pending principles
- Human reviewer → Reply send approval: approves send
- Reply send approval → Opportunity state: promotes reply
- Opportunity browser → Agent service: browses opportunities