# zeshuaro/appainter architecture

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

- Interactive diagram: https://gitdiagram.com/zeshuaro/appainter
- Repository: https://github.com/zeshuaro/appainter

## Overview

##### Project Type and Purpose
- Appainter is an open-source, multi-platform Flutter application (Web, Desktop, Mobile) that provides a visual, interactive editor for Material themes and generates Dart/JSON theme code.
- It is structured as a monorepo:
– The “app” itself under lib/, android/, ios/, linux/, macos/, windows/, web/
– An example/sandbox app under example/
– Two internal packages under packages/ (annotations & builder) for code-generation

##### Top-Level Architecture Components
A. Presentation Layer (Flutter UI)
– Home Screen (lib/home/…)
– Individual Theme Editors (e.g. lib/color_theme/, lib/text_theme/, lib/button_theme/, etc.)
– Theme Preview Pages (lib/theme_preview/views/)
– Common Widgets (lib/widgets/)
– Navigation (BottomNavigationBar, Drawer, etc.)
B. State Management Layer
– One Cubit per theme area (e.g. ColorThemeCubit, ButtonThemeCubit, TextThemeCubit…)
– Global App Cubit / Bloc Observer (lib/bloc_observer.dart)
C. Core Services & Models
– Theme models & enums (lib/models/, lib/common/)
– Services: Theme export, file I/O, analytics, authentication (lib/services/, lib/analytics/, lib/authentication/)
– Utilities and extensions (lib/utils/)
D. Code-Generation Layer
– Annotations Package (packages/annotations): defines metadata annotations for theme docs
– Builder Package (packages/builder): build_runner builder that scans annotations + theme models to emit generated code, docs, JSON
– build_runner integration (pubspec.yaml & build.yaml)
E. Platform Integration
– Flutter Engine & Plugins (android/, ios/, linux/, macos/, windows/, web/)
– Platform-specific entrypoints and resources
F. Example App
– Shows how to integrate the generated theme in a real Flutter app (example/lib/main.dart + example assets)
G. CI/CD & Tooling
– GitHub Actions workflows (.github/workflows/) for tests, build, publish
– FVM for Flutter version management (.fvm/)
– build.sh and JS configs for release automation

##### Relationships and Data Flows
1. User interacts with Presentation Layer → UI widgets dispatch events to the corresponding Cubit.
2. Cubit processes events → updates its ThemeState (immutable model).
3. ThemeState → fed into Theme Preview widgets to re-render live previews.
4. When “Export” is triggered → Export Service serializes theme to JSON / in-memory model.
5. build_runner (Builder) reads annotations on model classes + JSON → emits Dart source & documentation.
6. Generated code can be imported into the user’s Flutter project (shown in Example App).
7. Analytics & Authentication services may log usage or gate premium features.

##### Architectural Patterns & Principles
- Layered architecture (Presentation → State → Services → Generation)
- Separation of Concerns via Cubit pattern (one Cubit per theme domain)
- Modularity & Extensibility: add a new theme by creating its own cubit, view, model, and annotating it for the Builder.
- Code generation for DRY and up-to-date docs/exports.
- Platform-agnostic UI, deployment per Flutter’s multi-platform approach.

