# ramonsantospinto/nuclone architecture

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

- Interactive diagram: https://gitdiagram.com/ramonsantospinto/nuclone
- Repository: https://github.com/ramonsantospinto/nuclone

## Overview

#### Purpose and Entry Points
NuClone is a Flutter/Dart mobile portfolio app that recreates Nubank-style Home and Pix-send experiences using Clean Architecture. Flutter starts at `lib/main.dart`; platform hosts bootstrap the Flutter runtime through `android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt` and `ios/Runner/AppDelegate.swift`.

#### Composition and Shared Core
Application-wide wiring, error contracts, styling, and formatting live under `lib/app/core/`. The dependency container in `lib/app/core/dependency_injection/injector.dart` supplies repositories, use cases, and Cubits rather than letting presentation create concrete dependencies. Shared `Failure` types support explicit functional error paths, while theme files define the visual system.

#### Feature Boundaries
Features are vertically isolated under `lib/app/feature/home/` and `lib/app/feature/pix/`, each divided into `data`, `domain`, and `presentation`. The intended dependency direction is presentation → domain abstractions/use cases; data implements domain repository contracts. This keeps UI state and infrastructure replaceable per feature.

#### Home Data Flow
Home rendering begins at `lib/app/feature/home/presentation/pages/home_page.dart`, driven by `home_cubit.dart`. The Cubit invokes `get_account_data_usecase.dart`, which depends on the repository interface at `domain/repositories/home_repository.dart`. `data/repositories/home_repository_impl.dart` adapts the available source, presently `data/datasources/home_mock_datasource.dart`, into domain entities such as `account_entity.dart` and `transaction_entity.dart`. Outcomes propagate as `Either<Failure, Success>` into loading, success, or error Cubit states.

#### Pix Transfer Flow
The Pix screen at `lib/app/feature/pix/presentation/pages/pix_send_page.dart` delegates submission state to `pix_cubit.dart`. It calls `domain/usecases/send_pix_usecase.dart` through the abstract `pix_repository.dart`; the current concrete boundary is `data/repositories/pix_repository_impl.dart`. Presentation consumes Pix state transitions and displays completion through `presentation/widgets/pix_success_sheet.dart`.

#### State and UI Boundary
`flutter_bloc` Cubits own asynchronous feature state; pages and widgets render state rather than access repositories directly. Home presentation is composed from feature widgets including `presentation/widgets/home_header.dart` and `presentation/widgets/quick_actions.dart`. This is a native Flutter UI, not a web/server application.

#### Runtime and External Services
Material runtimes are Flutter 3.x and Dart 3.x, packaged for Android via Gradle (`android/app/build.gradle.kts`) and iOS via Xcode (`ios/Runner.xcodeproj/project.pbxproj`). The repository tree exposes no backend client, persistence layer, or live banking/Pix integration: Home uses a mock datasource and Pix has a repository implementation boundary suitable for a future external service.

