A senior-level Flutter portfolio application demonstrating Clean Architecture,
hybrid on-device/cloud AI routing, and cost-conscious engineering.
| Home | Editor | AI Actions |
|---|---|---|
 |
 |
 |
| Insights — Mood Tracker | Insights — Topic Distribution | AI Highlights |
|---|---|---|
 |
 |
 |
Insights History
Three engineering decisions separate NoteAI from a typical Flutter CRUD app:
1. Selective Intelligence — A routing engine (AIOrchestrator) that decides in real time whether a task should run on-device (free, private) or in the cloud (powerful, tracked). This is not a feature flag — it is a decision tree that evaluates prompt complexity, task type, and monthly budget before every AI call.
2. The Budget Guardian — A financial protection system baked into the data layer. Every cloud AI call is intercepted by UsageRepositoryImpl, costed using TokenCalculator, and recorded atomically in Isar. At $8.00 the user sees a warning chip. At $10.00 the app enforces local-only mode — automatically, without any user action required. The guard lives in AIOrchestrator.route(), not in UI button handlers, so it is impossible to bypass by adding a new screen.
3. Strict layer boundaries — Domain, Data, and Presentation layers have zero cross-layer imports. The domain layer has no Flutter or infrastructure dependencies. Every AI action is a standalone use case — adding a new AI feature means adding a new file, not modifying existing ones.
┌─────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ │
│ HomeScreen EditorScreen InsightsScreen FoldersScreen │
│ SettingsScreen (GoRouter + fl_chart + flutter_animate) │
│ │
│ Riverpod Providers (@riverpod code generation) │
│ notesNotifierProvider → aiOrchestratorProvider │
│ summarizeNotifier insightsNotifier settingsProvider │
└─────────────────────┬────────────────────────────────────────┘
│ ref.watch / ref.read
┌─────────────────────▼────────────────────────────────────────┐
│ DOMAIN LAYER │
│ (zero Flutter / infrastructure imports) │
│ │
│ Entities: Note, AiUsage, InsightsData, AiResult │
│ Use Cases: SummarizeNote, ExtractTasks, ChangeTone, │
│ ExpandIdea, FixGrammar, Translate, FormatText, │
│ GenerateInsights, GetNotes, SaveNote, DeleteNote │
│ │
│ ┌───────────────────────────────┐ │
│ │ AIOrchestrator │ The Brain │
│ │ │ │
│ │ route(prompt, task) │ │
│ │ 1. canUseCloudAI? (budget) │ │
│ │ 2. isEligibleForLocal? │ │
│ │ (task type + char length) │ │
│ │ 3. recordUsage after cloud │ │
│ └──────┬──────────────┬─────────┘ │
│ │ │ │
│ Local? │ │ Cloud? │
│ (free, $0) │ │ (tracked, budgeted) │
└──────────────────┼──────────────┼─────────────────────────────┘
│ │ delegates
┌──────────────────▼──────────────▼─────────────────────────────┐
│ DATA LAYER │
│ │
│ ┌──────────────────────────┐ ┌────────────────────────────┐ │
│ │ GemmaDataSourceImpl │ │ GeminiRemoteDataSource │ │
│ │ │ │ │ │
│ │ Primary: Gemma Nano │ │ Routes via Vercel proxy │ │
│ │ (Android AICore) │ │ Gemini 1.5 Flash (simple) │ │
│ │ Fallback: extractive │ │ Gemini 1.5 Pro (complex) │ │
│ │ summarization (Dart) │ │ Uses TokenCalculator for │ │
│ └──────────────────────────┘ │ cost estimation │ │
│ └───────────┬────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────▼──────────────┐ │
│ │ UsageRepositoryImpl (Budget Guardian) │ │
│ │ │ │
│ │ isBudgetExceeded() → reads Isar, compares $10 cap │ │
│ │ recordApiCall() → Read-Modify-Write (atomic) │ │
│ │ getCurrentMonthUsage() → AiUsageModel.toEntity() │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Isar Local Database │ │
│ │ │ │
│ │ NoteModel @collection │ │
│ │ ├── @Index() category (O(1) filter by category) │ │
│ │ └── @Index(type: value) updatedAt (sorted queries) │ │
│ │ │ │
│ │ AiUsageModel @collection │ │
│ │ └── month + year fields (monthly budget tracking) │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
User triggers AI action
│
▼
AIOrchestrator.route(prompt, task)
│
▼
usageRepository.isBudgetExceeded()?
│
YES ($10 reached) ──────────────────────→ _routeToLocalAi()
│ │
│ NO ($0–$9.99) │ isAvailable()?
▼ │
_isEligibleForLocalAi(task, prompt)? NO ──→ Exception
│ (UI shows budget-exceeded msg)
task ∈ {summarize, extractTasks}
AND prompt.length < 500 chars
│
YES │ NO
▼ ▼
_routeToLocalAi() _routeToCloudAi()
│ │
isAvailable()? task ∈ {generateInsights,
│ changeTone}?
NO │ │
│ YES │ NO (expand, fixGrammar,
▼ ▼ translate, formatText)
throws Exception Gemini Pro ▼
│ │ Gemini Flash
catch in route() └────┬───────┘
│ │
▼ TokenCalculator
_routeToCloudAi() .calculateCost()
(graceful fallback) │
recordApiCall()
(Isar atomic write)
│
AiResult{text, model,
tokensUsed, costUsd}
| Layer | Technology | Why |
|---|---|---|
| UI Framework | Flutter 3.x + Material 3 | Cross-platform, Dynamic Color (Monet on Android 12+) |
| State Management | Riverpod 2.x (code gen @riverpod) |
Compile-safe providers, zero manual boilerplate |
| Local Database | Isar 3.x | Type-safe queries, native List<double> for embeddings, no migrations |
| Cloud AI | Gemini 1.5 Flash + Pro via Vercel proxy | Flash for cost, Pro for quality — routed by task type. Proxy keeps API key off the device |
| On-device AI | Gemma Nano (flutter_gemma, pending) | Zero cost, offline, private |
| Local AI Fallback | Extractive Dart algorithm | Zero dependencies, works on all platforms while Gemma matures |
| Charts | fl_chart 0.68 | Fully customizable LineChart + PieChart |
| Animations | flutter_animate 4.x | Declarative staggered animations, shimmer skeleton loading |
| Navigation | GoRouter 14.x | Declarative routing, deep-link ready |
| Theming | dynamic_color | Monet wallpaper-based color extraction |
| Preferences | shared_preferences | Persistent user settings (theme, budget cap, language) |
| Immutable data | freezed + json_serializable | Pattern-matching sealed classes, code-generated fromJson |
| Environment | flutter_dotenv | API keys in .env, never committed to source control |
- Create, edit, and organize notes with categories (Work, Ideas, Personal, Creative)
- Masonry grid layout with glassmorphic cards and staggered entrance animations
- Inline markdown formatting toolbar in the editor
| Action | Routes to | Notes |
|---|---|---|
| Summarize | Gemma Nano / Gemini Flash | Free for notes < 500 chars (extractive fallback) |
| Extract Tasks | Gemma Nano / Gemini Flash | Matches -, •, ✓, □, numbered lists |
| Change Tone | Gemini Pro | Professional rewrite — always generative |
| Expand Idea | Gemini Flash | Turns a short note into full paragraphs |
| Fix Grammar | Gemini Flash | Spell-check and grammar correction |
| Translate | Gemini Flash | 10 languages: EN, ES, FR, DE, PT, IT, ZH, JA, AR, RU |
| Format Text | Gemini Flash | Cleans up and converts to Markdown |
- Mood trend line chart over 7 days (fl_chart
LineChartwithFlSpotdata) - Topic distribution donut chart (fl_chart
PieChartwithTopicSlicedomain entities) - AI-generated highlight cards: growth patterns and burnout alerts
- Goals detected in notes with status tracking (in-progress / completed / at-risk)
- Recommendations and weekly summary generated by Gemini Pro
- Real-time budget chip:
AI Budget: $X.XXX / $10.00with warning color at $8.00 - Skeleton shimmer loading state (
flutter_animate .shimmer()) while Gemini Pro responds
- Every insight analysis is persisted as a JSON snapshot with timestamp
- Chronological history lets users compare how their notes evolve over time
- Theme mode (light / dark / system)
- Configurable budget cap and warning threshold
- Default translation language
- Number of notes to include in insights analysis
- Default note category
- Confirm-before-delete toggle
- Export notes and clear AI history
- Hard cap: $10.00 USD/month on cloud AI (
AppConstants.monthlyBudgetLimitUsd) - Warning threshold: $8.00 (
AppConstants.budgetWarningThresholdUsd) - Automatic local-only mode when cap is reached — enforced in
AIOrchestrator, not UI - Atomic Read-Modify-Write in
UsageRepositoryImpl.recordApiCall()to prevent race conditions
lib/
├── core/
│ ├── constants/
│ │ ├── app_constants.dart # AppConstants + AiTask enum (budget limits, thresholds)
│ │ └── api_constants.dart # Model IDs (gemini-1.5-flash, gemini-1.5-pro)
│ ├── errors/ # Base Failure + Exception sealed classes
│ ├── extensions/ # StringExtensions, ContextExtensions
│ └── utils/
│ ├── token_calculator.dart # TokenCalculator (cost math, pure static)
│ └── network_info.dart # Connectivity checking
│
├── domain/ # Pure Dart — zero framework dependencies
│ ├── entities/
│ │ ├── note.dart # Note entity (id, title, content, embeddings)
│ │ ├── ai_usage.dart # AiUsage (monthly tokens, costUsd, isBudgetExceeded)
│ │ └── insights_data.dart # InsightsData (moodHistory, topicDistribution, highlights,
│ │ # goals, recommendations, weeklySummary)
│ ├── repositories/
│ │ ├── note_repository.dart # Abstract NoteRepository interface
│ │ ├── ai_repository.dart # Abstract AiRepository (processLocal, processCloud)
│ │ └── usage_repository.dart # Abstract UsageRepository (isBudgetExceeded, record)
│ ├── failures/
│ │ └── failures.dart # Sealed Failure hierarchy (DatabaseFailure, AIFailure…)
│ └── usecases/
│ ├── ai_orchestrator.dart # AIOrchestrator — central routing engine
│ ├── summarize_note_usecase.dart
│ ├── extract_tasks_usecase.dart
│ ├── change_tone_usecase.dart
│ ├── expand_idea_usecase.dart
│ ├── fix_grammar_usecase.dart
│ ├── translate_usecase.dart
│ ├── format_text_usecase.dart
│ ├── generate_insights_usecase.dart
│ ├── get_notes_usecase.dart
│ ├── save_note_usecase.dart
│ └── delete_note_usecase.dart
│
├── data/
│ ├── datasources/
│ │ ├── local/
│ │ │ ├── isar_datasource.dart # IsarDataSource (CRUD + usage queries)
│ │ │ └── gemma_datasource.dart # GemmaDataSourceImpl (on-device + fallback)
│ │ └── remote/
│ │ └── gemini_datasource.dart # GeminiRemoteDataSource (via Vercel proxy)
│ ├── models/
│ │ ├── note_model.dart # @collection NoteModel with fromEntity/toEntity
│ │ ├── note_model.g.dart # Generated by isar_generator
│ │ ├── ai_usage_model.dart # @collection AiUsageModel
│ │ └── ai_usage_model.g.dart
│ └── repositories/
│ ├── note_repository_impl.dart # Concrete NoteRepository
│ ├── ai_repository_impl.dart # Concrete AiRepository (delegates to sources)
│ └── usage_repository_impl.dart # Concrete UsageRepository (Budget Guardian)
│
└── presentation/
├── screens/
│ ├── home_screen.dart # Masonry grid, CategoryFilterChip, AiMagicFab
│ ├── editor_screen.dart # TextField, MarkdownToolbar, AiOverlayMenu (7 actions)
│ ├── insights_screen.dart # Dashboard: MoodTrackerCard, TopicDonutChart, highlights
│ ├── folders_screen.dart # Chronological history of insight snapshots
│ └── settings_screen.dart # User preferences (theme, AI, notes, data, about)
├── widgets/
│ ├── note_card.dart
│ ├── category_filter_chip.dart
│ ├── ai_magic_fab.dart
│ ├── ai_overlay_menu.dart # 7 AI actions glassmorphic overlay
│ ├── markdown_toolbar.dart
│ ├── mood_tracker_card.dart
│ ├── topic_donut_chart.dart
│ ├── ai_highlight_card.dart
│ └── stat_card.dart
├── providers/
│ ├── notes_provider.dart # notesNotifierProvider, usageRepositoryProvider
│ ├── notes_provider.g.dart
│ ├── ai_provider.dart # aiOrchestratorProvider, all action notifiers
│ ├── ai_provider.g.dart
│ ├── settings_provider.dart # settingsProvider (SharedPreferences-backed)
│ └── settings_provider.g.dart
└── theme/
├── app_theme.dart # Material 3 ThemeData with dynamic_color
└── app_colors.dart # Seed color + semantic color tokens
- Flutter 3.x SDK (
flutter --version) - Android Studio or VS Code with the Flutter extension
- A Google AI Studio API key (get yours free)
- Android API 24+ recommended (for future Gemma Nano via Android AICore)
The app calls Gemini through a Vercel proxy. The backend repo is kept private to avoid exposing API keys. To run locally, deploy your own proxy or point
VERCEL_API_URLto a local server.
# 1. Clone the repository
git clone https://github.com/Hugo-Dev1/noteai.git
cd noteai/noteai
# 2. Configure environment variables
cp .env.example .env
# Edit .env:
# GEMINI_API_KEY=your_key_here
# VERCEL_API_URL=your_vercel_proxy_url
# VERCEL_API_SECRET=your_proxy_secret
# 3. Install dependencies
flutter pub get
# 4. Generate code (Riverpod providers + Isar schemas)
dart run build_runner build --delete-conflicting-outputs
# 5. Run the app
flutter runThe
.envfile is loaded byflutter_dotenvand declared as an asset inpubspec.yaml. It is listed in.gitignoreand must never be committed.
NoteAI is designed for near-zero monthly AI costs. Every cloud call is tracked in Isar and blocked when the $10 hard cap is reached.
| Scenario | Model Used | Estimated Cost |
|---|---|---|
| Summarize a short note (< 500 chars) | Extractive fallback (Dart) | $0.00 |
| Summarize a long note | Gemini 1.5 Flash | ~$0.00001 |
| Extract tasks from a note | Extractive fallback (Dart) | $0.00 |
| Change tone (professional) | Gemini 1.5 Flash | ~$0.00002 |
| Expand / Fix Grammar / Translate / Format | Gemini 1.5 Flash | ~$0.00001–$0.00003 |
| Generate insights (up to 20 notes) | Gemini 1.5 Pro | ~$0.001–$0.01 |
Pricing constants (sourced from TokenCalculator and AppConstants):
- Gemini 1.5 Flash: $0.075 / 1M input tokens, $0.30 / 1M output tokens
- Gemini 1.5 Pro: $1.25 / 1M input tokens, $5.00 / 1M output tokens
- Token estimation:
text.length / 4(standard 4-chars-per-token heuristic for English)
Realistic monthly estimate for daily use: < $1.00
flutter test200 tests — 200 passing — 0 failures across:
- Domain layer: use cases, AIOrchestrator routing logic
- Data layer: repository implementations, Budget Guardian
- Presentation: widget tests, provider state tests
All mocks are written by hand — no Mockito dependency.
CI runs on every push via .github/workflows/ci.yml:
- Security check (
.envnot committed) flutter analyze --fatal-infosflutter test
- Stable
flutter_gemmaintegration when Android AICore reaches broad availability - MediaPipe TextEmbedder for fully on-device semantic search (using stored
embeddingsfield inNoteModel) - Golden tests for all widgets
- Note export (PDF, Markdown)
- iPad / tablet responsive layout with adaptive navigation rail
NoteAI was built as a portfolio demonstration of senior-level Flutter engineering. Every major technical decision is documented with its rationale in DECISIONS.md.