# milasantacruz/salesmate architecture

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

- Interactive diagram: https://gitdiagram.com/milasantacruz/salesmate
- Repository: https://github.com/milasantacruz/salesmate

## Overview

##### Project Type and Purpose
- This is a cross-platform mobile application built with Flutter (Dart) for order management, integrating bidirectionally with an Odoo ERP back-end and a small WebAdmin API. It supports offline mode (Hive) and real-time sync (JSON-RPC).

##### High-Level Architecture from File Structure
- Top-level “android/”, “ios/”, “linux/”, “macos/”, “windows/”, “web/” folders: platform runners generated by Flutter.
- “lib/” holds the core of the app, divided into three layers:
- core/ – low-level services (network, cache, DI, HTTP clients, constants, error handling)
- data/ – models (Odoo entities) and repositories (data access, offline/remote)
- presentation/ – UI layer (pages, widgets) and state management (BLoC)
- Root files: proxy_server.js (Node proxy), package.json (Node), flutter entry point main.dart.

##### Key Insights from README
- State Management: BLoC pattern
- Dependency Injection: GetIt
- Local Cache: Hive
- HTTP Layer: Odoo JSON-RPC (sale.order, res.partner, etc.) and WebAdmin REST endpoints
- Offline-First with bidirectional sync

##### Main Components
a. Presentation Layer
- Flutter UI (Pages & Widgets)
- BLoC Controllers (AuthBloc, ProductBloc, SaleOrderBloc, etc.)
b. Domain/Data Layer
- Repositories (PartnerRepository, SaleOrderRepository, OfflineOdooRepository)
- Data Models (PartnerModel, SaleOrderModel…)
c. Core Services
- Dependency Injection Container (injection_container.dart)
- Network Connectivity Monitor (network_connectivity.dart)
- HTTP Clients (OdooClientMobile/Web/Stub, SessionInterceptor)
- Cache Service (Hive wrappers)
d. External Services
- Odoo ERP JSON-RPC API
- WebAdmin REST API
- Optional: Local Node.js proxy (proxy_server.js)
e. Platform Runners (Android, iOS, etc.) – bootstrap the Flutter engine

##### Interactions and Data Flow
- UI widgets dispatch Events → BLoCs
- BLoCs resolve Dependencies via GetIt → invoke Repository methods
- Repositories consult:
- Cache layer (Hive)
- HTTP layer (Odoo JSON-RPC or WebAdmin)
- Offline repository for queued operations
- SessionInterceptor attaches session tokens to HTTP calls
- Network monitor toggles offline/online strategies
- Responses flow back up: Repository → BLoC → UI

