Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pubspec.yaml
• packages/conduit_core/pubspec.yaml
• packages/conduit_markdown/pubspec.yaml
• tool/platform_ui_allowlist.yaml
• scripts/release.sh

Conduit is a native mobile client for Open WebUI, model endpoints, and self-hosted agents. It uses Flutter to provide a native interface across iOS and Android, connecting directly to backends without developer-operated relays. The system architecture emphasizes local-first storage, secure credential management, and multi-platform compatibility through a modular package structure.

Sources: README.md:1-15, pubspec.yaml:1-5

Modular Package Structure

The project uses a Flutter workspace to manage multiple internal packages. This structure separates the core business logic from the UI rendering and platform-specific implementations.

Package	Purpose
conduit	The root Flutter mobile application. It handles UI, navigation, and platform integrations.
conduit_core	Contains business logic including authentication, API clients, streaming, and database management. It is written in pure Dart to remain portable.
conduit_markdown	Handles Markdown preprocessing and custom syntaxes. It transforms model output into block models for rendering.
conduit_theme	Manages shared design tokens and theming components for the application.
conduit_ddgs	Provides on-device web search capabilities for direct model connections.

Sources: pubspec.yaml:12-20, packages/conduit_core/pubspec.yaml:1-6, packages/conduit_markdown/pubspec.yaml:1-6

Dependency Graph

This diagram shows the relationship between the main application and its internal library dependencies.

The root application depends on all specialized packages, while conduit_core acts as the primary logic hub for searching and parsing.
Sources: pubspec.yaml:26-34, packages/conduit_core/pubspec.yaml:30-36

Connection Architecture

Conduit supports multiple backend types through a unified connection interface. Each connection type utilizes different protocols and authentication paths.

• Open WebUI: Full server integration using WebSocket for token streaming. Supports LDAP, SSO, and OAuth via reverse proxy cookie capture.
• Direct Connections: Connects to OpenAI-compatible endpoints, Ollama, or OpenRouter using standard REST/streaming APIs.
• On-Device Models: Utilizes Apple's SystemLanguageModel on eligible iOS devices for offline processing.
• Hermes Agent: Connects to specialized agent servers to run tools and scheduled tasks.

Sources: README.md:52-85, packages/conduit_core/pubspec.yaml:17-25

Data Flow for Chat Streaming

The following sequence illustrates how a message is sent and a response is received via WebSocket.

Conduit maintains UI responsiveness by processing streams in conduit_core and updating the transcript incrementally.
Sources: README.md:126-130, packages/conduit_core/pubspec.yaml:48-55

Security and Privacy Model

Conduit implements a "local-first" privacy model. No data routes through a developer-managed backend.

• Credential Storage: Uses platform-native secure storage (iOS Keychain and Android Keystore) via flutter_secure_storage.
• Local Persistence: Conversations, notes, and drafts are stored on the device using hive_ce and drift.
• Network Isolation: All traffic flows directly from the mobile device to the user's configured server.

Sources: README.md:310-320, pubspec.yaml:63-68

UI and Rendering System

The UI is built using native Flutter surfaces rather than web views. It utilizes an allowlist-based approach to manage platform-specific UI components (Material vs. Cupertino).

• Markdown Rendering: conduit_markdown parses content, which is then rendered with syntax highlighting, Mermaid diagrams, and LaTeX.
• Platform Seams: The platform_ui_allowlist.yaml manages the usage of material_ui and cupertino_ui to ensure adaptive interfaces across platforms.
• Advanced Components: Includes Chart.js embeds, interactive terminals over WebSocket, and native workspace management screens.

Sources: README.md:135-150, tool/platform_ui_allowlist.yaml:1-20, packages/conduit_markdown/pubspec.yaml:15-18

Release and Versioning Logic

The project uses CI-driven scripts to manage versions and release assets. Versioning is synchronized across the workspace via the root pubspec.yaml.

• Build Numbering: Automatically incremented during the release process.
• Platform Assets: Generates Fastlane changelogs for Android and updates the Deliverfile for iOS app versions.
• Verification: Validates release notes using internal tools before tagging.

Sources: scripts/release.sh:110-155, pubspec.yaml:4

Conduit's architecture ensures high portability of business logic through pure Dart packages while delivering a rich, native mobile experience through Flutter's adaptive UI framework.