Sellio Categories Sections

A powerful admin panel for managing Home Screen Category Sections in the Sellio application .. built with Clean Architecture, Cubit, and Retrofit, and fully documented as a learning resource for Flutter developers.

---

📚 Clean Architecture .. Chapter by Chapter

This project is not just an app .. it's a guided course.

Every architectural decision, every layer, every line of code is explained in a beginner-friendly App Story that walks you through building a real-world Flutter app using Clean Architecture.

#	Chapter	What You'll Story
0	Introduction	Project overview and architecture map
1	The Foundation .. Entities	Domain entities and business objects
2	The Translator .. Models & JSON	Data models, JSON serialization, code generation
3	The Messenger .. API & Data Sources	Retrofit, Dio, and remote data sources
3.5	The Bridge .. Mappers	Decoupling models from entities with mappers
4	The Rulebook .. Repositories & Use Cases	Repository pattern and single-purpose use cases
5	The Wiring .. Dependency Injection	GetIt, Injectable, and auto-wiring
6	The Brain .. Cubit State Management	Cubit, states, and reactive UI
7	The Face .. UI Layer	Screens, components, and user interactions

Technical Deep Dives

Guide	Description
Clean Architecture	Layer separation, dependency rules, and diagrams
Dependency Injection	How GetIt and Injectable wire everything together
Retrofit & Networking	Type-safe API calls with Retrofit and Dio
Cubit Refactor Guide	Migrating from ViewModel to Cubit
Release Automation	CI/CD with GitHub Actions

---

Key Features

• Section Management: Full CRUD operations for home screen sections
• Shimmer Loading: Polished skeleton loading effect instead of spinners
• Optimistic UI: Instant feedback with automatic rollback on errors
• Smart Merging: Server data merged with local state to preserve inactive sections
• Active/Inactive Toggling: Quick enable/disable from the main list
• Sort Order Sync: Edit sort order and see changes reflected immediately

Architecture

This project follows Clean Architecture principles with complete layer separation:

graph TD
    UI[Presentation UI] --> Cubit[Presentation Cubit]
    Cubit --> UseCase[Domain Use Case]
    UseCase --> RepoInterface[Domain Repository Interface]
    RepoImpl[Data Repository Implementation] --> RepoInterface
    RepoImpl --> Mapper[Data Mapper]
    RepoImpl --> DataSource[Data Data Source]
    DataSource --> API[External API]

Loading

• Domain Layer: Entities, Use Cases, Repository Interfaces .. pure Dart, zero dependencies
• Data Layer: Models, Mappers, Data Sources, Repository Implementations
• Presentation Layer: Screens, Components, Cubits, Theme

Note

For a deep dive into the architecture, check out Clean Architecture in Sellio.

Technology Stack

• Framework: Flutter (Dart 3.x)
• State Management: flutter_bloc (Cubit)
• Dependency Injection: GetIt & Injectable
• Networking: Retrofit & Dio
• Serialization: json_serializable
• Loading Effects: shimmer

Tip

Learn more about our networking layer in Retrofit Details.

Getting Started

Prerequisites

• Flutter SDK
• Dart SDK

Installation

1. Clone the repository

   git clone https://github.com/Ahmedsayed0895/Sellio-sections-controller.git

2. Install dependencies

   flutter pub get

3. Generate Code (required for Retrofit, Models, & DI)

   flutter pub run build_runner build --delete-conflicting-outputs

4. Run the application

   flutter run

Project Structure

lib/
├── domain/           # Business logic (Entities, Use Cases, Repos)
├── data/             # Data implementation (Models, Mappers, APIs, Repos Impl)
│   ├── models/
│   ├── mappers/
│   ├── datasources/
│   └── repositories/
├── presentation/     # UI and Cubits
│   ├── screens/
│   ├── cubits/
│   └── theme/
└── main.dart         # Entry point

app_story/            # Chapter-by-chapter architecture guide
docs/                 # Technical deep-dive documentation