##### Detailed Coverage
– Show shared utilities and common services centrally.
– Emphasize the Example App as a consumer of both the main app UI and the generated theme library.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer" 
    direction TB
    Home["Home Screen"]:::presentation
    ColorEditor["Color Theme Editor"]:::presentation
    TextEditor["Text Theme Editor"]:::presentation
    ButtonEditor["Button Theme Editor"]:::presentation
    Preview["Theme Preview Pages"]:::presentation
    Widgets["Common Widgets"]:::presentation
  end

  %% State Management Layer
  subgraph "State Management Layer"
    direction TB
    BlocObserver["Global Bloc Observer"]:::state
    ColorCubit["ColorThemeCubit"]:::state
    TextCubit["TextThemeCubit"]:::state
    ButtonCubit["ButtonThemeCubit"]:::state
  end

  %% Core Services & Models
  subgraph "Core Models & Services"
    direction TB
    Models["Core Models & Enums"]:::services
    CommonExt["Common Extensions & Consts"]:::services
    ExportService["Export & File I/O Service"]:::services
    Analytics["Analytics Service"]:::services
    Auth["Authentication Service"]:::services
    Utils["Utilities & Extensions"]:::services
  end

  %% Code-Generation Layer
  subgraph "Code-Generation Layer"
    direction TB
    Annotations["Annotations Package"]:::codegen
    BuilderLib["Builder Package"]:::codegen
    BuildYAML["build.yaml"]:::codegen
    BuildRunner["build_runner"]:::codegen
    Generated["Generated Dart Code & Docs"]:::codegen
  end

  %% Platform Integration
  subgraph "Platform Integration"
    direction TB
    Android["Android"]:::platform
    iOS["iOS"]:::platform
    Linux["Linux"]:::platform
    MacOS["macOS"]:::platform
    Windows["Windows"]:::platform
    Web["Web"]:::platform
  end

  %% Example App
  subgraph "Example App"
    direction TB
    ExampleMain["Main Entrypoint"]:::example
    ExampleAssets["Example Assets"]:::example
  end

  %% CI/CD & Tooling
  subgraph "CI/CD & Tooling"
    direction TB
    Workflows["GitHub Actions Workflows"]:::tooling
    FVM["FVM Config"]:::tooling
    ReleaseScripts["Release Automation Scripts"]:::tooling
  end

  %% Data Flows
  Home -->|navigates to| ColorEditor
  Home -->|navigates to| TextEditor
  Home -->|navigates to| ButtonEditor
  ColorEditor -->|dispatch events| ColorCubit
  TextEditor -->|dispatch events| TextCubit
  ButtonEditor -->|dispatch events| ButtonCubit
  ColorCubit -->|updates state| Preview
  TextCubit -->|updates state| Preview
  ButtonCubit -->|updates state| Preview
  Preview -->|uses widgets| Widgets

  ColorCubit -->|logs via| Analytics
  TextCubit -->|logs via| Analytics
  ButtonCubit -->|auth via| Auth

  Preview -->|export triggers| ExportService
  ExportService -->|serializes to JSON| Generated
  Annotations -->|scanned by| BuildRunner
  BuilderLib -->|integrates with| BuildRunner
  BuildYAML -->|configures| BuildRunner
  Generated -->|output to| ExampleMain
  Generated -->|output to| ExampleAssets

  ExampleMain -->|runs on| Android
  ExampleMain -->|runs on| iOS
  ExampleMain -->|runs on| Linux
  ExampleMain -->|runs on| MacOS
  ExampleMain -->|runs on| Windows
  ExampleMain -->|runs on| Web

  Workflows -->|manage builds/tests| BuildRunner
  FVM -->|pins Flutter version| BuildRunner
  ReleaseScripts -->|automate| BuildRunner

  %% Click Events
  click Home "https://github.com/zeshuaro/appainter/tree/main/lib/home/"
  click ColorEditor "https://github.com/zeshuaro/appainter/tree/main/lib/color_theme/"
  click TextEditor "https://github.com/zeshuaro/appainter/tree/main/lib/text_theme/"
  click ButtonEditor "https://github.com/zeshuaro/appainter/tree/main/lib/button_theme/"
  click Preview "https://github.com/zeshuaro/appainter/tree/main/lib/theme_preview/views/"
  click Widgets "https://github.com/zeshuaro/appainter/tree/main/lib/widgets/"
  click BlocObserver "https://github.com/zeshuaro/appainter/blob/main/lib/bloc_observer.dart"
  click ColorCubit "https://github.com/zeshuaro/appainter/blob/main/lib/color_theme/cubit/color_theme_cubit.dart"
  click TextCubit "https://github.com/zeshuaro/appainter/blob/main/lib/text_theme/cubits/text_theme_cubit.dart"
  click ButtonCubit "https://github.com/zeshuaro/appainter/blob/main/lib/button_theme/**/cubit/*.dart"
  click Models "https://github.com/zeshuaro/appainter/tree/main/lib/models/"
  click CommonExt "https://github.com/zeshuaro/appainter/tree/main/lib/common/"
  click ExportService "https://github.com/zeshuaro/appainter/tree/main/lib/services/"
  click Analytics "https://github.com/zeshuaro/appainter/blob/main/lib/analytics/analytics_repository.dart"
  click Auth "https://github.com/zeshuaro/appainter/blob/main/lib/authentication/authentication_repository.dart"
  click Utils "https://github.com/zeshuaro/appainter/tree/main/lib/utils/"
  click Annotations "https://github.com/zeshuaro/appainter/tree/main/packages/annotations/lib/"
  click BuilderLib "https://github.com/zeshuaro/appainter/tree/main/packages/builder/lib/"
  click BuildYAML "https://github.com/zeshuaro/appainter/blob/main/packages/builder/build.yaml"
  click Android "https://github.com/zeshuaro/appainter/tree/main/android/"
  click iOS "https://github.com/zeshuaro/appainter/tree/main/ios/"
  click Linux "https://github.com/zeshuaro/appainter/tree/main/linux/"
  click MacOS "https://github.com/zeshuaro/appainter/tree/main/macos/"
  click Windows "https://github.com/zeshuaro/appainter/tree/main/windows/"
  click Web "https://github.com/zeshuaro/appainter/tree/main/web/"
  click ExampleMain "https://github.com/zeshuaro/appainter/blob/main/example/lib/main.dart"
  click ExampleAssets "https://github.com/zeshuaro/appainter/blob/main/example/assets/appainter_theme.json"
  click Workflows "https://github.com/zeshuaro/appainter/tree/main/.github/workflows/"
  click FVM "https://github.com/zeshuaro/appainter/blob/main/.fvm/fvm_config.json"
  click ReleaseScripts "https://github.com/zeshuaro/appainter/blob/main/build.sh"

  %% Styles
  classDef presentation fill:#a8e6cf,stroke:#379683,color:#05386b
  classDef state fill:#dcedc1,stroke:#8ac926,color:#2f5d62
  classDef services fill:#ffe5b4,stroke:#ff8c00,color:#663300
  classDef codegen fill:#e0bbf4,stroke:#800080,color:#330033
  classDef platform fill:#f0f0f0,stroke:#999999,color:#333333
  classDef example fill:#b2ebf2,stroke:#00bcd4,color:#004d40
  classDef tooling fill:#ffcccb,stroke:#ff0000,color:#660000
```
