القائمة
Use when a developer needs orientation to the Trovara codebase — new team member, returning after a gap, or asking "how does X work", "where is Y", or "how do I add a new feature".
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | codebase-onboarding |
| description | Use when a developer needs orientation to the Trovara codebase — new team member, returning after a gap, or asking "how does X work", "where is Y", or "how do I add a new feature". |
| allowed-tools | Read, Grep, Glob, Bash |
| model | sonnet |
Orients a developer to Trovara's architecture, conventions, and key workflows. Ground every answer in the actual code — no generic Flutter advice.
Before exploring, ask or infer:
Tailor the tour to that scope.
| Area | Read first |
|---|---|
| Views / UI | lib/views/CLAUDE.md + docs/style_guide/Views_Style_Guide.md |
| Core services / DI | lib/core/CLAUDE.md |
| AI / RAG / embeddings | lib/core/services/ai/CLAUDE.md |
| Testing | patrol_test/CLAUDE.md + docs/PATROL_UNIT_TESTING.md |
| File near ~250 LOC | docs/style_guide/File_Organization_Rules.md |
Trovara — Flutter note-taking app with AI-powered RAG, Google Drive sync, and rich-text editing.
Stack: Flutter ≥3.8.1 · ObjectBox (local DB) · Provider (MVVM) · go_router · easy_localization (English + Khmer) · firebase_ai / Gemini / OpenAI-compatible HTTP · Google Drive API · Shorebird OTA.
Two flavors: staging (lib/main_staging.dart) and prod (lib/main_prod.dart), both delegate to lib/main.dart. API keys via --dart-define → lib/constants/config_constants.dart.
Startup sequence (lib/initializer.dart): EasyLocalization → Firebase → ThemeModeStorage → ServiceLocator().initialize() → Google Drive session restore → Shorebird OTA check.
// View — UI only, no logic
class NotesView extends StatelessWidget {
@override
Widget build(BuildContext context) => ViewModelProvider<NotesViewModel>(
create: (context) => NotesViewModel(),
root: true,
builder: (context, viewModel, child) => _NotesContent(viewModel),
);
}
// ViewModel — gets services via ServiceLocator, never calls ObjectBox directly
class NotesViewModel extends BaseViewModel {
final NoteService _noteService = ServiceLocator().noteService;
}
Folder structure per view:
lib/views/<feature>/
├── <feature>_view.dart # ViewModelProvider shell (< 30 lines)
├── <feature>_view_model.dart # business logic (< 300 lines)
├── <feature>_content.dart # part file: private _<Feature>Content
└── widgets/ # part files for sub-widgets
Interface → Implementation → ServiceLocator. ViewModels only see the interface.
lib/core/repository/interfaces/note_repository.dart → INoteRepository (abstract)
lib/core/repository/implementations/objectbox_note_repository.dart → ObjectBoxNoteRepository
lib/core/di/service_locator.dart → lazy getter wiring
lib/core/di/service_locator.dart is the only place implementations are wired.
// Add a new service:
MyService? _myService;
MyService get myService {
_myService ??= MyService(noteRepository: noteRepository);
return _myService!;
}
// In a ViewModel:
final _service = ServiceLocator().myService;
context.push('/note?noteId=42&readOnly=true'); // push
context.go('/'); // replace
Routes declared in lib/core/route/app_router.dart.
lib/core/services/ai/)Before touching any code, internalize these:
MyService() constructors outside service_locator.dart.INoteRepository, never ObjectBoxNoteRepository.tr('domain.key') always. Add to both en.json AND km.json.Theme.of(context).colorScheme.* only.LucideIcons.* from lucide_icons_flutter — never Icons.*.*.g.dart. Run ./scripts/build_runner.sh after model changes.package:logger — avoid_print is enforced.# Setup
flutter pub get
./scripts/build_runner.sh # Generate ObjectBox + flutter_gen code
./scripts/install_hooks.sh # Pre-commit hooks
# Run
./scripts/run_app.sh --quick # staging + debug, no prompts
# Quality
flutter analyze
flutter test patrol_test # logic tests, no emulator
./scripts/patrol_test.sh # E2E tests (requires emulator)
# Build
./scripts/build_apk.sh --trovara
./scripts/build_ipa.sh
Slash commands: /new-view <feature> · /i18n-check · /build-and-test
A change is not done until:
flutter analyze — zero new errorsflutter test patrol_test — all greenen.json and km.jsonbuild_runner runUse when inserting a new i18n key into Trovara's locale files — adds the key to both en.json and km.json under the correct nested path and verifies parity.
Use when incrementing the Trovara app version before a release — updates the semver and build number in pubspec.yaml following the project's versioning convention.
Use when reviewing a Trovara code change — checks correctness, MVVM layering, security, performance, i18n parity, file-size limits, and test coverage like a senior engineer.
Use when a new service, repository, or subsystem needs documentation — CLAUDE.md for new directories, dartdoc for public APIs, or updating existing architecture docs after a structural change.
Use when adding a new screen, modifying existing feature behavior, or wiring new business logic end-to-end in Trovara — creates MVVM scaffold, route, ServiceLocator wiring, and i18n keys.
Use when adding a new persistable data entity to Trovara — scaffolds the ObjectBox model class, repository interface, ObjectBox implementation, and ServiceLocator wiring, then runs codegen.