diff --git a/docs/c1-chart.md b/docs/c1-chart.md new file mode 100644 index 0000000..b52f5ac --- /dev/null +++ b/docs/c1-chart.md @@ -0,0 +1,46 @@ +```mermaid +graph LR + subgraph Actors[" Actors "] + direction TB + SRE["SRE / DevOps\n[Person]"] + OnCall["On-Call Operator\n[Person · HITL]"] + end + + subgraph External[" External Systems "] + direction TB + Prom["Prometheus\nAlertManager\n[External Monitor]"] + Platforms["Chat Platforms\nSlack · MS Teams · Google Chat\n[Inbound Event Sources]"] + end + + subgraph Core[" Alert Routing Infrastructure [Software System] "] + Rail["Extension Tool · L0 Agent · Dapr\nDedup · Rate Limit · Route · Reply"] + end + + subgraph Downstream[" Downstream "] + direction TB + L1["L1 Agents\n[Specialist Automation · A2A JSON-RPC]"] + StateStore["Dapr State Store\nRedis 7\n[Fingerprints · Rate Counters]"] + Broker["Dapr Pub/Sub\nRabbitMQ\n[alerts-inbound · alerts-outbound]"] + end + + SRE -->|"configures alert rules"| Prom + Prom -->|"webhook · HTTPS"| Platforms + Platforms -->|"Event JSON · Sync · HTTPS"| Rail + Rail -->|"formatted reply · HTTPS"| Platforms + OnCall -->|"HITL approval"| Rail + Rail -->|"A2A JSON-RPC · HTTPS"| L1 + Rail <-->|"[State] get/set/expire · RESP3"| StateStore + Rail <-->|"[Pub/Sub] AMQP 0-9-1"| Broker + + classDef actor fill:#1a2a1a,stroke:#00E5A0,stroke-width:1.5px,color:#00E5A0 + classDef external fill:#1a1a2a,stroke:#00C9FF,stroke-width:1.5px,color:#00C9FF + classDef core fill:#0d2a1a,stroke:#00E5A0,stroke-width:2.5px,color:#00E5A0 + classDef infra fill:#2a1a00,stroke:#FF9900,stroke-width:1.5px,color:#FF9900 + classDef agents fill:#1e1a2a,stroke:#C084FC,stroke-width:1.5px,color:#C084FC + + class SRE,OnCall actor + class Prom,Platforms external + class Rail core + class StateStore,Broker infra + class L1 agents +``` diff --git a/docs/c2-chart.md b/docs/c2-chart.md new file mode 100644 index 0000000..a710c85 --- /dev/null +++ b/docs/c2-chart.md @@ -0,0 +1,83 @@ +```mermaid +graph LR + %% ── External Systems + Prom["Prometheus
AlertManager
[External Monitor]"] + Platforms["Chat Platforms
Slack · Teams · GChat
[Inbound Sources]"] + + %% ── System Boundary + subgraph Boundary["System Boundary — Alert Routing Infrastructure"] + direction TB + + %% Extension Tool + subgraph ET["Extension Tool"] + direction TB + + GW["Message Gateway
Platform Adapter"] + VP["Validation Pipeline
Schema · Dedup · Rate Limiter"] + DaprET["Dapr Sidecar
Pub: alerts-inbound · Sub: alerts-outbound
State: fingerprints · counters"] + + GW --> VP --> DaprET + end + + %% Dapr State Store + subgraph State["Dapr State Store · Redis 7"] + Redis[("Redis 7
Fingerprints · Rate Counters")] + end + + %% Dapr Pub/Sub Broker + subgraph MsgBroker["Dapr Pub/Sub · RabbitMQ"] + direction TB + CH1["alerts-inbound"] + CH2["alerts-outbound"] + end + + %% L0 Agent + subgraph L0["L0 Agent"] + direction TB + QM["Queue Manager
Alert Consumer · Payload Parser"] + A2A["A2A Server
auto → L1 dispatch
hitl → HITL approval"] + RH["Response Handler
Formatter · Router"] + DaprL0["Dapr Sidecar
Sub: alerts-inbound · Pub: alerts-outbound"] + + DaprL0 --> QM --> A2A --> RH --> DaprL0 + end + + PlatOut["Outbound Platform APIs
Slack Web API · Teams Graph API · GChat REST
[Block Kit · Adaptive Card · Card JSON]"] + end + + %% L1 Agents + L1["L1 Agents
[A2A JSON-RPC · HTTPS]"] + + %% ── Flows + Prom -->|"webhook · HTTPS"| Platforms + Platforms -->|"[Inbound] Event JSON · Sync"| GW + DaprET <-->|"[State] Redis RESP3 · get/set/expire"| Redis + DaprET -->|"[Pub/Sub] AMQP 0-9-1 publish · alerts-inbound"| CH1 + CH1 -->|"[Pub/Sub] AMQP 0-9-1 deliver · alerts-inbound"| DaprL0 + DaprL0 -.->|"[Pub/Sub] AMQP 0-9-1 publish · alerts-outbound"| CH2 + CH2 -.->|"[Pub/Sub] AMQP 0-9-1 deliver · alerts-outbound"| DaprET + DaprET -.->|"[Outbound] ResponsePayload · HTTP callback"| GW + GW -.->|"[Outbound] formatted reply"| PlatOut + A2A <-.->|"A2A JSON-RPC · HTTPS · Async"| L1 + + %% ── Styling + classDef external fill:#1a1a2a,stroke:#00C9FF,stroke-width:1.5px,color:#00C9FF + classDef gateway fill:#0d1a2a,stroke:#00C9FF,stroke-width:1px,color:#00C9FF + classDef validate fill:#1a0d2a,stroke:#7B61FF,stroke-width:1px,color:#7B61FF + classDef dapr fill:#1e0d2a,stroke:#7B61FF,stroke-width:1.5px,color:#C084FC + classDef broker fill:#2a1a00,stroke:#FF9900,stroke-width:1px,color:#FF9900 + classDef redis fill:#1a0d1a,stroke:#7B61FF,stroke-width:1.5px,color:#7B61FF + classDef l0core fill:#0d2a1a,stroke:#00E5A0,stroke-width:1px,color:#00E5A0 + classDef outbound fill:#2a0d14,stroke:#FF4D6D,stroke-width:1px,color:#FF4D6D + classDef agents fill:#1e1a2a,stroke:#C084FC,stroke-width:1.5px,color:#C084FC + + class Prom,Platforms external + class GW gateway + class VP validate + class DaprET,DaprL0 dapr + class CH1,CH2 broker + class Redis redis + class QM,A2A,RH l0core + class PlatOut outbound + class L1 agents +``` diff --git a/docs/c3-l0-agent.md b/docs/c3-l0-agent.md new file mode 100644 index 0000000..2dc39ff --- /dev/null +++ b/docs/c3-l0-agent.md @@ -0,0 +1,53 @@ +```mermaid +graph LR + subgraph L0[" L0 Agent — Component Detail "] + direction LR + + DaprL0["Dapr Sidecar\n[Sub: alerts-inbound\nPub: alerts-outbound]"] + + subgraph QM[" Queue Manager "] + direction TB + AC["Alert Consumer\n[Dapr /subscribe callback\n→ RawAlert]"] + PP["Payload Parser\n[Normalise · Enrich\nScore severity\n→ NormalisedAlert\n{routingHint: auto|hitl}]"] + AC --> PP + end + + subgraph Core[" Core "] + A2A["A2A Server\n[Central core · A2A JSON-RPC · HTTPS\nauto → dispatches to L1 Agents\nhitl → HITL operator approval\n→ AgentResponse · HumanResponse]"] + end + + subgraph RH[" Response Handler "] + direction TB + FM["Formatter\n[Slack → Block Kit\nTeams → Adaptive Card\nGChat → Card JSON]"] + RT["Router\n[Publishes to Dapr\n→ RoutedResponse]"] + FM --> RT + end + + DaprL0 -->|"RawAlert"| AC + PP -->|"NormalisedAlert"| A2A + A2A -.->|"AgentResponse / HumanResponse"| FM + RT -.->|"RoutedResponse"| DaprL0 + end + + InboundBroker["Dapr Pub/Sub\n[alerts-inbound]"] + OutboundBroker["Dapr Pub/Sub\n[alerts-outbound]"] + L1["L1 Agents\n[Specialist Automation]"] + + InboundBroker -->|"[Pub/Sub] AMQP 0-9-1 deliver · alerts-inbound"| DaprL0 + DaprL0 -.->|"[Pub/Sub] AMQP 0-9-1 publish · alerts-outbound"| OutboundBroker + A2A <-.->|"A2A JSON-RPC · HTTPS · Async"| L1 + + classDef dapr fill:#1e0d2a,stroke:#C084FC,stroke-width:2px,color:#C084FC + classDef queuemgr fill:#0d1a2a,stroke:#00C9FF,stroke-width:1.5px,color:#00C9FF + classDef a2a fill:#0d2a1a,stroke:#00E5A0,stroke-width:2.5px,color:#00E5A0 + classDef response fill:#2a0d14,stroke:#FF4D6D,stroke-width:1.5px,color:#FF4D6D + classDef broker fill:#2a1a00,stroke:#FF9900,stroke-width:1px,color:#FF9900 + classDef agents fill:#1e1a2a,stroke:#C084FC,stroke-width:1.5px,color:#C084FC + + class DaprL0 dapr + class AC,PP queuemgr + class A2A a2a + class FM,RT response + class InboundBroker,OutboundBroker broker + class L1 agents +``` diff --git a/docs/c3-message-gateway.md b/docs/c3-message-gateway.md new file mode 100644 index 0000000..e1782cb --- /dev/null +++ b/docs/c3-message-gateway.md @@ -0,0 +1,42 @@ +```mermaid +flowchart TB + subgraph Platforms + SL[Slack webhook] + TM[Teams webhook] + DC[Discord websocket] + end + + subgraph Adapters["Adapters — BaseAdapter: verify · normalize · monitor() · send()"] + + AD["SlackAdapter · TeamsAdapter · DiscordAdapter"] + end + + subgraph NL["Normalization layer"] + IM["InboundMessage
platform-agnostic canonical schema"] + end + + subgraph GW["Gateway — hub-and-spoke"] + SUP["_supervise()
auto-restart with backoff"] + DISP["_dispatch()
fan-out to handlers"] + ROUTE["send()
route OutboundMessage"] + HEALTH["health
per-platform status"] + end + + subgraph Core["Core / Dispatcher — main.py"] + DAPR["publish_to_dapr()
Dapr broker publish"] + REPLY["OutboundMessage
platform-agnostic reply"] + end + + SL --> AD + TM --> AD + DC --> AD + + AD --> IM + + IM --> SUP + SUP --> DISP + DISP --> DAPR + DAPR --> REPLY + REPLY --> ROUTE + ROUTE --> AD +``` diff --git a/helm-chart/values.yaml b/helm-chart/values.yaml index ce15451..d4b64a7 100644 --- a/helm-chart/values.yaml +++ b/helm-chart/values.yaml @@ -31,7 +31,7 @@ pinecone: agents: - name: l0 enabled: true - image: 01community/agent-l0:v1 + image: 01community/agent-l0:v1.1 containerPort: 3000 env: # Application settings