`
- Auth: `@attribute [Authorize]` on protected pages
- Cleanup: `@implements IAsyncDisposable`
## Database Patterns
- **DbContext:** `ApplicationDbContext` — SQLite on mobile, PostgreSQL on server
- **Table names:** SINGULAR (configured in OnModelCreating)
- **Synced entities:** String GUID PKs with `ValueGeneratedNever()`
- **Non-synced:** Int auto-increment PKs
- **Migrations:** Always via `dotnet ef migrations add` — NEVER hand-write, NEVER raw SQL ALTER TABLE
- **Data isolation:** Filter by `UserProfileId`
- **CRITICAL:** Never call `EnsureCreatedAsync` before `MigrateAsync`
- **Migration location:** `Migrations/` (PostgreSQL), `Migrations/Sqlite/` (mobile)
## AI/Prompt Patterns
- **Templates:** 24+ Scriban templates in `src/SentenceStudio.AppLib/Resources/Raw/*.scriban-txt`
- **Client:** `IChatClient` (Microsoft.Extensions.AI) via `AiService.SendPrompt
()`
- **DTOs:** Use `[Description]` attributes on properties — no `[JsonPropertyName]`
- **Connectivity:** Check `_connectivity.IsInternetAvailable` before AI calls
- **Gateway:** Optional `IAiGatewayClient` for server routing
## Service Patterns
- Constructor injection via `IServiceProvider`
- All methods async (`Task`)
- `ILogger` for structured logging
- `WeakReferenceMessenger.Default.Send()` for cross-component messaging
- Scoped DbContext access: `_serviceProvider.CreateScope()` → `GetRequiredService()`
## Error Handling
- Structured logging: `_logger.LogError(ex, "context {Field}", value)`
- `InvalidOperationException` for state violations
- `ArgumentException` for invalid arguments
- Default/null returns for external API failures (TTS, image)
- Connectivity resilience via `ConnectivityChangedMessage`
## Activity tracking (ad-hoc + plan items)
- Every activity page calls `ActivityTimer.StartSession(activityType, PlanItemId, resourceId, skillId)` **unconditionally** — when `PlanItemId` is null/empty the service creates a synthetic `DailyPlanCompletion` with `PlanItemId = "adhoc-{guid}"` so freeform sessions get duration tracking.
- `activityType` string must parse to a `PlanActivityType` enum value or the ad-hoc row is silently dropped. **Valid enum values** (see `IProgressService.cs`): `VocabularyReview, Reading, Listening, VideoWatching, Shadowing, Cloze, Translation, Writing, SceneDescription, Conversation, VocabularyGame`. **NOT valid**: `VocabularyMatching` (use `VocabularyGame`), `HowDoYouSay`, `WordAssociation`, `MinimalPairs`.
- `ReconstructPlanFromDatabase` filters `adhoc-*` so they don't show up in "Today's Plan"; `GetActivityLogAsync` includes them so day-detail shows freeform practice with its own "Freeform practice" cluster.
- Query param naming is NOT uniform: most pages use singular `ResourceIdParam`; `VocabQuiz`/`VocabMatching` use plural `ResourceIdsParam` (comma-separated — take `.Split(',').FirstOrDefault()` for ad-hoc persistence).
## Scriban prompt loops
Default iteration limit is 1000. Dynamic learning resources ("New Words") can return thousands of unpracticed terms. Any service rendering `{{ for t in terms }}` must cap the collection before passing to the template — current cap is **40 random words** in `TranslationService` and `ClozureService`. If adding a new activity that loops vocab, apply the same cap.
## MauiReactor Conventions
- Use `VStart()` / `VEnd()` not `Top()` / `Bottom()`
- Use `HStart()` / `HEnd()` not `Start()` / `End()`
- NEVER use `FillAndExpand` — legacy pattern
- NEVER put CollectionView inside scrollable containers
## Anti-Patterns (CRITICAL)
- ❌ NEVER uninstall/reinstall apps (destroys user data)
- ❌ NEVER delete database files without permission + backup
- ❌ NEVER use `dotnet run` for MAUI apps
- ❌ NEVER use emoji in UI/code/logs
- ❌ NEVER use raw SQL ALTER TABLE — always EF migrations
- ❌ NEVER suppress PendingModelChangesWarning
- ❌ NEVER put CollectionView inside VStack/scrollable containers
- ❌ NEVER use inline FontImageSource — define in ApplicationTheme.Icons.cs
- ❌ All documentation files go in `/docs/` not repo root