# invoiceninja/admin-portal architecture

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

- Interactive diagram: https://gitdiagram.com/invoiceninja/admin-portal
- Repository: https://github.com/invoiceninja/admin-portal

## Overview

##### Project type and purpose
- This is a cross-platform client application (mobile + desktop + web) written in Flutter/Dart.
- It implements a Redux-based unidirectional data-flow architecture and communicates with the Invoice Ninja backend via RESTful APIs.

##### File structure
- Top-level “android”, “ios”, “linux”, “macos”, “windows”, “web” folders: native runners generated by Flutter.
- “lib/” contains the Dart code, split into four main packages:
- data/       → models, repositories, file storage & WebClient
- redux/      → actions, middleware, reducers, selectors, immutable app state
- ui/         → Flutter widgets & view-models for every feature (auth, invoices, clients, etc.)
- utils/      → shared utilities (i18n, formatting, OAuth stubs, code generation helpers)
- Configuration & build scripts: GitHub Actions (.github/workflows), Codemagic, Fastlane, Snapcraft, Flatpak manifests.

##### README for additional insights
- Confirms the layers (data, redux, ui, utils) and reliance on flutter_redux_starter.
- Mentions build_runner code generation for JSON-serializable models.
- Provides testing scripts (flutter drive) and CI pipelines.

##### Main components
a. Client Platforms (Android, iOS, Web, Windows, macOS, Linux)
- Each platform runs the same Flutter engine + Dart VM + native host.
b. App Layers within each client
- UI Layer (Widgets / Screens under lib/ui)
- State Management Layer (Redux Store: actions → middleware → reducers → app state; selectors read state)
- Data Layer (Repositories + WebClient + FileStorage)
c. External Backend Service
- Invoice Ninja REST API (hosted separately)
- Authentication endpoint, entity endpoints (invoices, clients, payments…), static data endpoints
d. Local Persistence
- FileStorage writes/reads local cache or credentials (lib/data/file_storage.dart)
e. Build & CI/CD
- Code Generation (build_runner → model.g.dart files)
- GitHub Actions, Codemagic, Fastlane, Snapcraft, Flatpak pipelines

##### Relationships & data flows
1) User interacts with UI Widget → dispatches a Redux Action
2) Action passes through Middleware → calls Data Repository
3) Repository uses WebClient → issues HTTP request to Backend API
4) Backend responds → repository returns data to Middleware
5) Middleware dispatches success/failure Action → Reducer updates App State
6) UI Layer subscribes via Selectors → rebuilds Widgets with new State
7) For offline or caching scenarios → FileStorage reads/writes locally

##### Architectural patterns & design principles
- Unidirectional data flow (Redux)
- Separation of concerns: UI, state, data, model layers
- Code generation for boilerplate model serializers
- Platform-agnostic business logic, single codebase → multiple targets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Platforms
    subgraph "Client Platforms"
        Android["Android"]:::external
        iOS["iOS"]:::external
        Web["Web"]:::external
        Linux["Linux"]:::external
        macOS["macOS"]:::external
        Windows["Windows"]:::external
    end

    %% Client Container
    subgraph "Client (Flutter/Dart)"
        direction TB
        subgraph "UI Layer"
            UI["UI Widgets & Screens"]:::ui
        end
        subgraph "State Management Layer (Redux)"
            Store["Redux Store\n(actions, middleware, reducers, selectors)"]:::redux
        end
        subgraph "Data Layer"
            Models["Models & Serializers"]:::data
            Repo["Repositories"]:::data
            WebClient["WebClient"]:::data
            FS["FileStorage"]:::data
        end
    end

    %% External Backend
    API["Invoice Ninja REST API"]:::external

    %% Build & CI/CD
    subgraph "Build & CI/CD"
        direction TB
        Gen["Code Generation\n(build_runner)"]:::external
        Build["Flutter Build\n(platform artifacts)"]:::external
        Dist["Distribution\n(App Store, Play Store, Snap, Flatpak)"]:::external
        GH["GitHub Actions"]:::external
        CM["Codemagic"]:::external
        FL["Fastlane"]:::external
        SN["Snapcraft"]:::external
        FP["Flatpak"]:::external
    end

    %% Interactions
    Android -->|"runs Client"| UI
    iOS -->|"runs Client"| UI
    Web -->|"runs Client"| UI
    Linux -->|"runs Client"| UI
    macOS -->|"runs Client"| UI
    Windows -->|"runs Client"| UI

    UI -->|"1. Dispatch Action"| Store
    Store -->|"2. Action→Middleware→Repo"| Repo
    Repo -->|"3. HTTP Request"| WebClient
    WebClient -->|"HTTP Request/Response"| API
    API -->|"HTTP Response"| WebClient
    WebClient -->|"4. Return Data"| Repo
    Repo -->|"5. Dispatch Success/Failure Action"| Store
    Store -->|"6. State Update"| UI
    Repo -->|"Read/Write Cache"| FS

    Gen -->|"generates models/state serializers"| Models
    Gen --> Build
    GH --> Build
    CM --> Build
    FL --> Build
    SN --> Build
    FP --> Build
    Build --> Dist

    %% Click Events
    click Android "https://github.com/invoiceninja/admin-portal/tree/master/android/"
    click iOS "https://github.com/invoiceninja/admin-portal/tree/master/ios/"
    click Web "https://github.com/invoiceninja/admin-portal/tree/master/web/"
    click Linux "https://github.com/invoiceninja/admin-portal/tree/master/linux/"
    click macOS "https://github.com/invoiceninja/admin-portal/tree/master/macos/"
    click Windows "https://github.com/invoiceninja/admin-portal/tree/master/windows/"
    click UI "https://github.com/invoiceninja/admin-portal/tree/master/lib/ui/"
    click Store "https://github.com/invoiceninja/admin-portal/tree/master/lib/redux/"
    click Models "https://github.com/invoiceninja/admin-portal/tree/master/lib/data/models/"
    click Repo "https://github.com/invoiceninja/admin-portal/tree/master/lib/data/repositories/"
    click WebClient "https://github.com/invoiceninja/admin-portal/blob/master/lib/data/web_client.dart"
    click FS "https://github.com/invoiceninja/admin-portal/blob/master/lib/data/file_storage.dart"
    click GH "https://github.com/invoiceninja/admin-portal/blob/master/.github/workflows/build.yml"
    click CM "https://github.com/invoiceninja/admin-portal/blob/master/codemagic.yaml"
    click FL "https://github.com/invoiceninja/admin-portal/tree/master/fastlane/"
    click SN "https://github.com/invoiceninja/admin-portal/blob/master/snap/snapcraft.yaml"
    click FP "https://github.com/invoiceninja/admin-portal/blob/master/flatpak/com.invoiceninja.InvoiceNinja.metainfo.xml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000
    classDef redux fill:#D0FFD0,stroke:#000
    classDef data fill:#FFE0B2,stroke:#000
    classDef external fill:#E0E0E0,stroke:#000
```