##### Architectural Patterns & Design Principles
- Layered Architecture (Presentation → Domain/Data → Core → External)
- BLoC for unidirectional data flow
- Repository pattern for data access abstraction
- Dependency Injection for decoupling and testability
- Offline-First caching strategy with synchronization logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile App"
        direction TB

        subgraph "UI Layer"
            direction TB
            UI_PAGES["Pages"]:::ui
            UI_WIDGETS["Widgets"]:::ui
        end

        subgraph "BLoC Controllers"
            direction TB
            AuthBloc["AuthBloc"]:::bloc
            EmpBloc["EmployeeBloc"]:::bloc
            PartnerBloc["PartnerBloc"]:::bloc
            ProductBloc["ProductBloc"]:::bloc
            SaleOrderBloc["SaleOrderBloc"]:::bloc
        end

        subgraph "Repositories & Models"
            direction TB
            PartnerRepo["PartnerRepository"]:::data
            SaleOrderRepo["SaleOrderRepository"]:::data
            ProductRepo["ProductRepository"]:::data
            PricelistRepo["PricelistRepository"]:::data
            EmployeeRepo["EmployeeRepository"]:::data
            OfflineRepo["OfflineOdooRepository"]:::data
            Models["Data Models"]:::data
        end

        subgraph "Core Services"
            direction TB
            DI["DI Container"]:::core
            NetMon["Network Monitor"]:::core
            HTTPFac["HTTP Client Factory"]:::core
            OdooMobile["OdooClientMobile"]:::core
            OdooWeb["OdooClientWeb"]:::core
            OdooStub["OdooClientStub"]:::core
            SessionInt["SessionInterceptor"]:::core
            CacheSvc["Cache Service"]:::core
            Constants["App Constants"]:::core
            Errors["Error Handling"]:::core
            Config["Odoo Config"]:::core
            Utils["Utils & Validators"]:::core
        end

        subgraph "Local Hive Store"
            Hive["Hive Store"]:::storage
        end
    end

    %% External Services
    OdooERP["Odoo ERP JSON-RPC"]:::external
    WebAdmin["WebAdmin API"]:::external
    NodeProxy["Node.js Proxy"]:::external

    %% Interactions
    UI_PAGES -->|"dispatch events"| AuthBloc
    UI_PAGES -->|"dispatch events"| EmpBloc
    UI_PAGES -->|"dispatch events"| PartnerBloc
    UI_PAGES -->|"dispatch events"| ProductBloc
    UI_PAGES -->|"dispatch events"| SaleOrderBloc
    UI_WIDGETS -->|"dispatch events"| AuthBloc
    UI_WIDGETS -->|"dispatch events"| EmpBloc
    UI_WIDGETS -->|"dispatch events"| PartnerBloc
    UI_WIDGETS -->|"dispatch events"| ProductBloc
    UI_WIDGETS -->|"dispatch events"| SaleOrderBloc

    AuthBloc -->|"calls"| PartnerRepo
    EmpBloc -->|"calls"| EmployeeRepo
    PartnerBloc -->|"calls"| PartnerRepo
    ProductBloc -->|"calls"| ProductRepo
    SaleOrderBloc -->|"calls"| SaleOrderRepo

    PartnerRepo -->|"Hive read/write"| CacheSvc
    EmployeeRepo -->|"Hive read/write"| CacheSvc
    ProductRepo -->|"Hive read/write"| CacheSvc
    PricelistRepo -->|"Hive read/write"| CacheSvc
    OfflineRepo -->|"queue ops"| CacheSvc
    SaleOrderRepo -->|"Hive read/write"| CacheSvc
    PartnerRepo -->|"JSON-RPC getPartners()"| OdooMobile
    SaleOrderRepo -->|"JSON-RPC getOrders()"| OdooMobile
    ProductRepo -->|"JSON-RPC getProducts()"| OdooMobile

    HTTPFac -->|"provides clients"| OdooMobile
    HTTPFac -->|"provides clients"| OdooWeb
    HTTPFac -->|"provides clients"| OdooStub

    OdooMobile -->|"""attach session"""| SessionInt
    OdooWeb -->|"""attach session"""| SessionInt
    OdooStub -->|"""attach session"""| SessionInt

    SessionInt -->|"forward request"| NodeProxy
    NodeProxy -->|"forward JSON-RPC"| OdooERP

    CacheSvc <-->|"read/write"| Hive

    OdooMobile -->|"JSON-RPC"| OdooERP
    OdooWeb -->|"JSON-RPC"| OdooERP
    OdooWeb -->|"REST"| WebAdmin

    AuthBloc -->|"<response>"| UI_PAGES
    EmpBloc -->|"<response>"| UI_PAGES
    PartnerBloc -->|"<response>"| UI_PAGES
    ProductBloc -->|"<response>"| UI_PAGES
    SaleOrderBloc -->|"<response>"| UI_PAGES

    %% Click Events
    click UI_PAGES "https://github.com/milasantacruz/salesmate/tree/main/lib/presentation/pages"
    click UI_WIDGETS "https://github.com/milasantacruz/salesmate/tree/main/lib/presentation/widgets"
    click AuthBloc "https://github.com/milasantacruz/salesmate/blob/main/lib/presentation/bloc/auth/auth_bloc.dart"
    click EmpBloc "https://github.com/milasantacruz/salesmate/blob/main/lib/presentation/bloc/employee/employee_bloc.dart"
    click PartnerBloc "https://github.com/milasantacruz/salesmate/blob/main/lib/presentation/bloc/partner_bloc.dart"
    click ProductBloc "https://github.com/milasantacruz/salesmate/blob/main/lib/presentation/bloc/product/product_bloc.dart"
    click SaleOrderBloc "https://github.com/milasantacruz/salesmate/blob/main/lib/presentation/bloc/sale_order/sale_order_bloc.dart"
    click Models "https://github.com/milasantacruz/salesmate/tree/main/lib/data/models"
    click PartnerRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/partner_repository.dart"
    click SaleOrderRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/sale_order_repository.dart"
    click ProductRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/product_repository.dart"
    click PricelistRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/pricelist_repository.dart"
    click EmployeeRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/employee_repository.dart"
    click OfflineRepo "https://github.com/milasantacruz/salesmate/blob/main/lib/data/repositories/offline_odoo_repository.dart"
    click DI "https://github.com/milasantacruz/salesmate/blob/main/lib/core/di/injection_container.dart"
    click NetMon "https://github.com/milasantacruz/salesmate/blob/main/lib/core/network/network_connectivity.dart"
    click HTTPFac "https://github.com/milasantacruz/salesmate/blob/main/lib/core/http/odoo_client_factory.dart"
    click OdooMobile "https://github.com/milasantacruz/salesmate/blob/main/lib/core/http/odoo_client_mobile.dart"
    click OdooWeb "https://github.com/milasantacruz/salesmate/blob/main/lib/core/http/odoo_client_web.dart"
    click OdooStub "https://github.com/milasantacruz/salesmate/blob/main/lib/core/http/odoo_client_stub.dart"
    click SessionInt "https://github.com/milasantacruz/salesmate/blob/main/lib/core/http/session_interceptor.dart"
    click CacheSvc "https://github.com/milasantacruz/salesmate/blob/main/lib/core/cache/custom_odoo_kv.dart"
    click Constants "https://github.com/milasantacruz/salesmate/blob/main/lib/core/constants/app_constants.dart"
    click Errors "https://github.com/milasantacruz/salesmate/blob/main/lib/core/errors/exceptions.dart"
    click Config "https://github.com/milasantacruz/salesmate/blob/main/lib/core/odoo/odoo_config.dart"
    click Utils "https://github.com/milasantacruz/salesmate/blob/main/lib/core/utils/typedefs.dart"
    click NodeProxy "https://github.com/milasantacruz/salesmate/blob/main/proxy_server.js"
    click main "https://github.com/milasantacruz/salesmate/blob/main/lib/main.dart"
    click android "https://github.com/milasantacruz/salesmate/tree/main/android/"
    click ios "https://github.com/milasantacruz/salesmate/tree/main/ios/"
    click linux "https://github.com/milasantacruz/salesmate/tree/main/linux/"
    click macos "https://github.com/milasantacruz/salesmate/tree/main/macos/"
    click windows "https://github.com/milasantacruz/salesmate/tree/main/windows/"
    click web "https://github.com/milasantacruz/salesmate/tree/main/web/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef bloc fill:#BFEFFF,stroke:#333,stroke-width:1px
    classDef data fill:#98FB98,stroke:#333,stroke-width:1px
    classDef core fill:#FFD580,stroke:#333,stroke-width:1px
    classDef external fill:#FF8C8C,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
```
