Skip to content

Commit 08b1149

Browse files
baeyc0510baeyc0510
committed
docs: add class, sequence, usecase uml (plant uml)
1 parent 49e42d5 commit 08b1149

3 files changed

Lines changed: 297 additions & 0 deletions

File tree

‎docs/diagrams/class.puml‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
@startuml Symphony Class Diagram
2+
' Symphony CLI - Core Architecture
3+
' Design Patterns: Registry, Plugin, Strategy, Dual Schema
4+
5+
skinparam classAttributeIconSize 0
6+
skinparam linetype ortho
7+
8+
package "Schema (Dual Schema Pattern)" {
9+
class UserPolicy <<A Schema>> {
10+
+Version: string
11+
+RBAC: UserRBAC
12+
+Rules: []UserRule
13+
--
14+
Natural language rules
15+
for human authoring
16+
}
17+
18+
class CodePolicy <<B Schema>> {
19+
+Version: string
20+
+RBAC: PolicyRBAC
21+
+Rules: []PolicyRule
22+
+Enforce: EnforceSettings
23+
--
24+
Formal rules for
25+
machine execution
26+
}
27+
28+
class PolicyRule {
29+
+ID: string
30+
+Selector: Selector
31+
+Engine: string
32+
+Check: map
33+
}
34+
35+
class Selector {
36+
+Languages: []string
37+
+Include: []string
38+
+Exclude: []string
39+
+Roles: []string
40+
}
41+
42+
UserPolicy ..> CodePolicy : "LLM converts"
43+
CodePolicy *-- PolicyRule
44+
PolicyRule *-- Selector
45+
}
46+
47+
package "Linter (Plugin Pattern)" {
48+
interface Linter <<interface>> {
49+
+Name(): string
50+
+GetCapabilities(): Capabilities
51+
+CheckAvailability(ctx): error
52+
+Execute(ctx, config, files): ToolOutput
53+
+ParseOutput(output): []Violation
54+
}
55+
56+
interface Converter <<interface>> {
57+
+Name(): string
58+
+GetLLMDescription(): string
59+
+GetRoutingHints(): []string
60+
+ConvertSingleRule(ctx, rule): SingleRuleResult
61+
+BuildConfig(results): LinterConfig
62+
}
63+
64+
class Registry <<singleton>> {
65+
-tools: map[string]ToolEntry
66+
+RegisterTool(linter, converter, configFile)
67+
+GetAllTools(): []ToolEntry
68+
+GetByName(name): ToolEntry
69+
}
70+
71+
class ESLint implements Linter
72+
class Prettier implements Linter
73+
class TSC implements Linter
74+
class PyLint implements Linter
75+
76+
Registry o-- Linter : registers
77+
Registry o-- Converter : registers
78+
}
79+
80+
package "LLM Provider (Strategy Pattern)" {
81+
interface Provider <<interface>> {
82+
+Name(): string
83+
+Execute(ctx, prompt, format): string
84+
}
85+
86+
class ClaudeCode implements Provider
87+
class GeminiCLI implements Provider
88+
class OpenAIAPI implements Provider
89+
}
90+
91+
package "Validator (Execution Unit Pattern)" {
92+
class Validator {
93+
+ValidateChanges(changes): ValidationResult
94+
-createExecutionUnits(): []ExecutionUnit
95+
-executeInParallel(units): []Violation
96+
}
97+
98+
interface ExecutionUnit <<interface>> {
99+
+Execute(ctx): []Violation
100+
+GetRuleIDs(): []string
101+
+GetEngineName(): string
102+
+GetFiles(): []string
103+
}
104+
105+
class LinterExecutionUnit implements ExecutionUnit {
106+
Batch: all files, all rules
107+
Single linter invocation
108+
}
109+
110+
class LLMExecutionUnit implements ExecutionUnit {
111+
Granular: one file, one rule
112+
Parallel LLM calls
113+
}
114+
115+
Validator --> ExecutionUnit : creates
116+
LinterExecutionUnit --> Linter : uses
117+
LLMExecutionUnit --> Provider : uses
118+
}
119+
120+
package "MCP Server" {
121+
class MCPServer {
122+
+query_conventions(category, languages): string
123+
+validate_code(role): ValidationResult
124+
}
125+
126+
MCPServer --> Validator : delegates
127+
MCPServer --> UserPolicy : reads
128+
}
129+
130+
package "RBAC" {
131+
class RBACChecker {
132+
+CheckPermission(role, file): bool
133+
+GetDeniedFiles(role, files): []string
134+
}
135+
136+
Validator --> RBACChecker : "first check"
137+
}
138+
139+
' Key relationships
140+
Validator --> CodePolicy : validates against
141+
Converter ..> Provider : "uses for conversion"
142+
143+
note bottom of Registry
144+
Self-registration via init()
145+
in each linter package
146+
end note
147+
148+
note bottom of ExecutionUnit
149+
Linters: Batched for efficiency
150+
LLM: Granular for parallelism
151+
end note
152+
153+
@enduml

