Architecture

Clean, layered Flutter architecture with clear separation of concerns.

Overview

The Everything App follows a layered architecture pattern that separates the codebase into distinct responsibilities. Each layer depends only on the layer below it, preventing circular dependencies and making the code testable in isolation.

┌──────────────────────────────────────────────────────┐
│                    Views Layer                        │
│  HomeScreen · LoginScreen · StatsScreen · Widgets     │
│  (StatelessWidget / StatefulWidget — UI only)         │
├──────────────────────────────────────────────────────┤
│                   State Layer                         │
│    EventProvider (ChangeNotifier) — primary state      │
│    EventBloc (Cubit) — alternative BLoC pattern        │
│    UserProvider (ChangeNotifier) — user session         │
├──────────────────────────────────────────────────────┤
│                  Services Layer                        │
│  EventService — coordinates persistence + state        │
│  AuthService — Firebase Auth wrapper                   │
│  GraphService — Microsoft Graph API client             │
├──────────────────────────────────────────────────────┤
│                   Data Layer                           │
│  LocalStorage — SQLite singleton (sqflite)             │
│  EventRepository · UserRepository — CRUD operations    │
├──────────────────────────────────────────────────────┤
│                  Models Layer                          │
│  EventModel · EventTag · RecurrenceRule · UserModel    │
│  (Immutable, with copyWith, fromJson/toJson)           │
└──────────────────────────────────────────────────────┘

Layer Responsibilities

Models

Pure Dart classes with no Flutter dependencies. All models are designed to be:

Immutable — fields are final, mutations use copyWith()
Serializable — fromJson() / toJson() for SQLite and API
Value-equatable — overridden == and hashCode

📋 EventModel

Core event with id, title, description, date, priority, tags, and recurrence. Generates recurring occurrences via generateOccurrences().

🏷️ EventTag

Color-coded categorization with 8 preset colors and common tag presets (Work, Personal, Meeting, etc.).

🔄 RecurrenceRule

Daily/weekly/monthly/yearly recurrence with configurable intervals and optional end dates. Handles month-length clamping (Jan 31 + 1 month = Feb 28).

👤 UserModel

User identity with id, name, and email. Persisted to local storage for session restoration.

Data Layer

The data layer handles all persistence through two components:

LocalStorage — Singleton SQLite manager with versioned schema migrations (v1→v4). All queries use parameterized bindings to prevent SQL injection.
Repositories — Thin wrappers around LocalStorage that provide domain-specific CRUD operations (EventRepository, UserRepository).

Schema Versions v1: Basic users + events tables. v2: Added description + priority. v3: Added tags (JSON). v4: Added recurrence (JSON). Each migration is applied incrementally via onUpgrade.

Services Layer

Services coordinate between the data layer and state layer:

EventService — The single point of coordination for all event mutations. Updates in-memory state first (for responsiveness), then persists to disk asynchronously. Persistence errors are logged but don't crash the UI.
AuthService — Wraps Firebase Auth with typed AuthException errors. Maps Firebase error codes to human-readable identifiers.
GraphService — Microsoft Graph API client with paginated event fetching. Includes SSRF protection — pagination links are validated against trusted hosts.

State Layer

Two state management approaches coexist:

Pattern	Implementation	Use Case
Provider	`EventProvider`, `UserProvider`	Primary UI state — O(1) indexed lookups, unmodifiable list exposure
BLoC	`EventBloc` (Cubit)	Alternative pattern — state machine with `EventInitial`, `EventLoaded`, `EventError` states

Views Layer

Flutter widgets that consume state and render UI. No business logic lives here — widgets delegate all mutations to services/providers.

Data Flow

Authentication Flow

App Start → Firebase.initializeApp()
         → AuthGate (StreamBuilder on authStateChanges)
            ├─ User exists → restore UserProvider → HomeScreen
            └─ No user → LoginScreen
                          → AuthService.loginWithEmail()
                          → Firebase Auth
                          → UserProvider.setUser() + UserRepository.saveUser()
                          → Navigate to HomeScreen

Event CRUD Flow

UI Action (e.g., "Add Event")
  → EventService.addEvent(event)
    → EventProvider.addEvent()     ← in-memory (instant UI update)
    → EventRepository.saveEvent()  ← async persistence (fire-and-forget)
  → UI rebuilds via ChangeNotifier

Microsoft Graph Sync Flow

User triggers sync
  → GraphService.fetchCalendarEvents(accessToken)
    → GET /me/events?$top=50
    → Follow @odata.nextLink (validated against trustedApiHosts)
    → Collect all pages (max 50 pages safety limit)
  → Map to EventModel list
  → EventService.setEvents() / merge

Key Design Patterns

🏭 Singleton Database

LocalStorage._db ensures only one database connection exists. Lazy-initialized on first access.

📇 O(1) Index Map

EventProvider._idIndex maps event IDs to list indices, enabling constant-time lookups, updates, and deletions.

🔥 Fire-and-Forget Persistence

EventService updates in-memory state first for instant UI response, then persists asynchronously. Disk errors are logged, not surfaced.

🛡️ Typed Exceptions

AuthException, HttpException, HttpSecurityException, GraphServiceException — each error type carries structured context for proper handling.