Skip to content

Commit 1926638

Browse files
renefloorrenefloor
authored
feat(repo): create AGENTS.md file for the feeds repo (#54)
1 parent 515ed5c commit 1926638

File tree

1 file changed

+315
-0
lines changed

1 file changed

+315
-0
lines changed

‎AGENTS.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# AGENTS.md
2+
3+
This file provides essential context for AI agents and developers working on the Stream Feeds Flutter/Dart SDK.
4+
5+
## Project Overview
6+
7+
This is the **official Flutter/Dart SDK** for Stream Feeds API v3, a scalable activity feed service. The repository contains:
8+
9+
- **Low-level SDK** (`packages/stream_feeds/`): Pure Dart SDK for Stream Feeds API v3
10+
- **Sample App** (`sample_app/`): Flutter demo application showcasing SDK usage
11+
- **Documentation** (`docs/`): Code snippets and examples
12+
13+
## Repository Structure
14+
15+
```
16+
stream-feeds-flutter/
17+
├── packages/
18+
│ └── stream_feeds/ # Main SDK package
19+
│ ├── lib/
20+
│ │ ├── stream_feeds.dart # Public API entry point
21+
│ │ └── src/
22+
│ │ ├── client/ # Client implementation
23+
│ │ ├── cdn/ # CDN API client
24+
│ │ ├── generated/ # OpenAPI-generated API code
25+
│ │ ├── models/ # Domain models (@freezed)
26+
│ │ ├── repository/ # Data access layer
27+
│ │ ├── resolvers/ # Feature resolvers
28+
│ │ ├── state/ # State objects and handlers
29+
│ │ ├── utils/ # Utility classes (filter, sort, batcher, uploader)
30+
│ │ └── ws/ # WebSocket event handling
31+
│ └── test/ # Test suite
32+
├── sample_app/ # Flutter demo app
33+
├── docs/ # Documentation and examples
34+
└── scripts/ # Build and generation scripts
35+
```
36+
37+
## Architecture Principles
38+
39+
### Core Design Patterns
40+
41+
1. **Pure Dart**: The low-level SDK (stream_feeds) is pure Dart and has no platform-specific dependencies. It can be used outside of Flutter.
42+
2. **Layered Architecture**: Clear separation between client, core, data, presentation, and state layers
43+
3. **Immutable Data**: All models use `@freezed` with const constructors
44+
4. **Reactive State**: StateNotifier-based state management with automatic change notifications
45+
5. **Result Pattern**: Explicit error handling using Result types (not exceptions)
46+
6. **Public API Focus**: Clean separation between public API (`lib/`) and internal implementation (`lib/src/`)
47+
48+
### Layer Responsibilities
49+
50+
- **Client Layer** (`src/client/`): Client factory and implementation
51+
- **Models** (`src/models/`): Domain models, queries, and business logic (all `@freezed` data classes)
52+
- **Repository Layer** (`src/repository/`): Data access layer with Result pattern
53+
- **State Management** (`src/state/`): StateNotifier implementations and high-level state objects (Feed, ActivityList, etc.)
54+
- **Utilities** (`src/utils/`): Helper classes for filtering, sorting, batching, and file uploads
55+
- **WebSocket** (`src/ws/`): Real-time event handling and WebSocket connections
56+
- **CDN** (`src/cdn/`): CDN API client for file uploads
57+
- **Generated** (`src/generated/`): OpenAPI-generated API client code
58+
59+
## Code Generation
60+
61+
The project uses extensive code generation:
62+
63+
### Generated Code
64+
65+
1. **OpenAPI Client** (`src/generated/api/`): Auto-generated from OpenAPI spec
66+
- Generated via `scripts/generate.sh`
67+
- Includes API models, endpoints, and serialization
68+
69+
2. **Freezed Models** (`*.freezed.dart`): Immutable data classes
70+
- Run: `melos run generate:all`
71+
- Uses `freezed` and `json_serializable`
72+
73+
3. **Retrofit** (`*.g.dart`): HTTP client generation
74+
- Uses `retrofit_generator` for API client methods
75+
76+
### Running Code Generation
77+
78+
```bash
79+
# Generate all (Dart + Flutter packages)
80+
melos run generate:all
81+
82+
# Generate only Dart packages
83+
melos run generate:dart
84+
85+
# Generate only Flutter packages
86+
melos run generate:flutter
87+
88+
# Generate OpenAPI client (requires OpenAPI spec)
89+
melos run gen:feeds
90+
```
91+
92+
**Important**: Never manually edit generated files. All changes must be made in source files or OpenAPI specs.
93+
94+
## Coding Standards
95+
96+
### Data Models
97+
98+
- Use `@freezed` for all data classes
99+
- Follow Freezed 3.0 mixed mode syntax with `@override` annotations
100+
- All models should have an `id` field when representing entities
101+
- Place custom data fields last in constructors and class definitions
102+
103+
Example:
104+
```dart
105+
@freezed
106+
class ActivityData with _$ActivityData {
107+
const ActivityData({
108+
required this.id,
109+
required this.user,
110+
this.custom,
111+
});
112+
113+
@override
114+
final String id;
115+
@override
116+
final UserData user;
117+
@override
118+
final Map<String, Object>? custom;
119+
}
120+
```
121+
122+
### State Management
123+
124+
- Use StateNotifier for reactive state management
125+
- State classes must use `@freezed` with const constructors
126+
- High-level state objects (Feed, ActivityList) are the public API
127+
- StateNotifier implementations are internal details
128+
129+
### Repository Pattern
130+
131+
- All repository methods return `Result<T>` types
132+
- Use early return patterns for validation and errors
133+
- Use extension functions for API-to-domain model mapping
134+
- Never throw exceptions - always return Result types
135+
136+
Example:
137+
```dart
138+
Future<Result<ActivityData>> getActivity(String id) async {
139+
try {
140+
final result = await apiClient.getActivity(id: id);
141+
if (result == null) {
142+
return Result.failure(NetworkException('No data returned'));
143+
}
144+
return Result.success(result.toModel());
145+
} on ClientException catch (e) {
146+
return Result.failure(_mapClientException(e));
147+
}
148+
}
149+
```
150+
151+
### Documentation
152+
153+
- Use `///` for public API documentation
154+
- Use `//` for internal/private code
155+
- Follow Effective Dart documentation guidelines
156+
- Include examples for complex APIs
157+
158+
## Testing Strategy
159+
160+
### Test Structure
161+
162+
- Tests mirror the `lib/` structure in `test/`
163+
- Focus on testing through public APIs only
164+
- Use HTTP interceptors instead of mocking repositories
165+
- Test StateNotifier behavior through high-level state objects
166+
167+
### Running Tests
168+
169+
```bash
170+
# Run all tests
171+
melos run test:all
172+
173+
# Run Dart tests only
174+
melos run test:dart
175+
176+
# Run Flutter tests only
177+
melos run test:flutter
178+
```
179+
180+
## Dependencies & Monorepo
181+
182+
### Melos Workspace
183+
184+
This is a **Melos monorepo** for managing multiple packages:
185+
186+
- All dependencies are defined in `melos.yaml`
187+
- **Never** edit `pubspec.yaml` environment or dependency versions directly
188+
- Use `melos bootstrap` to sync dependencies after changes
189+
190+
### Adding Dependencies
191+
192+
1. Add dependency to `packages/stream_feeds/pubspec.yaml`
193+
2. Add it to `melos.yaml` dependencies list
194+
3. Run `melos bootstrap` to sync
195+
196+
### Key Dependencies
197+
198+
- **state_notifier**: Reactive state management
199+
- **freezed**: Immutable data classes
200+
- **dio**: HTTP client
201+
- **retrofit**: Type-safe HTTP client
202+
- **stream_core**: Core HTTP/WSS infrastructure
203+
204+
See `melos.yaml` for complete dependency list.
205+
206+
## Development Workflow
207+
208+
### Code Quality
209+
210+
```bash
211+
# Format code
212+
melos run format
213+
214+
# Verify formatting
215+
melos run format:verify
216+
217+
# Run static analysis
218+
melos run analyze
219+
220+
# Run linting + formatting
221+
melos run lint:all
222+
```
223+
224+
### Common Tasks
225+
226+
1. **Making Changes to Models**:
227+
- Edit the `.dart` model file
228+
- Run `melos run generate:all`
229+
- Commit both source and generated files
230+
231+
2. **Updating OpenAPI Client**:
232+
- Update OpenAPI spec (if you have access)
233+
- Run `melos run gen:feeds`
234+
- Review generated changes in `src/generated/`
235+
236+
3. **Adding New Features**:
237+
- Create models in `src/models/`
238+
- Add repositories in `src/repository/`
239+
- Create state objects in `src/state/`
240+
- Export in `lib/stream_feeds.dart` if public API
241+
242+
## File Organization Rules
243+
244+
### Public vs Internal
245+
246+
- **Public API**: Files in `lib/` root
247+
- **Internal**: Everything in `lib/src/`
248+
249+
### Naming Conventions
250+
251+
- Models: `*Data` (e.g., `ActivityData`, `FeedData`)
252+
- Queries: `*Query` (e.g., `ActivitiesQuery`, `FeedsQuery`)
253+
- Requests: `*Request` (e.g., `FeedAddActivityRequest`)
254+
- State: `*State` (e.g., `FeedState`, `ActivityListState`)
255+
- StateNotifier: `*StateNotifier` (e.g., `FeedStateNotifier`)
256+
257+
## Important Files
258+
259+
- `.cursorrules`: Primary development rules for AI assistants
260+
- `.cursor/rules/`: Supplementary documentation for specific patterns
261+
- `analysis_options.yaml`: Dart analyzer configuration
262+
- `melos.yaml`: Monorepo configuration and dependencies
263+
- `scripts/generate.sh`: OpenAPI client generation script
264+
265+
## WebSocket & Real-time
266+
267+
- Real-time updates via WebSocket connections
268+
- Event handlers in `src/ws/events/`
269+
- Events use `@freezed` for type-safe event handling
270+
- State objects automatically update from WebSocket events
271+
272+
## Versioning
273+
274+
- SDK uses semantic versioning
275+
- Version managed in `packages/stream_feeds/pubspec.yaml`
276+
- Versioning mode: independent (per-package)
277+
278+
## Getting Help
279+
280+
- **Documentation**: Check `docs/` for code examples
281+
- **API Docs**: https://getstream.io/activity-feeds/docs/flutter/
282+
- **Cursor Rules**: See `.cursorrules` and `.cursor/rules/` for detailed patterns
283+
284+
## Quick Reference
285+
286+
```bash
287+
# Setup
288+
melos bootstrap
289+
290+
# Generate code
291+
melos run generate:all
292+
293+
# Test
294+
melos run test:all
295+
296+
# Format & lint
297+
melos run lint:all
298+
299+
# Clean
300+
melos run clean:flutter
301+
```
302+
303+
## Important Notes for AI Agents
304+
305+
1. **Always run code generation** after modifying `@freezed` models or OpenAPI specs
306+
2. **Never edit generated files** (`*.freezed.dart`, `*.g.dart`, `src/generated/`)
307+
3. **Use Result pattern** for error handling, not exceptions
308+
4. **Test through public APIs** only, not internal StateNotifier implementations
309+
5. **Follow Freezed 3.0 syntax** with `@override` annotations for fields
310+
6. **Keep public API minimal** - most code should be in `lib/src/`
311+
7. **Use early returns** for validation and error cases
312+
8. **Document public APIs** with `///` following Effective Dart guidelines
313+
9. **Sync dependencies** via `melos bootstrap` after changes
314+
10. **Check `.cursorrules`** for detailed implementation patterns
315+

0 commit comments

Comments
 (0)