Architecture

System context

macOS desktop UI (side-panel)
   |-> OS-native OCR + screen capture
   |-> ConnectRPC over HTTP/2
   v
Raven backend (services/raven)

Code structure

lib/
  app/            App shell, router, themes, window chrome
  common/         Shared logging + widgets
  env/            Build-time environment (Envied)
  features/       Feature modules (auth, home, ocr, overlay, updates, ...)
  gen/            Generated ConnectRPC + protobuf stubs
  providers/      Cross-cutting Riverpod providers (theme, etc.)
  services/       Shared services (auth interceptor, statsig, auto-update)

Feature layout conventions

Most features follow a consistent layout:

features/<feature>/
  models/        Typed state + request models
  providers/     Riverpod controllers and derived state
  services/      Business logic / integrations
  ui/            Pages and widgets

The OCR feature also includes notifications/ for secondary windows.

Feature modules

• features/auth/: login, SSO, auth providers, and client integration.
• features/ocr/: OCR capture + state machine + notifications.
• features/overlay/: side-panel window behavior and tray integration.
• features/home/: search UI and result rendering.
• features/settings/, features/updates/, features/onboarding/.

App startup sequence

• lib/main.dart initializes windowing, Statsig, auto-updater, and Firebase.
• Release builds enable Sentry and wrap the app with SentryWidget.
• lib/app/app.dart wires the ShadApp shell, theme, and go_router.
• _EagerInitialization initializes tray, OCR background, and notifications.

Routing and windowing

• go_router handles auth, onboarding, and main routes.
• Secondary windows (OCR notifications, update prompts) use desktop_multi_window with typed launch arguments.
• Overlay window behavior is coordinated in features/overlay/.

State management

• Riverpod (flutter_riverpod) with feature-scoped providers in features/*/providers/ and shared providers in lib/providers/.
• UI reads providers via ConsumerWidget and NotifierProvider (e.g., OCR).
• Debug builds attach a RavenProviderObserver for provider change logging.

Networking and storage

• ConnectRPC over HTTP/2 with protobuf stubs in lib/gen/.
• auth_interceptor attaches Firebase tokens to ConnectRPC requests.
• Session state persists in flutter_secure_storage.
• Settings and last-login metadata use SharedPreferences.

Error handling

• Central logging via lib/common/logger.dart.
• Sentry enabled in release builds for crash + performance reporting.
• OCR errors are normalized through OcrErrorMapper and surfaced in OcrStatus.
• ConnectRPC auth uses an interceptor to attach Firebase tokens and logs failures.

UI libraries

• shadcn_ui for core components and theming (ShadApp / ShadTheme).
• lucide_icons_flutter + font_awesome_flutter for iconography.
• mesh_gradient for background effects.

Key integrations

• Raven backend (services/raven/).
• macOS system APIs for OCR and screen capture.
• Firebase Auth for user sessions.
• Statsig and Sentry for telemetry and experiments.