# flutterwtf/survey_sdk architecture

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

- Interactive diagram: https://gitdiagram.com/flutterwtf/survey_sdk
- Repository: https://github.com/flutterwtf/survey_sdk

## Overview

##### Project Type and Purpose
- This is a mono-repo containing two primary Flutter Dart packages and associated tooling:
- admin – A Flutter-based authoring UI (web/desktop) for building and exporting survey definitions (JSON).
- core (survey_sdk) – A standalone Flutter SDK providing reusable survey widgets, BLoC/Cubit controllers, data mappers, and domain entities for integration into client apps.
- There is also a core/example Flutter app that demonstrates embedding the survey_sdk. CI scripts and GitHub workflows live at the repo root.

##### File Structure Analysis and Architectural Patterns
- Top-level:
- .github/workflows – CI pipelines for admin, core, examples, code quality checks.
- scripts – Shell scripts for coverage and pub points checks.
- admin package:
- lib/data → data sources interfaces + web implementations (filesystem, session storage)
- lib/data/repositories → repository implementations
- lib/domain/repository_interfaces → domain-level contracts
- lib/presentation → Flutter UI organized by pages, cubits (BLoC pattern), widgets, theming, DI injector
- core package (survey_sdk):
- lib/src/data → data sources, mappers for survey JSON, theme JSON, actions
- lib/src/data/repositories → survey data repository impl
- lib/src/domain → entities, repository interfaces, utils
- lib/src/presentation → survey_controller (Cubit), question pages, widgets, localization, DI
- example/… → demonstration app showing SDK integration.
- Architectural patterns:
- Layered architecture (Data → Domain → Presentation)
- Repository pattern, Data mappers, Dependency Injection
- State management via Flutter BLoC/Cubit
- Modular packages (admin vs. core)

##### Key README Insights
- survey_sdk features customizable forms, multiple question types, theme support, i18n, analytics integration (Google/Firebase), import/export JSON.
- The admin package complements survey_sdk by authoring JSON definitions.

