Skip to content

Commit 1932eeb

Browse files
xsahil03xxsahil03x
authored
refactor(llc): refactor client and add impl (#8)
1 parent 96fcae0 commit 1932eeb

File tree

1,399 files changed

+108290
-15643
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,399 files changed

+108290
-15643
lines changed

‎.cursor/rules/cursor-rules-location.mdc‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
---
2+
description: Cursor Rules organization and file structure standards
3+
globs: ["**/*.mdc", ".cursorrules"]
4+
alwaysApply: true
5+
---
6+
7+
# Cursor Rules Organization - Modern Standards
8+
9+
Implement effective organization and file structure standards for Cursor AI rules and configuration files in the repository.
10+
11+
## When to Apply
12+
13+
Use these guidelines when:
14+
- Organizing cursor rules for a new project
15+
- Restructuring existing cursor configuration
16+
- Adding new domain-specific rule files
17+
- Updating rules for better AI understanding
18+
- Migrating from legacy cursor rule patterns
19+
20+
## Core Principles
21+
22+
- ✅ **Clear Hierarchy**: Primary rules in root, specialized rules in subdirectories
23+
- ✅ **Single Responsibility**: Each rule file has a focused purpose
24+
- ✅ **Consistent Structure**: Standardized format across all rule files
25+
- ✅ **Actionable Content**: Rules provide implementation guidance, not just documentation
26+
- ✅ **Maintainable**: Easy to update and extend as project evolves
27+
- ✅ **AI-Friendly**: Structured for optimal Cursor AI understanding
28+
29+
## Implementation Guide
30+
31+
### Step 1: File Structure Setup
32+
33+
Organize cursor rules following modern 2024/2025 best practices:
34+
35+
```
36+
stream-feeds-flutter/
37+
├── .cursorrules # Primary development rules
38+
├── .cursor/
39+
│ └── rules/ # Supplementary documentation
40+
│ ├── project-overview.mdc # Development context & architecture
41+
│ ├── stream-feeds-sdk.mdc # SDK implementation patterns
42+
│ ├── stream-feeds-api.mdc # Stream Feeds API overview
43+
│ ├── planit-mode.mdc # Structured development methodology
44+
│ ├── cursor-rules-location.mdc # This file - organization docs
45+
│ └── patterns/ # Implementation pattern rules
46+
│ ├── data-models.mdc # @freezed data class guidelines
47+
│ ├── query-specifications.mdc # Query class patterns
48+
│ ├── repository-pattern.mdc # Repository implementation
49+
│ ├── data-mapping.mdc # Extension function mapping
50+
│ └── state-management.mdc # StateNotifier patterns
51+
└── ...
52+
```
53+
54+
### Step 2: Primary Configuration
55+
56+
Create the main `.cursorrules` file in project root:
57+
58+
```
59+
# Stream Feeds Dart SDK - Cursor Rules
60+
61+
You are an expert Dart developer working on the Stream Feeds Dart SDK, a professional real-time activity feeds SDK. Follow these guidelines strictly.
62+
63+
## Project Context
64+
65+
This is a pure Dart SDK that implements the Stream Feeds API for real-time social feeds and activity streams. The SDK:
66+
67+
- Provides activity feeds, social interactions, and real-time updates
68+
- Works across all Dart environments (Flutter, Dart VM, Dart Web)
69+
- Uses WebSocket for real-time updates and OpenAPI-generated HTTP client for API communication
70+
- Implements StateNotifier-based reactive state management with automatic notifications
71+
- Uses @freezed models for immutable data structures
72+
73+
## Architecture & Design Patterns
74+
75+
### Project Structure
76+
- Follow the existing structure: `lib/src/` for implementation details
77+
- Keep public API in `lib/` root files (main entry point: `stream_feeds.dart`)
78+
- Use `@includeInBarrelFile` to mark classes/functions for public API export
79+
- Generated barrel files automatically export public elements from `lib/src/`
80+
- Tests mirror the lib structure in `test/`
81+
- Use clear layer separation: core, data, presentation, client, state_objects
82+
83+
// ... more specific guidelines
84+
```
85+
86+
### Step 3: Supplementary Rules Structure
87+
88+
Create specialized `.mdc` files for complex contexts:
89+
90+
```yaml
91+
---
92+
description: Brief description of rule purpose
93+
globs: ["**/*.dart", "**/*.swift"] # File patterns to apply to
94+
alwaysApply: true/false # Whether to apply automatically
95+
---
96+
97+
# Rule Title - Action-Oriented Description
98+
99+
Brief description of what this rule accomplishes and when to use it.
100+
101+
## When to Apply
102+
103+
Use these guidelines when:
104+
- Specific trigger condition 1
105+
- Specific trigger condition 2
106+
- Specific trigger condition 3
107+
108+
## Core Principles
109+
110+
- ✅ **Principle 1**: Clear, actionable guidance
111+
- ✅ **Principle 2**: Specific implementation approach
112+
- ✅ **Principle 3**: Measurable outcome
113+
114+
## Implementation Guide
115+
116+
### Step 1: Title
117+
Detailed implementation instructions...
118+
119+
### Step 2: Title
120+
More implementation steps...
121+
122+
## Best Practices Checklist
123+
124+
When implementing, ensure:
125+
- [ ] Checklist item 1
126+
- [ ] Checklist item 2
127+
- [ ] Checklist item 3
128+
129+
## Success Criteria
130+
131+
A well-implemented solution should:
132+
- ✅ Measurable criterion 1
133+
- ✅ Measurable criterion 2
134+
- ✅ Measurable criterion 3
135+
```
136+
137+
### Step 4: Naming Conventions
138+
139+
Apply consistent naming standards:
140+
141+
#### File Naming
142+
- **`.cursorrules`**: Always this exact filename in root
143+
- **`.mdc files`**: Use kebab-case, descriptive names (e.g., `stream-feeds-api.mdc`)
144+
- **Subdirectories**: Use lowercase, functional grouping (e.g., `patterns/`, `testing/`)
145+
146+
#### Content Naming
147+
- **Descriptive**: Names should indicate purpose clearly
148+
- **Action-Oriented**: Use active verbs in titles ("Implement X", "Build Y", "Create Z")
149+
- **Consistent**: Follow established patterns across all rule files
150+
151+
## Organization Strategy
152+
153+
### Top-Level Rules (`.cursor/rules/`)
154+
- **Project Overview**: High-level architecture and context
155+
- **SDK Documentation**: Main SDK explanation and features
156+
- **API Documentation**: External API and service information
157+
- **Organization Guidelines**: This file and meta-documentation
158+
159+
### Patterns Subdirectory (`.cursor/rules/patterns/`)
160+
- **Component-Specific**: Rules for specific code component types
161+
- **Implementation Focus**: Detailed coding patterns and best practices
162+
- **Architectural Layers**: Organized by responsibility (data, state, mapping)
163+
- **Code Examples**: Rich examples and implementation guidelines
164+
165+
### Content Guidelines
166+
167+
#### For .cursorrules (Primary)
168+
- Focus on general development patterns
169+
- Include language/framework specific guidelines
170+
- Define code style and architecture preferences
171+
- Keep concise but comprehensive
172+
173+
#### For .mdc files (Supplementary)
174+
- Use YAML frontmatter for metadata
175+
- Include detailed context and examples
176+
- Focus on specific domains or complex scenarios
177+
- Use action-oriented structure (When to Apply, Implementation Guide, Success Criteria)
178+
179+
## Code Generation & Barrel Files
180+
181+
### Barrel Files Strategy
182+
- Use `barrel_files` package for automated public API management
183+
- Place `@includeInBarrelFile` annotation on public classes, enums, and functions
184+
- Keep implementation details in `lib/src/` without annotations
185+
- Generate barrel files with `build_runner` alongside other code generation
186+
187+
### Dependencies Setup
188+
```yaml
189+
dependencies:
190+
barrel_files_annotation: ^0.1.1
191+
192+
dev_dependencies:
193+
barrel_files: ^0.1.1
194+
build_runner: ^2.4.7
195+
```
196+
197+
### Public API Guidelines
198+
- Mark only classes/functions intended for external package usage
199+
- Internal SDK components should remain in `lib/src/` without annotations
200+
- Repository classes, mappers, and internal state objects are not public
201+
- Only client interfaces, data models, queries, and exceptions are public
202+
203+
## Maintenance Strategy
204+
205+
### Integration from Legacy Patterns
206+
1. **Primary rules** → Move to `.cursorrules` in root
207+
2. **Complex rules** → Keep as `.mdc` files in `.cursor/rules/`
208+
3. **Update metadata** → Add proper YAML frontmatter
209+
4. **Consolidate overlaps** → Avoid duplication between files
210+
211+
### Ongoing Maintenance
212+
- Keep `.cursorrules` as the primary entry point
213+
- Use `.mdc` files for specialized contexts only
214+
- Review rules quarterly for framework updates
215+
- Update based on framework/language evolution
216+
- Tag rule versions in git for change tracking
217+
- Document rule changes in commit messages
218+
219+
### Quality Standards
220+
- **Specificity**: Rules should be specific to project needs
221+
- **Clarity**: Clear, actionable guidelines
222+
- **Currency**: Updated for latest framework versions
223+
- **Completeness**: Cover common development scenarios
224+
- **Validation**: Rules should be testable and verifiable
225+
226+
## Best Practices Checklist
227+
228+
When organizing cursor rules, ensure:
229+
230+
- [ ] Used clear file structure with `.cursorrules` in root
231+
- [ ] Applied consistent naming conventions (kebab-case for .mdc)
232+
- [ ] Added proper YAML frontmatter to .mdc files
233+
- [ ] Organized by functional responsibility
234+
- [ ] Used action-oriented language throughout
235+
- [ ] Included implementation guides and success criteria
236+
- [ ] Avoided duplication between files
237+
- [ ] Made rules specific to project needs
238+
- [ ] Updated content for latest framework versions
239+
- [ ] Documented organization decisions
240+
241+
## Common Organization Patterns
242+
243+
### Basic Project Setup
244+
```
245+
PROJECT_ROOT/
246+
├── .cursorrules # Primary rules (REQUIRED)
247+
├── .cursor/
248+
│ └── rules/ # Supplementary rules (OPTIONAL)
249+
│ ├── project-context.mdc # Project-specific context
250+
│ ├── architecture-rules.mdc # Architecture guidelines
251+
│ └── domain-specs.mdc # Domain-specific patterns
252+
└── ...
253+
```
254+
255+
### Advanced Multi-Domain Setup
256+
```
257+
PROJECT_ROOT/
258+
├── .cursorrules # Primary development rules
259+
├── .cursor/
260+
│ └── rules/ # Specialized contexts
261+
│ ├── project-overview.mdc # High-level context
262+
│ ├── sdk-patterns.mdc # SDK-specific patterns
263+
│ ├── api-integration.mdc # External API patterns
264+
│ └── patterns/ # Implementation patterns
265+
│ ├── data-models.mdc # Data structure patterns
266+
│ ├── state-mgmt.mdc # State management patterns
267+
│ └── testing.mdc # Testing strategies
268+
└── ...
269+
```
270+
271+
### Rule Validation in CI
272+
- Validate YAML frontmatter syntax
273+
- Check for broken internal links
274+
- Verify code examples compile
275+
- Test rule consistency across files
276+
277+
## Success Criteria
278+
279+
A well-organized cursor rules system should:
280+
- ✅ Provide clear, actionable guidance for AI and developers
281+
- ✅ Follow consistent structure and naming conventions
282+
- ✅ Scale effectively as project complexity grows
283+
- ✅ Support easy maintenance and updates
284+
- ✅ Include proper validation and quality checks
285+
- ✅ Focus on implementation guidance over documentation
286+
- ✅ Use modern 2024/2025 best practices
287+
- ✅ Support both general and specialized development contexts
288+
- ✅ Include automated rule validation in CI/CD
289+
- ✅ Balance simplicity with flexibility for complex scenarios

0 commit comments

Comments
 (0)