Xolo Architecture: Layered Flutter Design

Xolo is built around a strict separation of concerns: each layer has a single responsibility, depends only on the layers below it, and exposes a well-defined contract. This boundary discipline makes every module independently testable, keeps the UI free of database types, and lets the data implementation be swapped without touching a single widget. The application boots from a single ProviderScope in main.dart, and every dependency — database, HTTP client, auth services, navigation — flows through Riverpod providers.

The Four Layers

Core
Domain
Data
Presentation

The Core layer provides infrastructure that every other layer can use without depending on Flutter’s widget tree. It never imports from domain, data, or presentation.Router — app_router.dartNavigation is handled by go_router (^15.1.2). The appRouter instance is a GoRouter that wraps all main routes inside a ShellRoute backed by HomeShell. AppRoutes is an abstract final class of typed path constants:

abstract final class AppRoutes {
  static const explorer    = '/';
  static const history     = '/history';
  static const composer    = '/composer';
  static const sync        = '/sync';
  static const environments = '/environments';
  static const settings    = '/settings';
  static const runActive   = '/runs/active';
  static const runHistory  = '/runs';
  static const runReport   = '/runs/report';
}

Helper functions (routeForTabIndex, tabIndexForRoute, railIndexForRoute, routeForRailIndex) translate between numeric navigation-rail/bottom-nav indices and route paths, keeping navigation logic out of widgets entirely.Theme — XoloPremiumTheme & XoloDesignTokensXoloPremiumTheme exposes darkTheme(int) and lightTheme(int) factory methods that return fully configured ThemeData objects using Material 3. Both themes set Inter as the body font and JetBrains Mono for code/URL fields via google_fonts. The dark theme uses XoloPalette.black (#000000) as the scaffold background; the light theme uses XoloPalette.lightBg (#FAFAFA).XoloDesignTokens (xolo_design_tokens.dart) centralises every visual constant:

XoloSpacing — xs (4), sm (8), md (12), lg (16), xl (24), xxl (32)
XoloRadius — sm (8 px), md (12 px), lg (16 px) as both double values and pre-built BorderRadius instances
XoloPalette — named colour constants for both dark (base, raised, hover, line, text, accent) and light (lightBg, lightSurface, lightLine) surfaces
XoloMotion — fast (120 ms) and normal (200 ms) animation durations
XoloLayout — railWidth (72), urlBarHeight (56), sectionTabHeight (48), requestTabHeight (40)
XoloSurfaces — panel() and card() factory methods that return BoxDecoration instances consistent with the active ColorScheme
XoloTypography — typed TextStyle factories: sectionLabel, cardTitle, cardSubtitle, meta
XoloA11y — minTouchTarget (44) for WCAG-compliant tap targets

Network — HttpClientProvider & RequestPipelinedioProvider creates a Dio instance configured with 15 s connect, 30 s receive, and 30 s send timeouts. An InterceptorsWrapper logs every request and response through AppLogger. The error handler applies an automatic retry strategy: idempotent methods (GET, HEAD, OPTIONS) are retried up to twice on 429/5xx responses and on transient connection errors, with a back-off of 300 ms × (attempt + 1).RequestPipeline is a plain Dart class (registered as requestPipelineProvider) that encapsulates the full HTTP execution path shared by the Composer screen and CollectionRunnerService. It resolves {{variables}} in URLs, headers, and bodies via VariableParser, resolves auth inheritance via AuthResolverService, refreshes OAuth 2.0 tokens when needed, and injects Authorization headers for bearer, oauth2, basic, and api_key auth types. It returns a RequestOutput value object with statusCode, durationMs, resolvedUrl, data, error, and cancelled fields.Services

Service	Responsibility
`AppLogger`	Debug-only logger with automatic redaction of `authorization`, `token`, `password`, `secret`, `client_secret`, and `api_key` values
`EncryptionService`	AES encryption for cloud backup payloads
`OAuth2Service`	Authorization Code + PKCE flow with embedded ephemeral local server for token exchange; `maybeRefreshOAuth2AuthData` refreshes stale tokens transparently
`BiometricService`	FaceID/Fingerprint lock via `local_auth`; checks `shouldLockOnColdStart()` and `shouldLockApp()` based on configurable policy
`CloudService` / `CloudSyncService`	Google Drive–backed encrypted sync
`AuthSecretService`	Migrates legacy plain-text auth data from the database to `flutter_secure_storage`
`AuthResolverService`	Walks the collection tree to find the effective auth config for a request, respecting the `inherit` auth type

Config — AppConfig & SecureStorageAppConfig is an immutable value class holding schemaVersion, themeModeDefault, allowAbsoluteUrl, and a featureFlags map. It is loaded by appConfigProvider (FutureProvider) from two settings keys: app_config_runtime (server-pushed overrides) and app_config_user_override (local user preferences), merged over compiled defaults. Sensitive credentials are stored separately in flutter_secure_storage.

The Domain layer contains the application’s business logic and data contracts. It has no Flutter dependencies and no Drift imports — only pure Dart. This constraint is what makes every domain class fully unit-testable without a device or database.Repository ContractXoloRepository is an abstract class that defines every data operation the application needs. DriftXoloRepository in the Data layer provides the only production implementation. Tests substitute a mock or an in-memory implementation without touching a single widget.Domain EntitiesAll entities are immutable const-constructible Dart classes:

CollectionEntity — represents a project or folder node in the collection tree
SavedRequestEntity — a persisted HTTP request with metadata fields including preScriptsJson, scriptsJson, and assertionsJson
EnvironmentEntity — a named variable scope belonging to a workspace
EnvVariableEntity — a key/value variable with scope (env or global) and optional environmentId/collectionId bindings
HistoryEntryEntity — a single executed-request record with timing and response snapshot
AssertionRuleEntity / AssertionResultEntity — declarative test rules and their evaluated results
CollectionRunEntity — a completed or in-progress collection run with aggregate pass/fail/skip counters
RunStepResultEntity — the per-request result within a run, including assertion results and extracted variables

Pure ServicesRunPlanBuilder, CollectionRunnerService, and AssertionEvaluator live in lib/domain/services/ and have no Flutter or Drift dependencies.

The Data layer owns everything related to SQLite persistence. It depends on Core (for AppLogger) and Domain (for entity types and the XoloRepository contract), but Presentation never imports from it directly.AppDatabase is the Drift-generated database class. Schema version is currently 8. All SQL logic is factored into focused query files that are part of 'database.dart':

collection_queries.dart
environment_queries.dart
history_queries.dart
run_queries.dart
settings_queries.dart

DriftXoloRepository implements XoloRepository by delegating every call to AppDatabase and mapping the raw Drift row types to domain entities via entity_mappers.dart.entity_mappers.dart defines Dart extension methods on every Drift row type (e.g. CollectionEntityMapper on Collection) so that .toEntity() is available everywhere and mapping logic is co-located with the types it converts.Import/Sync Services in lib/data/services/ handle Postman collection import and Google Drive sync. These services access AppDatabase directly because their bulk-write patterns do not fit the XoloRepository CRUD contract.

The Presentation layer contains all Flutter screens, widgets, and Riverpod providers. It depends on Domain (entities and XoloRepository) but never imports from data/local/ or data/repositories/ directly.Screens are organised under lib/presentation/screens/:

Screen	Route
`ActiveWorkspaceExplorer`	`/`
`HistoryScreen`	`/history`
`ComposerScreen`	`/composer`
`SyncScreen`	`/sync`
`EnvironmentsScreen`	`/environments`
`SettingsScreen`	`/settings`
`CollectionRunScreen`	`/runs/active`
`RunHistoryScreen`	`/runs`
`RunReportScreen`	`/runs/report/:runId`

Providers in lib/presentation/providers/ expose reactive streams to widgets. xoloRepositoryProvider is the root Provider<XoloRepository> used by all other data providers. databaseProvider creates AppDatabase and registers db.close as the dispose callback.Biometric Lock is implemented as an overlay: XoloApp.build watches isAppLockedProvider and stacks BiometricLockScreen over the entire navigator when the app is locked.

State Management

Xolo uses flutter_riverpod ^3.1.0. The entire app is wrapped in a single ProviderScope at the root of main(). Provider types in use:

Provider Type	Usage
`Provider<T>`	Synchronous singleton services — `databaseProvider`, `xoloRepositoryProvider`, `dioProvider`, `requestPipelineProvider`, all service providers
`StateProvider<T>`	Simple mutable state — `themeModeProvider`, `isAppLockedProvider`
`StreamProvider<T>`	Reactive database streams — collections, history, environments, runs, settings
`NotifierProvider<N, T>`	Complex stateful logic with side effects — Composer state, active run state
`FutureProvider<T>`	One-shot async resolution — `appConfigProvider`

xoloRepositoryProvider is the single entry point for all persistent data access in the presentation layer. Every StreamProvider that watches a database collection calls ref.watch(xoloRepositoryProvider) first.

Navigation is driven by go_router. All routes are nested inside a ShellRoute that renders HomeShell, which provides the adaptive navigation shell (bottom navigation bar on phones, navigation rail on tablets/desktop).

final appRouter = GoRouter(
  initialLocation: AppRoutes.explorer,
  routes: [
    ShellRoute(
      builder: (context, state, child) => HomeShell(child: child),
      routes: [
        GoRoute(path: '/',               /* ActiveWorkspaceExplorer */ ),
        GoRoute(path: '/history',        /* HistoryScreen           */ ),
        GoRoute(path: '/composer',       /* ComposerScreen          */ ),
        GoRoute(path: '/sync',           /* SyncScreen              */ ),
        GoRoute(path: '/environments',   /* EnvironmentsScreen      */ ),
        GoRoute(path: '/settings',       /* SettingsScreen          */ ),
        GoRoute(path: '/runs/active',    /* CollectionRunScreen     */ ),
        GoRoute(path: '/runs',           /* RunHistoryScreen        */ ),
        GoRoute(path: '/runs/report/:runId', /* RunReportScreen     */ ),
      ],
    ),
  ],
);

All pageBuilder callbacks return NoTransitionPage to eliminate route transition animations, keeping navigation feel instant.

Tech Stack

Layer	Technology
Framework	Flutter 3.x
State Management	Riverpod (`flutter_riverpod ^3.1.0`)
Navigation	go_router (`^15.1.2`)
Local Persistence	Drift (`^2.26.0`) — Reactive SQLite
Networking	Dio (`^5.9.0`)
Fonts	google_fonts — Inter + JetBrains Mono
Secure Storage	flutter_secure_storage (`^10.0.0`)
Biometrics	local_auth (`^3.0.0`)
OAuth 2.0	Native implementation via http + embedded local server
JSONPath	json_path (`^0.7.1`)
Cloud Sync	googleapis + google_sign_in
Encryption	encrypt (`^5.0.3`) + crypto
CI/CD	GitHub Actions

Explore Further

Data Layer

Deep-dive into the Drift schema, DriftXoloRepository, entity mappers, migrations, and reactive query patterns.

Domain Layer

Explore XoloRepository’s full method contract, every domain entity, and the pure testable services that orchestrate collection runs and assertion evaluation.

Project Structure

Contributing

Xolo Architecture: Layered Flutter Design

The Four Layers

State Management

Navigation

Tech Stack

Explore Further

Data Layer

Domain Layer

Build docs developers (and LLMs) love

Project Structure

Contributing

Documentation Index

​The Four Layers

​State Management

​Navigation

​Tech Stack

​Explore Further

Data Layer

Domain Layer

Build docs developers (and LLMs) love

The Four Layers

State Management

Navigation

Tech Stack

Explore Further