‎docs/diagrams/sequence.puml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
@startuml Symphony Validation Sequence
2+
' Symphony CLI - Code Validation Workflow
3+
' Shows the core validation pipeline
4+
5+
skinparam sequenceMessageAlign center
6+
skinparam responseMessageBelowArrow true
7+
8+
actor "AI IDE" as client
9+
participant "MCP Server" as mcp
10+
participant "Validator" as validator
11+
participant "RBAC\nChecker" as rbac
12+
participant "Git" as git
13+
participant "Linter\nExecutionUnit" as linter_unit
14+
participant "LLM\nExecutionUnit" as llm_unit
15+
participant "Linter\n(ESLint, etc.)" as linter
16+
participant "LLM\nProvider" as llm
17+
18+
== MCP validate_code Request ==
19+
20+
client -> mcp: validate_code(role)
21+
activate mcp
22+
23+
mcp -> git: GetChanges()
24+
git --> mcp: []Change (staged + unstaged)
25+
26+
mcp -> validator: ValidateChanges(changes)
27+
activate validator
28+
29+
== Phase 1: RBAC Check ==
30+
31+
validator -> rbac: CheckPermissions(role, files)
32+
rbac --> validator: deniedFiles[]
33+
34+
alt has denied files
35+
validator --> validator: Create RBAC violations
36+
end
37+
38+
== Phase 2: Group Rules by Engine ==
39+
40+
validator -> validator: Group rules by engine type
41+
note right
42+
Linter rules → batch
43+
LLM rules → granular
44+
end note
45+
46+
== Phase 3: Create Execution Units ==
47+
48+
validator -> linter_unit **: create(linter, allFiles, allRules)
49+
validator -> llm_unit **: create(file, rule) for each pair
50+
51+
== Phase 4: Parallel Execution ==
52+
53+
par Concurrent execution (CPU/2 limit)
54+
validator -> linter_unit: Execute()
55+
activate linter_unit
56+
linter_unit -> linter: Execute(config, files)
57+
linter --> linter_unit: raw output
58+
linter_unit -> linter_unit: ParseOutput()
59+
linter_unit --> validator: []Violation
60+
deactivate linter_unit
61+
else
62+
validator -> llm_unit: Execute()
63+
activate llm_unit
64+
llm_unit -> llm: Execute(prompt)
65+
llm --> llm_unit: analysis result
66+
llm_unit --> validator: []Violation
67+
deactivate llm_unit
68+
end
69+
70+
== Phase 5: Aggregate Results ==
71+
72+
validator -> validator: Merge all violations
73+
validator --> mcp: ValidationResult
74+
deactivate validator
75+
76+
mcp --> client: {status, violations[]}
77+
deactivate mcp
78+
79+
note over client, llm
80+
Design Philosophy:
81+
- RBAC enforced first
82+
- Linters batched for efficiency
83+
- LLM calls parallelized for throughput
84+
- Graceful fallback: linter → LLM
85+
end note
86+
87+
@enduml

‎docs/diagrams/usecase.puml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
@startuml Symphony Use Case Diagram
2+
' Symphony CLI - LLM-Friendly Convention Linter
3+
' Core Use Cases
4+
5+
skinparam actorStyle awesome
6+
skinparam packageStyle rectangle
7+
8+
left to right direction
9+
10+
actor "Developer" as dev
11+
actor "AI IDE\n(MCP Client)" as ai
12+
13+
rectangle Symphony {
14+
' Project Setup
15+
usecase "Initialize Project\n(sym init)" as UC_INIT
16+
17+
' Policy Management
18+
usecase "Define Conventions\n(Natural Language)" as UC_DEFINE
19+
usecase "Convert Policy\n(A→B Schema)" as UC_CONVERT
20+
21+
' Validation
22+
usecase "Validate Code\n(sym validate)" as UC_VALIDATE
23+
24+
' MCP Integration
25+
usecase "Query Conventions\n(MCP Tool)" as UC_QUERY
26+
usecase "Validate Changes\n(MCP Tool)" as UC_MCP_VALIDATE
27+
28+
' RBAC
29+
usecase "Check Permissions\n(RBAC)" as UC_RBAC
30+
}
31+
32+
' Developer interactions
33+
dev --> UC_INIT
34+
dev --> UC_DEFINE
35+
dev --> UC_VALIDATE
36+
37+
' AI IDE interactions (MCP protocol)
38+
ai --> UC_QUERY : "query_conventions"
39+
ai --> UC_MCP_VALIDATE : "validate_code"
40+
41+
' Internal relationships
42+
UC_DEFINE ..> UC_CONVERT : <<include>>
43+
UC_VALIDATE ..> UC_RBAC : <<include>>
44+
UC_MCP_VALIDATE ..> UC_VALIDATE : <<include>>
45+
UC_CONVERT ..> UC_QUERY : "enables"
46+
47+
note right of UC_CONVERT
48+
LLM transforms natural language
49+
rules into linter-specific configs
50+
end note
51+
52+
note bottom of UC_RBAC
53+
Role-based file access control
54+
enforced before validation
55+
end note
56+
57+
@enduml

0 commit comments

Comments
 (0)