Cursor rule

1---
2description: Comprehensive architectural standards and design principles following SOLID principles, Clean Architecture, and DRY practices for building maintainable, scalable software
3globs:
4alwaysApply: true
5---
6# Architecture & Design Principles
7# Architecture & Design Principles
8 
9<goal>
10Establish comprehensive architectural standards and design principles for building maintainable, scalable, and robust software following industry best practices adapted to the project's domain-driven structure.
11</goal>
12 
13## Core Architectural Principles
14 
15### SOLID Principles
16 
17<principle type="solid_srp">
18**Single Responsibility Principle (SRP):**
19- Each module, class, or function should have only one reason to change
20- Separate business logic, data access, and presentation concerns
21- Use domain-specific packages: `engine/{agent,task,tool,workflow,runtime,infra}/`
22- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
23</principle>
24 
25<principle type="solid_ocp">
26**Open/Closed Principle (OCP):**
27- Open for extension, closed for modification
28- Use interfaces and composition over inheritance
29- Leverage factory patterns for extensible behavior
30- *Factory pattern implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
31</principle>
32 
33<principle type="solid_lsp">
34**Liskov Substitution Principle (LSP):**
35- Subtypes must be substitutable for their base types
36- Interface implementations must honor contracts
37- Ensure interface methods behave consistently
38- *Interface design patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
39</principle>
40 
41<principle type="solid_isp">
42**Interface Segregation Principle (ISP):**
43- Clients should not depend on interfaces they don't use
44- Create small, focused interfaces
45- Use interface composition for complex behavior
46- *Interface composition examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
47</principle>
48 
49<principle type="solid_dip">
50**Dependency Inversion Principle (DIP):**
51- Depend on abstractions, not concretions
52- Use dependency injection through constructors
53- High-level modules should not depend on low-level modules
54- *Constructor patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
55</principle>
56 
57### DRY Principle (Don't Repeat Yourself)
58 
59<dry_strategies type="code_reuse">
60**Code Reuse Strategies:**
61- Extract common functionality into shared packages
62- Use generic functions for similar operations
63- Create utility packages for cross-cutting concerns
64 
65```go
66// ✅ Good: Reusable validation utility
67func ValidateRequired(value string, fieldName string) error {
68    if strings.TrimSpace(value) == "" {
69        return fmt.Errorf("%s is required", fieldName)
70    }
71    return nil
72}
73 
74// Usage across multiple validators
75func (v *UserValidator) ValidateName(name string) error {
76    return ValidateRequired(name, "name")
77}
78 
79func (v *TaskValidator) ValidateTitle(title string) error {
80    return ValidateRequired(title, "title")
81}
82```
83</dry_strategies>
84 
85<dry_strategies type="configuration_patterns">
86**Configuration Patterns:**
87- Centralize configuration with defaults
88- Use template engine for dynamic configurations
89- Avoid duplicating configuration logic
90- *Configuration implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
91</dry_strategies>
92 
93### Clean Architecture
94 
95<architecture_structure type="domain_driven">
96**Domain-Driven Design Structure:**
97```
98engine/
99├── agent/     # Agent domain logic
100├── task/      # Task execution domain
101├── tool/      # Tool management domain
102├── workflow/  # Workflow orchestration domain
103├── runtime/   # Runtime execution environment
104├── infra/     # Infrastructure concerns
105└── core/      # Shared domain primitives
106```
107</architecture_structure>
108 
109<layer_separation>
110**Layer Separation:**
111- **Domain Layer** (`engine/core/`): Shared business entities, value objects, and cross-domain primitives
112- **Application Layer** (`engine/{agent,task,tool,workflow}/`): Domain-specific business logic, use cases, and port interfaces (repositories, external services)
113- **Infrastructure Layer** (`engine/infra/`): External concerns (DB, HTTP, etc.) and adapter implementations
114- **Runtime Layer** (`engine/runtime/`): Execution environment and system orchestration
115 
116**Interface Ownership Clarification:**
117- **Port Interfaces** (e.g., Repository, ExternalService): Defined in Application Layer packages where they're used
118- **Domain Entities**: Defined in Domain Layer (`engine/core/`) for cross-domain sharing
119- **Adapter Implementations**: Defined in Infrastructure Layer, implementing Application Layer interfaces
120</layer_separation>
121 
122<dependency_flow>
123```go
124// ✅ Good: Dependencies flow inward
125package task
126 
127import (
128    "context"
129    "github.com/project/engine/core" // Domain entities
130)
131 
132type Service struct {
133    repo Repository // Interface defined in domain
134}
135 
136type Repository interface { // Domain-defined interface
137    Save(ctx context.Context, task *core.Task) error
138    Find(ctx context.Context, id core.ID) (*core.Task, error)
139}
140 
141// Implementation in infrastructure layer
142package infra
143 
144import (
145    "github.com/project/engine/task" // Application layer
146)
147 
148type PostgreSQLTaskRepository struct {
149    db *sql.DB
150}
151 
152func (r *PostgreSQLTaskRepository) Save(ctx context.Context, task *core.Task) error {
153    // Implementation details
154}
155```
156</dependency_flow>
157 
158### Clean Code Practices
159 
160**Naming Conventions:**
161- Use intention-revealing names
162- Avoid mental mapping and abbreviations
163- Use searchable names for important concepts
164 
165<example type="naming_conventions">
166```go
167// ✅ Good: Clear, intention-revealing names
168type WorkflowExecutionResult struct {
169    TaskResults    []TaskResult  `json:"task_results"`
170    ExecutionTime  time.Duration `json:"execution_time"`
171    Status         ExecutionStatus `json:"status"`
172}
173 
174func (w *WorkflowService) ExecuteWorkflowWithRetry(
175    ctx context.Context,
176    workflowID core.ID,
177    maxRetries int,
178) (*WorkflowExecutionResult, error) {
179    // Implementation
180}
181 
182// ❌ Bad: Unclear, abbreviated names
183type WfExecRes struct {
184    TskRes []TskRes `json:"tr"`
185    ExecT  int64    `json:"et"`
186    Stat   int      `json:"s"`
187}
188 
189func (w *WfSvc) ExecWf(ctx context.Context, id string, mr int) (*WfExecRes, error) {
190    // Implementation
191}
192```
193</example>
194 
195<function_design>
196**Function Design:**
197- Follow function length limits defined in go-coding-standards.mdc
198- Single level of abstraction per function
199- Minimize function parameters (max 3-4)
200</function_design>
201 
202<example type="function_design">
203```go
204// ✅ Good: Small, focused function
205func (s *TaskService) ValidateTaskInput(task *core.Task) error {
206    if err := s.validateRequiredFields(task); err != nil {
207        return fmt.Errorf("validation failed: %w", err)
208    }
209    if err := s.validateBusinessRules(task); err != nil {
210        return fmt.Errorf("business rule validation failed: %w", err)
211    }
212    return nil
213}
214 
215func (s *TaskService) validateRequiredFields(task *core.Task) error {
216    if task.Title == "" {
217        return errors.New("title is required")
218    }
219    if task.Type == "" {
220        return errors.New("type is required")
221    }
222    return nil
223}
224```
225</example>
226 
227<error_handling_architecture>
228**Error Handling Architecture:**
229Follow unified error handling strategy from [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc)
230</error_handling_architecture>
231 
232<example type="error_handling">
233```go
234// ✅ Good: Structured error handling
235func (s *WorkflowService) ExecuteWorkflow(ctx context.Context, id core.ID) error {
236    workflow, err := s.repo.FindWorkflow(ctx, id)
237    if err != nil {
238        return fmt.Errorf("failed to load workflow %s: %w", id, err)
239    }
240 
241    if err := s.validateWorkflow(workflow); err != nil {
242        return core.NewError(err, "WORKFLOW_VALIDATION_FAILED", map[string]any{
243            "workflow_id": id,
244            "workflow_type": workflow.Type,
245        })
246    }
247 
248    return s.executeWorkflowTasks(ctx, workflow)
249}
250```
251</example>
252 
253## Project-Specific Patterns
254 
255### Domain Organization
256 
257<package_structure>
258**Package Structure:**
259- Each domain in `engine/` has clear boundaries
260- Shared types in `engine/core/`
261- Infrastructure concerns in `engine/infra/`
262</package_structure>
263 
264### Service Construction
265 
266<constructor_pattern type="mandatory">
267**MANDATORY constructor pattern for all services**
268- Use dependency injection through constructors
269- Always provide nil-safe configuration handling
270- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
271</constructor_pattern>
272 
273### Context Propagation
274 
275<context_requirements type="mandatory">
276**Context as first parameter in all functions**
277- Always handle context cancellation
278- Propagate context through call chains
279- *Context handling patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
280</context_requirements>
281 
282### Resource Management
283 
284<cleanup_patterns>
285**Resource cleanup requirements:**
286- Use defer for cleanup operations
287- Handle cleanup errors appropriately
288- Implement timeout handling for long-running operations
289- *Resource management patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
290</cleanup_patterns>
291 
292## Anti-Patterns to Avoid
293 
294### God Objects
295```go
296// ❌ Avoid: Too many responsibilities
297type MegaService struct {
298    // Too many dependencies and responsibilities
299}
300```
301 
302### Tight Coupling
303```go
304// ❌ Avoid: Direct dependency on concrete types
305type Service struct {
306    db *sql.DB // Should be an interface
307}
308```
309 
310### Circular Dependencies
311```go
312// ❌ Avoid: Package A imports B, B imports A
313```
314 
315### Magic Numbers/Strings
316```go
317// ❌ Avoid: Magic values
318if status == 1 { /* what does 1 mean? */ }
319 
320// ✅ Use: Named constants
321const StatusActive = 1
322if status == StatusActive { /* clear meaning */ }
323```
324 
325## Quality Metrics
326 
327### Code Quality Indicators
328- **Function complexity and length:** Follow limits defined in go-coding-standards.mdc
329- **Package Coupling:** Minimize cross-package dependencies
330- **Test Coverage:** Aim for 80%+ on business logic
331 
332### Architecture Health
333- **Dependency Direction:** Always inward toward domain
334- **Interface Usage:** High ratio of interfaces to concrete types
335- **Package Cohesion:** Related functionality grouped together
336- **Separation of Concerns:** Clear boundaries between layers
337 
338## Final Guidelines
339 
3401. **Design for Change:** Assume requirements will evolve
3412. **Favor Composition:** Over inheritance and complex hierarchies
3423. **Explicit Dependencies:** Make all dependencies visible
3434. **Fail Fast:** Validate inputs early and fail explicitly
3445. **Document Decisions:** Capture architectural decisions and trade-offs
3456. **Measure and Monitor:** Track architecture health metrics
3467. **Refactor Continuously:** Improve design as understanding grows
3478. **Test Architecture:** Verify architectural constraints in tests
348