# ramonsantospinto/cards_circulos architecture

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

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

## Overview

#### Purpose and runtime
Cards & Circles is a single-module Android study app demonstrating feature-oriented Clean Architecture, unidirectional data flow, and lifecycle-aware UI state. It runs as a native Kotlin Android application using Jetpack Compose, ViewModel, StateFlow, coroutines, and Compose Navigation. No backend, persistence layer, or external service is indicated.

#### Application entry and composition root
`app/src/main/java/com/example/cards/MainActivity.kt` is the Android entry point and top-level composition root. It initializes the Compose UI, owns the application-level Scaffold/navigation orchestration, and connects route selection to feature screens. Android packaging, launcher configuration, theme resources, and platform declarations begin at `app/src/main/AndroidManifest.xml`.

#### Navigation boundary
Navigation is centralized rather than embedded in feature implementations. `app/src/main/java/com/example/cards/core/navigation/Screen.kt` defines the shared screen/route model used by `MainActivity` and the destination graph. This core boundary lets feature presentation code expose UI destinations while keeping route identity and transitions consistent across the app.

#### Home feature: state-driven card grid
The Home feature represents the primary card-grid interaction flow:
- `app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt` renders the declarative home UI and forwards user events.
- `app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt` receives those events, owns lifecycle-aware presentation state, and applies state transitions.
- `app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt` is the explicit UI-state contract consumed by Compose.

The intended UDF path is UI event → ViewModel → StateFlow-backed `HomeUiState` update → Compose recomposition. UI rendering remains state-derived rather than holding business interaction state locally.

#### Circles feature: isolated interactive presentation
The Circles feature is a separate presentation slice for color/circle interaction:
- `app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt`
- `app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt`

Its screen observes ViewModel-managed reactive state and emits user actions upward; its ViewModel is the control boundary for circle interaction logic and asynchronous/stateful behavior. Feature isolation allows its presentation model to evolve independently from Home, connected only through shared navigation and the app shell.

#### State, lifecycle, and rendering flow
ViewModels are the durable state holders across Compose recompositions and Activity lifecycle events. StateFlow and coroutines provide the reactive/asynchronous mechanism: feature ViewModels publish state, screens collect it, and Compose redraws from the latest value. `MainActivity` controls destination-level composition; each feature controls its own presentation-state transitions.

#### Build and platform boundaries
Gradle defines a conventional Android application module at `app/build.gradle.kts`, with repository-wide build setup in `build.gradle.kts` and `settings.gradle.kts`. Android resources and themes remain platform-facing boundaries under `app/src/main/res`, while code shrinker retention policy is isolated at `app/src/main/keepRules/rules.keep`.

