How zeshuaro/appainter works
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.