How moffatman/chan works
1. Overall shape
- Chance is a Flutter client application targeting iOS, Android, desktop, and web.
- The core product is an imageboard browser: it fetches boards/threads/posts from multiple sites, renders them in a rich UI, and stores selected content locally.
2. Flutter app as the main runtime
- lib/main.dart and lib/main_desktop.dart are the top-level entry points for mobile and desktop variants.
- The UI is built mostly from Flutter pages/widgets, so the architecture is a classic presentation layer over a service/data layer rather than a server-backed app.
3. Feature-oriented UI layer
- lib/pages/ contains the main screens and flows: board browsing, thread view, search, gallery, history, saved content, settings, debugging tools, and tab management.
- lib/widgets/ holds reusable UI building blocks such as post rows, attachment viewers, reply boxes, drawers, context menus, adaptive controls, and media thumbnails.
- This split suggests the UI is organized around screen-level composition plus shared interaction components.
4. Site abstraction layer
- lib/sites/ is the major boundary between the app and the outside world.
- Each file represents an adapter for a specific imageboard/forum backend such as 4chan, 8kun, Futaba, LynxChan, Xenforo, Reddit, Hacker News, and others.
- These adapters normalize different site-specific HTML/JSON/API shapes into the app’s common models and behavior.
5. Shared domain models
- lib/models/ defines the core data objects: boards, threads, posts, attachments, flags, searches, and parent/child relationships.
- The generated *.g.dart files indicate code generation for serialization and persistence-friendly models.
- These models are the common contract used across site adapters, UI pages, and local storage.
6. Service layer as the app’s engine
- lib/services/ is where most non-UI behavior lives: HTTP, caching, storage, cookies, captcha solving, translation, filtering, notifications, sharing, media handling, and request interception.
- This layer likely mediates all external interactions: network requests go through HTTP/client helpers, responses get fixed up or parsed, and results are cached or persisted.
- Many services are platform-aware (android.dart, apple.dart, desktop/web-adjacent helpers), showing that the same feature set is adapted per OS.
7. Local state and persistence
- The app keeps substantial state locally: settings, history, saved posts/threads, outbox actions, thread watcher state, caches, and import/export data.
- Generated files like settings.g.dart, persistence.g.dart, thread_watcher.g.dart, and media.g.dart imply structured local storage, likely via a codegen-backed database or key-value store.
- This is important architecturally because the app is not purely request/response; it maintains offline state and background task state.
8. Media and attachment pipeline
- Attachments are a first-class subsystem: caching, thumbnail generation, viewer UI, image selection, web image picking, reverse image search, and video/audio handling are all present.
- Support for WEBM, MP4 streaming, thumbnailers, and media viewers suggests a dedicated media ingestion and rendering pipeline rather than simple image links.
- Attachments flow from site adapters into media services, then into gallery/thread UI components.
9. Captcha, browser, and web interaction
- The app includes multiple captcha handlers (captcha_*.dart), JavaScript challenge handling, cookie handling, embedded/cooperative browser views, and external URL launching.
- This means posting/replying is not just a simple form submit; it involves interactive web-session management for different sites and anti-bot systems.
- There are also helpers for auth pages, dark-mode browser behavior, and webview introspection.
10. Multi-platform native shells
- The repository contains full native wrappers for Android, iOS, macOS, Linux, Windows, and web.
- Android and iOS include Firebase configuration files, app manifests, launch assets, and in iOS a Share extension (ios/Share) for importing shared content into the app.
- The native layers mainly provide app lifecycle integration, platform permissions, sharing, and platform-specific UI/embedding.
11. Auxiliary native code
- iOS includes custom Swift helpers such as language recognition, translation helpers, async mutexes, and app delegate wrappers.
- Android has native Java entry points and test scaffolding, and desktop platforms have the standard Flutter embedder shells.
- These pieces are thin compared to lib/, but they matter for diagramming because they define the OS boundary and extension points.
12. Auxiliary Go module
- The go/ directory is a separate module with its own main.go, options, assets, and hover.yaml.
- It appears to be a supporting tool or bundled helper rather than the core app runtime, so it should be shown as an adjacent build/runtime component, not part of the Flutter UI pipeline.
13. Build-time generation and tooling
- The repo uses Dart code generation (build_runner) extensively, plus generated model/service/widget files.
- Tests are split into unit tests under test/ and integration/performance tests under integration_test/ and test_driver/.
- This matters because several architectural seams are codegen-driven, not hand-wired.
14. External dependencies and services
- Firebase is configured on Android/iOS and initialized from Dart via lib/firebase_options.dart.
- The app also depends on numerous external imageboard sites and archives, which are the real upstream data sources.
- Readme notes the app is often pointed at a test server by default, with settings controlling which board/site backend is used.
15. Primary data flow
- User action in a page/widget → service layer → site adapter / network / captcha / auth helper → parsed models → local cache/persistence → UI update.
- For saved or watched content, the flow extends into local storage, notification/background checking, and later retrieval from history/saved views.
- For posting/uploading, the flow includes attachment selection, media processing, cookie/session handling, and site-specific challenge solving before the request is submitted.
Main entry points: android.dart Platform glue · board.dart Pages · http_client.dart HTTP · post.dart Models
Components 21
Flutter app
Main Dart runtime and feature UI
- Main app · Primary Flutter entry point for mobile and web
lib/main.dart - Desktop app · Desktop-oriented Flutter entry point
lib/main_desktop.dart - Pages · Board, thread, search, gallery, history, saved, settings, debug, and tab screens
lib/pages/board.dart
Domain data
Shared models and generated contracts
- Models · Boards, threads, posts, attachments, search, flags, and relations
lib/models/post.dart
Site adapters
Per-backend normalization layer
- Site base · Common site abstraction and helpers
lib/sites/imageboard_site.dart - Site adapters · Backend-specific parsers and normalizers for many imageboards and forums
lib/sites/4chan.dart
Service engine
Networking, storage, media, auth, and background behavior
- HTTP · Request execution, retries, fixups, and logging
lib/services/http_client.dart - Persistence · Settings, cached state, history, watchers, and structured local storage
lib/services/persistence.dart - Media · Attachment caching, thumbnails, viewers, audio/video handling, and image helpers
lib/services/media.dart - Captcha · Captcha, JS challenge, browser, cookies, and auth-page helpers
lib/services/captcha.dart - Notifications · Thread watching, notifications, outbox, and background task coordination
lib/services/thread_watcher.dart - Share/import · Sharing, external launch, import/export, and posted-content exchange
lib/services/share.dart - Settings · User preferences and app configuration
lib/services/settings.dart - Platform glue · Platform-aware helpers for Android, Apple, desktop, and web behavior
lib/services/android.dart
UI widgets
Reusable presentation and interaction components
- Widgets · Reusable post, attachment, browser, drawer, and control widgets
lib/widgets/post_row.dart
Native shells
Platform-specific launchers and extensions
- Android shell · Android launcher, activity, manifest, and Firebase setup
android/app/src/main/java/com/moffatman/chan/MainActivity.java - iOS shell · iOS runner, app delegate, Swift helpers, and share extension
ios/Runner/AppDelegate.swift - macOS shell · macOS Flutter embedder and app wrapper
macos/Runner/AppDelegate.swift - Desktop shells · Linux and Windows Flutter embedders
linux/main.cc - Web shell · Web entry page, manifest, and splash assets
web/index.html
Aux tooling
Adjacent Go helper runtime
- Go helper · Separate Go module with its own command-line entry point
go/cmd/main.go
Connections 24
- Main app → Pages: builds · Main Flutter runtime composes the screen layer
- Desktop app → Pages: builds · Desktop entry also composes the screen layer
- Pages → Widgets: uses · Screens are assembled from shared UI components
- Pages → Models: reads/writes · Pages render and mutate domain objects
- Pages → Site base: queries · Screen flows request site-agnostic board/thread behavior
- Site base → Site adapters: implemented by · Concrete backend adapters provide the site contract
- Site adapters → HTTP: fetches via · Adapters use the network stack to load remote content
- Site adapters → Models: normalizes to · Backend payloads are converted into shared models
- HTTP → Captcha: triggers · Requests may require captcha or challenge resolution
- HTTP → Settings: configures · Network behavior is influenced by app settings
- HTTP → Platform glue: adapts through · Transport and platform-specific behavior is delegated
- Models → Persistence: stored in · Core entities are persisted for offline/local state
- Persistence → Notifications: feeds · Stored watcher and background state drives notifications
- Models → Media: contains · Attachments and related media metadata flow into media handling
- Media → Widgets: renders in · Thumbnails, viewers, and controls appear in UI widgets
- Captcha → Widgets: shown in · Interactive challenge UIs are embedded in widgets/pages
- Share/import → Persistence: imports/exports · Shared content and local data move through storage boundaries
- Share/import → Widgets: launches · Sharing and external navigation are initiated from the UI
- Platform glue → Android shell: bridges to · Android-specific helpers connect to the native shell
- Platform glue → iOS shell: bridges to · Apple-specific helpers connect to the native shell
- Platform glue → macOS shell: bridges to · macOS-specific helpers connect to the native shell
- Platform glue → Desktop shells: bridges to · Linux and Windows embedding uses platform glue
- Platform glue → Web shell: bridges to · Web-specific behavior is exposed through the browser host
- Go helper → Site adapters: adjacent · Separate Go module sits alongside the Flutter architecture