Main entry points: [`app/src/main/java/com/example/cards/MainActivity.kt`](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/MainActivity.kt) (Main Activity), [`app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt`](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt) (Home Screen), [`app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt`](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt) (Circles Screen), [`app/src/main/java/com/example/cards/core/navigation/Screen.kt`](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/core/navigation/Screen.kt) (Screen Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Android Platform"]
  node_gradle["Gradle Build<br/>[build.gradle.kts]"]
  node_manifest["Android Manifest<br/>platform config"]
  node_resources["Resources &amp; Themes"]
  node_android{{"Android Runtime<br/>platform"}}
end

subgraph group_app["App Shell"]
  node_main_activity["Main Activity<br/>composition root<br/>[MainActivity.kt]"]
  node_routes["Screen Routes<br/>navigation model<br/>[Screen.kt]"]
  node_stateflow["StateFlow &amp; Coroutines<br/>reactive runtime"]
end

subgraph group_home["Home Feature"]
  node_home_screen["Home Screen<br/>Compose screen<br/>[HomeScreen.kt]"]
  node_home_vm["Home ViewModel<br/>state holder<br/>[HomeViewModel.kt]"]
  node_home_state["Home UI State<br/>state contract<br/>[HomeUiState.kt]"]
end

subgraph group_circles["Circles Feature"]
  node_circles_screen["Circles Screen<br/>Compose screen<br/>[CirclesScreen.kt]"]
  node_circles_vm["Circles ViewModel<br/>state holder"]
end

node_gradle -->|"builds"| node_android
node_manifest -->|"declares app"| node_android
node_resources -->|"themes UI"| node_main_activity
node_android -->|"launches"| node_main_activity
node_main_activity -->|"uses routes"| node_routes
node_main_activity -->|"composes destination"| node_home_screen
node_main_activity -->|"composes destination"| node_circles_screen
node_routes -->|"selects"| node_home_screen
node_routes -->|"selects"| node_circles_screen
node_home_screen -->|"user events"| node_home_vm
node_home_vm -->|"updates"| node_home_state
node_home_vm -->|"publishes via"| node_stateflow
node_stateflow -->|"state collection"| node_home_screen
node_home_state -->|"renders"| node_home_screen
node_circles_screen -->|"user actions"| node_circles_vm
node_circles_vm -->|"publishes via"| node_stateflow
node_stateflow -->|"state collection"| node_circles_screen

click node_gradle "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/build.gradle.kts"
click node_manifest "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/AndroidManifest.xml"
click node_resources "https://github.com/ramonsantospinto/cards_circulos/tree/main/app/src/main/res"
click node_main_activity "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/MainActivity.kt"
click node_routes "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/core/navigation/Screen.kt"
click node_home_screen "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt"
click node_home_vm "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt"
click node_home_state "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt"
click node_circles_screen "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt"
click node_circles_vm "https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt"

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_gradle,node_manifest,node_resources,node_android toneBlue
class node_main_activity,node_routes,node_stateflow toneAmber
class node_home_screen,node_home_vm,node_home_state toneMint
class node_circles_screen,node_circles_vm toneRose
```

## Components

### Android Platform

- [Gradle Build](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/build.gradle.kts): build · Defines the Android application module and repository build setup. · `app/build.gradle.kts`
- [Android Manifest](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/AndroidManifest.xml): platform config · Declares Android packaging and launcher integration. · `app/src/main/AndroidManifest.xml`
- [Resources & Themes](https://github.com/ramonsantospinto/cards_circulos/tree/main/app/src/main/res): resources · Platform-facing Android resources and themes. · `app/src/main/res`
- **Android Runtime**: platform

### App Shell

- [Main Activity](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/MainActivity.kt): composition root · Hosts Compose, scaffold orchestration, and destination composition. · `app/src/main/java/com/example/cards/MainActivity.kt`
- [Screen Routes](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/core/navigation/Screen.kt): navigation model · Shared route identity for app destinations. · `app/src/main/java/com/example/cards/core/navigation/Screen.kt`
- **StateFlow & Coroutines**: reactive runtime · Delivers lifecycle-aware asynchronous state updates.

### Home Feature

- [Home Screen](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt): Compose screen · Renders the card grid from state and forwards user events. · `app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt`
- [Home ViewModel](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt): state holder · Handles home events and publishes presentation state. · `app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt`
- [Home UI State](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt): state contract · Explicit state consumed by the Home composable. · `app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt`

### Circles Feature

- [Circles Screen](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt): Compose screen · Renders circle interaction state and emits actions. · `app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt`
- [Circles ViewModel](https://github.com/ramonsantospinto/cards_circulos/blob/main/app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt): state holder · Controls circle interaction and reactive state. · `app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt`

## Connections

- Gradle Build → Android Runtime: builds
- Android Manifest → Android Runtime: declares app
- Resources & Themes → Main Activity: themes UI
- Android Runtime → Main Activity: launches
- Main Activity → Screen Routes: uses routes
- Main Activity → Home Screen: composes destination
- Main Activity → Circles Screen: composes destination
- Screen Routes → Home Screen: selects
- Screen Routes → Circles Screen: selects
- Home Screen → Home ViewModel: user events
- Home ViewModel → Home UI State: updates
- Home ViewModel → StateFlow & Coroutines: publishes via
- StateFlow & Coroutines → Home Screen: state collection
- Home UI State → Home Screen: renders
- Circles Screen → Circles ViewModel: user actions
- Circles ViewModel → StateFlow & Coroutines: publishes via
- StateFlow & Coroutines → Circles Screen: state collection