a. Main Components:
- Repository Root: CI/CD scripts & workflows
- Admin Package (Flutter Web/Desktop)
- Core Package (survey_sdk)
- Example App (uses survey_sdk)
- External Services: File System, Session Storage, Google Analytics/Firebase Analytics
b. Relationships and Interactions:
- Admin UI ↔ DI Injector ↔ Cubits (builder, new_question) ↔ Domain Repos ↔ Data Sources (filesystem, session storage) ←→ Local Storage / Web Storage
- Core SDK → DI Injector → SurveyCubit / SurveyController → Survey pages/widgets → calls SurveyDataRepository → Data Mappers → DataSource (filesystem)
- Example App imports core SDK and invokes SurveyWidget
- Both admin and core optionally emit analytics events to external Analytics services
c. Architectural Patterns/Principles:
- BLoC/Cubit for state management
- Layered separation: Data, Domain, Presentation
- Dependency Injection for swapping data sources (web vs. mobile)
- Repository & Mapper patterns isolating JSON & entity transformations
d. Relevant Technologies:
- Flutter & Dart
- BLoC/Cubit (flutter_bloc)
- JSON serialization / arb files for localization
- Web storage APIs, SessionStorage, FileSystem API
- Google/Firebase Analytics SDKs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository Root
    subgraph "Repository Root" 
        direction TB
        Workflows("CI Workflows"):::repo
        Scripts("CI & Tooling Scripts"):::repo
    end

    %% Admin Package
    subgraph "Admin Package" 
        direction TB
        subgraph "Presentation Layer"
            direction TB
            AdminMain["main.dart"]:::admin
            AdminInjector["injector.dart"]:::admin
            AdminApp["app.dart"]:::admin
            BuilderCubit["BuilderCubit"]:::admin
            NewQuestionCubit["NewQuestionCubit"]:::admin
        end
        subgraph "Domain Layer"
            direction TB
            FSRepoInterface["file_system_repository.dart"]:::admin
            SessionRepoInterface["session_storage_repository.dart"]:::admin
        end
        subgraph "Data Layer"
            direction TB
            FSDSInterface["filesystem_data_source.dart"]:::admin
            SessionDSInterface["session_storage_data_source.dart"]:::admin
            WebFSImpl["web_filesystem_data_source_impl.dart"]:::admin
            WebSessionImpl["web_session_storage_data_source.dart"]:::admin
            FSRepoImpl["file_system_repository_impl.dart"]:::admin
            SessionRepoImpl["session_storage_repository_impl.dart"]:::admin
        end
    end

    %% Core Package
    subgraph "Core Package (survey_sdk)"
        direction TB
        subgraph "Presentation Layer"
            direction TB
            CoreInjector["injector.dart"]:::core
            SurveyCubit["survey_cubit.dart"]:::core
            SurveyController["survey_controller.dart"]:::core
            SurveyWidget["survey.dart"]:::core
            ChoicePage["choice_question_page.dart"]:::core
            InfoPage["info_question_page.dart"]:::core
            InputPage["input_question_page.dart"]:::core
            SliderPage["slider_question_page.dart"]:::core
            Localization["localization"]:::core
        end
        subgraph "Domain Layer"
            direction TB
            Entities["entities"]:::core
            SurveyRepoInterface["survey_data_repository.dart"]:::core
        end
        subgraph "Data Layer"
            direction TB
            CoreFSDSInterface["filesystem_data_source.dart"]:::core
            CoreFSDSImpl["filesystem_data_source_impl.dart"]:::core
            Mappers["data mappers"]:::core
            SurveyRepoImpl["survey_data_repository_impl.dart"]:::core
        end
    end

    %% Example App
    subgraph "Example App"
        direction TB
        ExampleMain["main.dart"]:::example
        QuestionsJSON["questions.json"]:::example
        Android["android/"]:::example
        IOS["ios/"]:::example
        Linux["linux/"]:::example
        MacOS["macos/"]:::example
        Windows["windows/"]:::example
    end

    %% External Services
    FileSystem[(File System)]:::external-storage
    SessionStorage[(Session Storage)]:::external-storage
    Analytics[(Analytics Service)]:::external

    %% Connections - Admin
    AdminMain -->|uses DI| AdminInjector
    AdminInjector --> BuilderCubit
    AdminInjector --> NewQuestionCubit
    BuilderCubit -->|calls| FSRepoInterface
    NewQuestionCubit -->|calls| SessionRepoInterface
    FSRepoInterface --> FSDSInterface
    SessionRepoInterface --> SessionDSInterface
    FSDSInterface --> WebFSImpl
    SessionDSInterface --> WebSessionImpl
    WebFSImpl --> FileSystem
    WebSessionImpl --> SessionStorage
    BuilderCubit -->|emit analytics| Analytics
    NewQuestionCubit -->|emit analytics| Analytics

    %% Connections - Core
    CoreInjector --> SurveyCubit
    CoreInjector --> SurveyController
    SurveyCubit --> SurveyRepoInterface
    SurveyController --> SurveyRepoInterface
    SurveyRepoInterface --> CoreFSDSInterface
    CoreFSDSInterface --> CoreFSDSImpl
    CoreFSDSImpl --> FileSystem
    SurveyRepoInterface --> Mappers
    SurveyRepoImpl --> Mappers
    Mappers --> CoreFSDSImpl
    SurveyCubit -->|renders| SurveyWidget
    SurveyWidget --> ChoicePage
    SurveyWidget --> InfoPage
    SurveyWidget --> InputPage
    SurveyWidget --> SliderPage
    SurveyCubit -->|emit analytics| Analytics
    SurveyWidget -->|emit analytics| Analytics

    %% Example App usage
    ExampleMain --> SurveyWidget
    ExampleMain --> QuestionsJSON

    %% Repo Root connections
    Workflows --> Scripts

    %% Click Events - Repository Root
    click Workflows "https://github.com/flutterwtf/survey_sdk/blob/dev/.github/workflows/.admin.yml"
    click Workflows "https://github.com/flutterwtf/survey_sdk/blob/dev/.github/workflows/.core.yml"
    click Workflows "https://github.com/flutterwtf/survey_sdk/blob/dev/.github/workflows/.example.yml"
    click Scripts "https://github.com/flutterwtf/survey_sdk/blob/dev/scripts/coverage_check.sh"
    click Scripts "https://github.com/flutterwtf/survey_sdk/blob/dev/scripts/pub_points_check.sh"

    %% Click Events - Admin Package
    click AdminMain "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/main.dart"
    click AdminInjector "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/presentation/app/di/injector.dart"
    click AdminApp "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/presentation/app/app.dart"
    click BuilderCubit "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/presentation/pages/builder/builder_cubit.dart"
    click NewQuestionCubit "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/presentation/pages/new_question_page/new_question_cubit.dart"
    click FSRepoInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/domain/repository_interfaces/file_system_repository.dart"
    click SessionRepoInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/domain/repository_interfaces/session_storage_repository.dart"
    click FSDSInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/data_sources/interfaces/filesystem_data_source.dart"
    click SessionDSInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/data_sources/interfaces/session_storage_data_source.dart"
    click WebFSImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/data_sources/web/web_filesystem_data_source_impl.dart"
    click WebSessionImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/data_sources/web/web_session_storage_data_source.dart"
    click FSRepoImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/repositories/file_system_repository_impl.dart"
    click SessionRepoImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/admin/lib/data/repositories/session_storage_repository_impl.dart"

    %% Click Events - Core Package
    click CoreInjector "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/di/injector.dart"
    click SurveyCubit "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/survey/survey_cubit.dart"
    click SurveyController "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/survey/survey_controller.dart"
    click SurveyWidget "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/survey/survey.dart"
    click ChoicePage "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/choice_question/choice_question_page.dart"
    click InfoPage "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/info_question/info_question_page.dart"
    click InputPage "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/input_question/input_question_page.dart"
    click SliderPage "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/presentation/slider_question/slider_question_page.dart"
    click CoreFSDSInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/data/data_sources/interfaces/filesystem_data_source.dart"
    click CoreFSDSImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/data/data_sources/filesystem_data_source_impl.dart"
    click SurveyRepoImpl "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/data/repositories/survey_data_repository_impl.dart"
    click SurveyRepoInterface "https://github.com/flutterwtf/survey_sdk/blob/dev/core/lib/src/domain/repository_interfaces/survey_data_repository.dart"

    %% Click Events - Example App
    click ExampleMain "https://github.com/flutterwtf/survey_sdk/blob/dev/core/example/lib/main.dart"
    click QuestionsJSON "https://github.com/flutterwtf/survey_sdk/blob/dev/core/example/assets/questions.json"
    click Android "https://github.com/flutterwtf/survey_sdk/tree/dev/core/example/android/"
    click IOS "https://github.com/flutterwtf/survey_sdk/tree/dev/core/example/ios/"
    click Linux "https://github.com/flutterwtf/survey_sdk/tree/dev/core/example/linux/"
    click MacOS "https://github.com/flutterwtf/survey_sdk/tree/dev/core/example/macos/"
    click Windows "https://github.com/flutterwtf/survey_sdk/tree/dev/core/example/windows/"

    %% Styles
    classDef repo fill:#f9f,stroke:#333,stroke-width:1px;
    classDef admin fill:#bbf,stroke:#333,stroke-width:1px;
    classDef core fill:#bfb,stroke:#333,stroke-width:1px;
    classDef example fill:#fbf,stroke:#333,stroke-width:1px;
    classDef data fill:#fcc,stroke:#333,stroke-width:1px;
    classDef domain fill:#cfc,stroke:#333,stroke-width:1px;
    classDef presentation fill:#ccf,stroke:#333,stroke-width:1px;
    classDef external-storage fill:#ffe,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#eef,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