Main entry points: [`lib/main.dart`](https://github.com/ramonsantospinto/nuclone/blob/main/lib/main.dart) (Flutter app entry), [`lib/app/core/dependency_injection/injector.dart`](https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/core/dependency_injection/injector.dart) (Dependency injector), [`lib/app/feature/home/presentation/pages/home_page.dart`](https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/feature/home/presentation/pages/home_page.dart) (Home page), [`android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt`](https://github.com/ramonsantospinto/nuclone/blob/main/android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt) (Android host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime Hosts"]
  node_android["Android host<br/>Kotlin / Gradle<br/>[MainActivity.kt]"]
  node_ios["iOS host<br/>Swift / Xcode<br/>[AppDelegate.swift]"]
  node_flutter["Flutter app entry<br/>Flutter / Dart<br/>[main.dart]"]
end

subgraph group_core["App Core"]
  node_injector{{"Dependency injector<br/>composition root<br/>[injector.dart]"}}
  node_failure["Failure contracts<br/>error model"]
  node_theme["Theme system<br/>shared styling"]
end

subgraph group_home["Home Feature"]
  node_home_page["Home page<br/>Flutter page<br/>[home_page.dart]"]
  node_home_widgets["Home UI widgets<br/>Flutter widgets"]
  node_home_cubit{{"Home Cubit<br/>Cubit state"}}
  node_get_account["Get account data<br/>use case"]
  node_home_repository["Home repository contract<br/>domain interface"]
  node_home_repository_impl["Home repository implementation<br/>data repository"]
  node_home_mock[("Home mock datasource<br/>mock data source")]
  node_home_entities["Account &amp; transactions<br/>domain entities"]
end

subgraph group_pix["Pix Feature"]
  node_pix_page["Pix send page<br/>Flutter page<br/>[pix_send_page.dart]"]
  node_pix_cubit{{"Pix Cubit<br/>Cubit state"}}
  node_send_pix["Send Pix<br/>use case"]
  node_pix_repository["Pix repository contract<br/>domain interface"]
  node_pix_repository_impl["Pix repository implementation<br/>data repository"]
  node_pix_success["Pix success sheet<br/>Flutter widget"]
end

node_android -->|"launches"| node_flutter
node_ios -->|"launches"| node_flutter
node_flutter -->|"composes"| node_injector
node_flutter -->|"applies"| node_theme
node_injector -->|"provides"| node_home_cubit
node_injector -->|"provides"| node_pix_cubit
node_home_page -->|"renders state"| node_home_cubit
node_home_page -->|"composes"| node_home_widgets
node_home_cubit -->|"invokes"| node_get_account
node_get_account -->|"depends on"| node_home_repository
node_home_repository_impl -.->|"implements"| node_home_repository
node_home_repository_impl -->|"reads"| node_home_mock
node_home_repository_impl -->|"maps to"| node_home_entities
node_home_cubit -->|"handles Either failures"| node_failure
node_pix_page -->|"submits through"| node_pix_cubit
node_pix_cubit -->|"invokes"| node_send_pix
node_send_pix -->|"depends on"| node_pix_repository
node_pix_repository_impl -.->|"implements"| node_pix_repository
node_pix_cubit -->|"shows on completion"| node_pix_success
node_pix_cubit -->|"handles failures"| node_failure

click node_android "https://github.com/ramonsantospinto/nuclone/blob/main/android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt"
click node_ios "https://github.com/ramonsantospinto/nuclone/blob/main/ios/Runner/AppDelegate.swift"
click node_flutter "https://github.com/ramonsantospinto/nuclone/blob/main/lib/main.dart"
click node_injector "https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/core/dependency_injection/injector.dart"
click node_home_page "https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/feature/home/presentation/pages/home_page.dart"
click node_pix_page "https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/feature/pix/presentation/pages/pix_send_page.dart"

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_android,node_ios,node_flutter toneBlue
class node_injector,node_failure,node_theme toneAmber
class node_home_page,node_home_widgets,node_home_cubit,node_get_account,node_home_repository,node_home_repository_impl,node_home_mock,node_home_entities toneMint
class node_pix_page,node_pix_cubit,node_send_pix,node_pix_repository,node_pix_repository_impl,node_pix_success toneRose
```

## Components

### Runtime Hosts

- [Android host](https://github.com/ramonsantospinto/nuclone/blob/main/android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt): Kotlin / Gradle · Bootstraps the Flutter runtime on Android. · `android/app/src/main/kotlin/br/com/nuclone/nuclone/MainActivity.kt`
- [iOS host](https://github.com/ramonsantospinto/nuclone/blob/main/ios/Runner/AppDelegate.swift): Swift / Xcode · Bootstraps the Flutter runtime on iOS. · `ios/Runner/AppDelegate.swift`
- [Flutter app entry](https://github.com/ramonsantospinto/nuclone/blob/main/lib/main.dart): Flutter / Dart · `lib/main.dart`

### App Core

- [Dependency injector](https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/core/dependency_injection/injector.dart): composition root · Supplies feature repositories, use cases, and Cubits. · `lib/app/core/dependency_injection/injector.dart`
- **Failure contracts**: error model · Supports explicit functional error results.
- **Theme system**: shared styling

### Home Feature

- [Home page](https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/feature/home/presentation/pages/home_page.dart): Flutter page · `lib/app/feature/home/presentation/pages/home_page.dart`
- **Home UI widgets**: Flutter widgets · Header and quick-action components render Home content.
- **Home Cubit**: Cubit state · Maps account loading outcomes to UI states.
- **Get account data**: use case
- **Home repository contract**: domain interface
- **Home repository implementation**: data repository
- **Home mock datasource**: mock data source · Current source for account and transaction data.
- **Account & transactions**: domain entities

### Pix Feature

- [Pix send page](https://github.com/ramonsantospinto/nuclone/blob/main/lib/app/feature/pix/presentation/pages/pix_send_page.dart): Flutter page · `lib/app/feature/pix/presentation/pages/pix_send_page.dart`
- **Pix Cubit**: Cubit state · Owns Pix submission state transitions.
- **Send Pix**: use case
- **Pix repository contract**: domain interface
- **Pix repository implementation**: data repository · Concrete boundary for a future Pix service.
- **Pix success sheet**: Flutter widget · Displays transfer completion.

## Connections

- Android host → Flutter app entry: launches
- iOS host → Flutter app entry: launches
- Flutter app entry → Dependency injector: composes
- Flutter app entry → Theme system: applies
- Dependency injector → Home Cubit: provides
- Dependency injector → Pix Cubit: provides
- Home page → Home Cubit: renders state
- Home page → Home UI widgets: composes
- Home Cubit → Get account data: invokes
- Get account data → Home repository contract: depends on
- Home repository implementation → Home repository contract: implements
- Home repository implementation → Home mock datasource: reads
- Home repository implementation → Account & transactions: maps to
- Home Cubit → Failure contracts: handles Either failures
- Pix send page → Pix Cubit: submits through
- Pix Cubit → Send Pix: invokes
- Send Pix → Pix repository contract: depends on
- Pix repository implementation → Pix repository contract: implements
- Pix Cubit → Pix success sheet: shows on completion
- Pix Cubit → Failure contracts: handles failures