Skip to content

Commit e7150e5

Browse files
badlydrawnrodbadlydrawnrod
committed
Add diagrams.
1 parent 7498bc9 commit e7150e5

3 files changed

Lines changed: 467 additions & 0 deletions

File tree

‎docs/class-diagram.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Agent C — Class Diagram (UML)
2+
3+
Protocols owned by Core, implemented by Backends, used by Adapters
4+
5+
```mermaid
6+
classDiagram
7+
%% Core Protocols (Interface Definitions)
8+
class AgentSessionProtocol {
9+
<<protocol>>
10+
+run(prompt, cancellation_event) AgentEventStream
11+
+history list[ModelMessage]
12+
+reset_history()
13+
}
14+
15+
class AgentEventStream {
16+
<<type>>
17+
AsyncGenerator[AgentEvent, ApprovalResponse | None]
18+
}
19+
20+
class AgentEvent {
21+
<<union>>
22+
AgentChunk | ToolCallInfo | ToolCallResultInfo | ApprovalRequest | AgentDone
23+
}
24+
25+
class SessionFactoryProtocol {
26+
<<protocol>>
27+
+create_session(config) AgentSessionProtocol
28+
}
29+
30+
%% Backend Implementations
31+
class AgentSession {
32+
-_agent Agent
33+
-_history list[ModelMessage]
34+
+run(prompt, event) AgentEventStream
35+
+reset_history()
36+
}
37+
38+
class GhAgentSession {
39+
-_session CopilotSession
40+
-_history list[Message]
41+
+run(prompt, event) AgentEventStream
42+
+reset_history()
43+
}
44+
45+
class PydanticAISessionFactory {
46+
+create_session(config) AgentSessionProtocol
47+
}
48+
49+
class GhCopilotSessionFactory {
50+
+create_session(config) AgentSessionProtocol
51+
}
52+
53+
%% Adapter Layer
54+
class TextualAgentAdapter {
55+
-_session AgentSessionProtocol
56+
-_prompt str
57+
+run() AsyncIterator[Message]
58+
-_handle_approval()
59+
}
60+
61+
class ConsoleAgentAdapter {
62+
-_session AgentSessionProtocol
63+
-_prompt str
64+
+run()
65+
}
66+
67+
%% UI Layer
68+
class TextualAgentApp {
69+
-_factory SessionFactoryProtocol
70+
+background_task(prompt)
71+
}
72+
73+
%% Relationships - Realization (implements)
74+
AgentSession ..|> AgentSessionProtocol : realizes
75+
GhAgentSession ..|> AgentSessionProtocol : realizes
76+
PydanticAISessionFactory ..|> SessionFactoryProtocol : realizes
77+
GhCopilotSessionFactory ..|> SessionFactoryProtocol : realizes
78+
79+
%% Relationships - Dependencies (uses)
80+
AgentSessionProtocol ..> AgentEventStream : returns
81+
AgentEventStream ..> AgentEvent : yields
82+
TextualAgentAdapter ..> AgentSessionProtocol : uses
83+
ConsoleAgentAdapter ..> AgentSessionProtocol : uses
84+
TextualAgentApp ..> SessionFactoryProtocol : uses
85+
TextualAgentApp ..> TextualAgentAdapter : creates
86+
87+
%% Styling
88+
style AgentSessionProtocol fill:#eef2ff,stroke:#6366f1,stroke-width:3px
89+
style AgentEventStream fill:#eef2ff,stroke:#6366f1,stroke-width:2px
90+
style AgentEvent fill:#eef2ff,stroke:#6366f1,stroke-width:2px
91+
style SessionFactoryProtocol fill:#eef2ff,stroke:#6366f1,stroke-width:2px
92+
93+
style AgentSession fill:#fff7ed,stroke:#f97316,stroke-width:2px
94+
style GhAgentSession fill:#fff7ed,stroke:#f97316,stroke-width:2px
95+
style PydanticAISessionFactory fill:#fff7ed,stroke:#f97316,stroke-width:2px
96+
style GhCopilotSessionFactory fill:#fff7ed,stroke:#f97316,stroke-width:2px
97+
98+
style TextualAgentAdapter fill:#fefce8,stroke:#eab308,stroke-width:2px
99+
style ConsoleAgentAdapter fill:#fefce8,stroke:#eab308,stroke-width:2px
100+
101+
style TextualAgentApp fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
102+
```
103+
104+
## Key Relationships
105+
106+
**Realization** (dotted line with hollow arrow `...|>`):
107+
- Backend classes IMPLEMENT the protocols defined by Core
108+
- `AgentSession` and `GhAgentSession` realize `AgentSessionProtocol`
109+
- Factory classes realize `SessionFactoryProtocol`
110+
111+
**Dependency** (dotted line with arrow `..>`):
112+
- Adapters and UI DEPEND ON protocols (use them via interfaces)
113+
- `TextualAgentAdapter` uses `AgentSessionProtocol` (doesn't care which implementation)
114+
- `TextualAgentApp` uses `SessionFactoryProtocol` to create sessions
115+
116+
**Core Principle**:
117+
- Core layer OWNS protocols (`AgentSessionProtocol`, `AgentEventStream`, `AgentEvent`)
118+
- Backends REALIZE protocols (provide concrete implementations)
119+
- Adapters/UI DEPEND on protocols (consume via abstract interfaces)
120+
- Dependencies point toward abstractions, not implementations

‎docs/layered-architecture.svg‎

Lines changed: 247 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)