# moffatman/chan architecture

> Architecture diagram of the GitHub repository moffatman/chan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moffatman/chan
- Repository: https://github.com/moffatman/chan

## Overview

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: [`lib/services/android.dart`](https://github.com/moffatman/chan/blob/master/lib/services/android.dart) (Platform glue), [`lib/pages/board.dart`](https://github.com/moffatman/chan/blob/master/lib/pages/board.dart) (Pages), [`lib/services/http_client.dart`](https://github.com/moffatman/chan/blob/master/lib/services/http_client.dart) (HTTP), [`lib/models/post.dart`](https://github.com/moffatman/chan/blob/master/lib/models/post.dart) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter_app["Flutter app"]
  node_main_mobile["Main app<br/>Flutter entry<br/>[main.dart]"]
  node_main_desktop["Desktop app<br/>Flutter entry<br/>[main_desktop.dart]"]
  node_pages["Pages<br/>screen flows<br/>[board.dart]"]
end

subgraph group_domain_data["Domain data"]
  node_models[("Models<br/>[post.dart]")]
end

subgraph group_site_adapters["Site adapters"]
  node_site_base["Site base<br/>site interface"]
  node_site_adapters_set["Site adapters<br/>backend adapters<br/>[4chan.dart]"]
end

subgraph group_service_engine["Service engine"]
  node_http["HTTP<br/>network client<br/>[http_client.dart]"]
  node_persistence[("Persistence<br/>local state<br/>[persistence.dart]")]
  node_media["Media<br/>[media.dart]"]
  node_captcha["Captcha<br/>challenge handling<br/>[captcha.dart]"]
  node_notifications["Notifications<br/>watching"]
  node_share["Share/import<br/>sharing<br/>[share.dart]"]
  node_settings[("Settings<br/>config state<br/>[settings.dart]")]
  node_platform["Platform glue<br/>os adapters<br/>[android.dart]"]
end

subgraph group_ui_widgets["UI widgets"]
  node_widgets["Widgets<br/>ui components<br/>[post_row.dart]"]
end

subgraph group_native_shells["Native shells"]
  node_android_shell["Android shell<br/>native host<br/>[MainActivity.java]"]
  node_ios_shell["iOS shell<br/>native host<br/>[AppDelegate.swift]"]
  node_macos_shell["macOS shell<br/>native host<br/>[AppDelegate.swift]"]
  node_desktop_shells["Desktop shells<br/>native host<br/>[main.cc]"]
  node_web_shell["Web shell<br/>web host<br/>[index.html]"]
end

subgraph group_aux_tooling["Aux tooling"]
  node_go_tool["Go helper<br/>adjacent runtime<br/>[main.go]"]
end

node_main_mobile -->|"builds"| node_pages
node_main_desktop -->|"builds"| node_pages
node_pages -->|"uses"| node_widgets
node_pages -->|"reads/writes"| node_models
node_pages -->|"queries"| node_site_base
node_site_base -->|"implemented by"| node_site_adapters_set
node_site_adapters_set -->|"fetches via"| node_http
node_site_adapters_set -->|"normalizes to"| node_models
node_http -->|"triggers"| node_captcha
node_http -->|"configures"| node_settings
node_http -->|"adapts through"| node_platform
node_models -->|"stored in"| node_persistence
node_persistence -->|"feeds"| node_notifications
node_models -->|"contains"| node_media
node_media -->|"renders in"| node_widgets
node_captcha -->|"shown in"| node_widgets
node_share -->|"imports/exports"| node_persistence
node_share -->|"launches"| node_widgets
node_platform -->|"bridges to"| node_android_shell
node_platform -->|"bridges to"| node_ios_shell
node_platform -->|"bridges to"| node_macos_shell
node_platform -->|"bridges to"| node_desktop_shells
node_platform -->|"bridges to"| node_web_shell
node_go_tool -.->|"adjacent"| node_site_adapters_set

click node_main_mobile "https://github.com/moffatman/chan/blob/master/lib/main.dart"
click node_main_desktop "https://github.com/moffatman/chan/blob/master/lib/main_desktop.dart"
click node_pages "https://github.com/moffatman/chan/blob/master/lib/pages/board.dart"
click node_widgets "https://github.com/moffatman/chan/blob/master/lib/widgets/post_row.dart"
click node_models "https://github.com/moffatman/chan/blob/master/lib/models/post.dart"
click node_site_base "https://github.com/moffatman/chan/blob/master/lib/sites/imageboard_site.dart"
click node_site_adapters_set "https://github.com/moffatman/chan/blob/master/lib/sites/4chan.dart"
click node_http "https://github.com/moffatman/chan/blob/master/lib/services/http_client.dart"
click node_persistence "https://github.com/moffatman/chan/blob/master/lib/services/persistence.dart"
click node_media "https://github.com/moffatman/chan/blob/master/lib/services/media.dart"
click node_captcha "https://github.com/moffatman/chan/blob/master/lib/services/captcha.dart"
click node_notifications "https://github.com/moffatman/chan/blob/master/lib/services/thread_watcher.dart"
click node_share "https://github.com/moffatman/chan/blob/master/lib/services/share.dart"
click node_settings "https://github.com/moffatman/chan/blob/master/lib/services/settings.dart"
click node_platform "https://github.com/moffatman/chan/blob/master/lib/services/android.dart"
click node_android_shell "https://github.com/moffatman/chan/blob/master/android/app/src/main/java/com/moffatman/chan/MainActivity.java"
click node_ios_shell "https://github.com/moffatman/chan/blob/master/ios/Runner/AppDelegate.swift"
click node_macos_shell "https://github.com/moffatman/chan/blob/master/macos/Runner/AppDelegate.swift"
click node_desktop_shells "https://github.com/moffatman/chan/blob/master/linux/main.cc"
click node_web_shell "https://github.com/moffatman/chan/blob/master/web/index.html"
click node_go_tool "https://github.com/moffatman/chan/blob/master/go/cmd/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_mobile,node_main_desktop,node_pages,node_go_tool toneBlue
class node_models toneAmber
class node_site_base,node_site_adapters_set toneMint
class node_http,node_persistence,node_media,node_captcha,node_notifications,node_share,node_settings,node_platform toneRose
class node_widgets toneIndigo
class node_android_shell,node_ios_shell,node_macos_shell,node_desktop_shells,node_web_shell toneTeal
```

## Components

### Flutter app

Main Dart runtime and feature UI

- [Main app](https://github.com/moffatman/chan/blob/master/lib/main.dart): Flutter entry · Primary Flutter entry point for mobile and web · `lib/main.dart`
- [Desktop app](https://github.com/moffatman/chan/blob/master/lib/main_desktop.dart): Flutter entry · Desktop-oriented Flutter entry point · `lib/main_desktop.dart`
- [Pages](https://github.com/moffatman/chan/blob/master/lib/pages/board.dart): screen flows · Board, thread, search, gallery, history, saved, settings, debug, and tab screens · `lib/pages/board.dart`

### Domain data

Shared models and generated contracts

- [Models](https://github.com/moffatman/chan/blob/master/lib/models/post.dart): domain models · Boards, threads, posts, attachments, search, flags, and relations · `lib/models/post.dart`

### Site adapters

Per-backend normalization layer

- [Site base](https://github.com/moffatman/chan/blob/master/lib/sites/imageboard_site.dart): site interface · Common site abstraction and helpers · `lib/sites/imageboard_site.dart`
- [Site adapters](https://github.com/moffatman/chan/blob/master/lib/sites/4chan.dart): backend 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](https://github.com/moffatman/chan/blob/master/lib/services/http_client.dart): network client · Request execution, retries, fixups, and logging · `lib/services/http_client.dart`
- [Persistence](https://github.com/moffatman/chan/blob/master/lib/services/persistence.dart): local state · Settings, cached state, history, watchers, and structured local storage · `lib/services/persistence.dart`
- [Media](https://github.com/moffatman/chan/blob/master/lib/services/media.dart): media pipeline · Attachment caching, thumbnails, viewers, audio/video handling, and image helpers · `lib/services/media.dart`
- [Captcha](https://github.com/moffatman/chan/blob/master/lib/services/captcha.dart): challenge handling · Captcha, JS challenge, browser, cookies, and auth-page helpers · `lib/services/captcha.dart`
- [Notifications](https://github.com/moffatman/chan/blob/master/lib/services/thread_watcher.dart): watching · Thread watching, notifications, outbox, and background task coordination · `lib/services/thread_watcher.dart`
- [Share/import](https://github.com/moffatman/chan/blob/master/lib/services/share.dart): sharing · Sharing, external launch, import/export, and posted-content exchange · `lib/services/share.dart`
- [Settings](https://github.com/moffatman/chan/blob/master/lib/services/settings.dart): config state · User preferences and app configuration · `lib/services/settings.dart`
- [Platform glue](https://github.com/moffatman/chan/blob/master/lib/services/android.dart): os adapters · Platform-aware helpers for Android, Apple, desktop, and web behavior · `lib/services/android.dart`

### UI widgets

Reusable presentation and interaction components

- [Widgets](https://github.com/moffatman/chan/blob/master/lib/widgets/post_row.dart): ui components · Reusable post, attachment, browser, drawer, and control widgets · `lib/widgets/post_row.dart`

### Native shells

Platform-specific launchers and extensions

- [Android shell](https://github.com/moffatman/chan/blob/master/android/app/src/main/java/com/moffatman/chan/MainActivity.java): native host · Android launcher, activity, manifest, and Firebase setup · `android/app/src/main/java/com/moffatman/chan/MainActivity.java`
- [iOS shell](https://github.com/moffatman/chan/blob/master/ios/Runner/AppDelegate.swift): native host · iOS runner, app delegate, Swift helpers, and share extension · `ios/Runner/AppDelegate.swift`
- [macOS shell](https://github.com/moffatman/chan/blob/master/macos/Runner/AppDelegate.swift): native host · macOS Flutter embedder and app wrapper · `macos/Runner/AppDelegate.swift`
- [Desktop shells](https://github.com/moffatman/chan/blob/master/linux/main.cc): native host · Linux and Windows Flutter embedders · `linux/main.cc`
- [Web shell](https://github.com/moffatman/chan/blob/master/web/index.html): web host · Web entry page, manifest, and splash assets · `web/index.html`

### Aux tooling

Adjacent Go helper runtime

- [Go helper](https://github.com/moffatman/chan/blob/master/go/cmd/main.go): adjacent runtime · Separate Go module with its own command-line entry point · `go/cmd/main.go`

## Connections

- 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
