# yata-repos/yata architecture

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

- Interactive diagram: https://gitdiagram.com/yata-repos/yata
- Repository: https://github.com/yata-repos/yata

## Overview

##### Project Type & Purpose
- This is a cross-platform full-stack application (“YATA”) written in Flutter/Dart, targeting mobile (Android, iOS), desktop (Windows, Linux, macOS) and web.
- It uses a serverless backend (Supabase) for database, authentication, real-time subscriptions, and storage.
- State is managed with Riverpod, navigation via go_router, and local offline support via a cache/offline-queue layer.

##### File-Structure & Architecture Overview
- Top-level “android”, “ios”, “linux”, “macos”, “windows”, “web” directories host platform wrappers around a single codebase in “lib”
- “lib/app” contains entrypoint (`main.dart`), router, DI wiring
- “lib/features/*” follows feature-module decomposition (auth, inventory, menu, order, analytics, export, settings) with clear subfolders: DTOs, models, presentation (pages/controllers/providers/widgets), repositories, services
- “lib/core” contains cross-cutting abstractions: contracts, constants, base classes, logging interfaces, realtime interfaces, validators
- “lib/infra” holds adapters/implementations: Supabase client, cache manager (memory/TTL), offline-queue, logging adapters, realtime manager
- “lib/shared” implements reusable UI components, theming, utilities
- Tests mirror the “core”, “features”, “infra”, “shared” hierarchy
- CI/CD automation in “.github/workflows” triggers multi-platform builds (AppImage, ZIP, APK) on version tags
- Configuration via `.env` for Supabase credentials, EnvValidator in core

##### Main Architectural Layers & Components
a. Presentation Layer (Flutter UI)
- Widgets/pages (“lib/features/*/presentation/pages”)
- Controllers & Providers (Riverpod) manage UI state
- Routing (go_router) with guards (auth_guard)
b. Domain & Service Layer
- Feature services (`lib/features/*/services`) implement business use-cases
- Use DTO ↔ Model mappers
c. Data Layer (Repository Pattern)
- Contracts defined in “lib/core/contracts”
- Repositories implement contracts in “lib/features/*/repositories” and “lib/infra/repositories”
d. Infrastructure Layer
- Supabase adapter (`lib/infra/supabase/supabase_client.dart`)
- Local cache & offline queue (`lib/infra/local/cache` and `lib/infra/local/offline_queue`)
- Realtime manager (`lib/infra/realtime`)
- Logging adapters & sinks (`lib/infra/logging`)
e. External Services
- Supabase (Auth, Postgres, Realtime subscriptions)
- Optional external analytics or error-reporting (via infra/logging)

##### Data Flow & Interactions
- UI event → Controller/Provider → Service → Repository contract → Infra Adapter → Supabase
- Read path: Supabase → Infra Adapter → Repository → Service → Provider → UI
- Write path: UI → Provider → Service → Repository → Offline Queue/Cache → Supabase
- Real-time updates via Supabase Realtime → RealtimeManager → Stream management mixins → Providers → UI
- Logging flows: Application code → LoggerBinding → Infra logging sinks (console, file, analytics)

##### Architectural Patterns & Principles
- Layered architecture (Presentation / Domain / Data / Infra)
- Feature-based modularization (each feature is self-contained)
- Dependency inversion: UI and services depend on abstract contracts, provided by wiring modules (override_dev, override_prod)
- Repository pattern for data access
- DI via Riverpod and custom provider wiring
- Separation of concerns: UI vs business logic vs data access vs infra

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        SupabaseDB["Supabase Postgres"]:::external
        SupabaseAuth["Supabase Auth"]:::external
        SupabaseRealtime["Supabase Realtime"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        SupabaseClient["SupabaseClient"]:::infra
        CacheManager["CacheManager"]:::infra
        OfflineQueue["OfflineQueue"]:::infra
        RealtimeManager["RealtimeManager"]:::infra
        LoggingAdapters["LoggingAdapters & Sinks"]:::infra
    end

    %% Data Layer
    subgraph "Data/Repository Layer"
        direction TB
        Contracts["Core Contracts"]:::data
        AuthRepo["AuthRepository"]:::data
        InventoryRepo["InventoryRepository"]:::data
        MenuRepo["MenuRepository"]:::data
        OrderRepo["OrderRepository"]:::data
        AnalyticsRepo["DailySummaryRepository"]:::data
        ExportRepo["ExportRepository"]:::data
        SettingsLocalDS["SettingsLocalDataSource"]:::data
    end

    %% Domain/Service Layer
    subgraph "Domain/Service Layer"
        direction TB
        AuthService["AuthService"]:::domain
        InventoryService["InventoryService"]:::domain
        MenuService["MenuService"]:::domain
        OrderService["OrderService"]:::domain
        AnalyticsService["AnalyticsService"]:::domain
        CSVExportService["CSVExportService"]:::domain
        SettingsService["SettingsService"]:::domain
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Widgets["Widgets/Pages"]:::presentation
        Controllers["Controllers & Providers"]:::presentation
        Router["AppRouter & Guards"]:::presentation
    end

    %% Core Cross-cutting
    subgraph "Core (Cross-cutting)" 
        direction TB
        LoggerBinding["LoggerBinding"]:::core
        EnvValidator["EnvValidator"]:::core
        UtilsMixins["Utilities & Mixins"]:::core
    end

    %% Platform Clients
    subgraph "Clients"
        direction TB
        Mobile["Mobile/Desktop/Web"]:::external
        FlutterApp["Flutter Codebase"]:::presentation
    end

    %% Connections
    Mobile -->|runs| FlutterApp
    FlutterApp -->|renders| Widgets
    Widgets -->|uses| Controllers
    Controllers -->|calls| Router

    Controllers -->|invoke| AuthService
    Controllers -->|invoke| InventoryService
    Controllers -->|invoke| MenuService
    Controllers -->|invoke| OrderService
    Controllers -->|invoke| AnalyticsService
    Controllers -->|invoke| CSVExportService
    Controllers -->|invoke| SettingsService

    AuthService -->|depends on| AuthRepo
    InventoryService -->|depends on| InventoryRepo
    MenuService -->|depends on| MenuRepo
    OrderService -->|depends on| OrderRepo
    AnalyticsService -->|depends on| AnalyticsRepo
    CSVExportService -->|depends on| ExportRepo
    SettingsService -->|depends on| SettingsLocalDS

    AuthRepo -->|impl via| SupabaseClient
    InventoryRepo -->|impl via| SupabaseClient
    MenuRepo -->|impl via| SupabaseClient
    OrderRepo -->|impl via| SupabaseClient
    AnalyticsRepo -->|impl via| SupabaseClient
    ExportRepo -->|impl via| SupabaseClient
    SettingsLocalDS -->|reads/writes| CacheManager

    %% Offline & Cache
    Controllers -->|write ops| OfflineQueue
    OfflineQueue -->|flush to| SupabaseClient
    CacheManager -->|cache read/write| SupabaseClient

    %% Realtime
    SupabaseRealtime -->|events| RealtimeManager
    RealtimeManager -->|streams to| Controllers

    %% Logging
    Widgets -->|logs| LoggerBinding
    Controllers -->|logs| LoggerBinding
    AuthService -->|logs| LoggerBinding
    InventoryService -->|logs| LoggerBinding
    LoggingAdapters -->|connects| LoggerBinding
    LoggerBinding -->|sink| LoggingAdapters

    %% External calls
    SupabaseClient -->|queries| SupabaseDB
    SupabaseClient -->|auth| SupabaseAuth

    %% Core
    Contracts -->|provides| AuthRepo
    Contracts -->|provides| InventoryRepo
    Contracts -->|provides| MenuRepo
    Contracts -->|provides| OrderRepo
    Contracts -->|provides| AnalyticsRepo
    Contracts -->|provides| ExportRepo
    Contracts -->|provides| SettingsLocalDS

    EnvValidator -->|validates| SupabaseClient
    UtilsMixins -->|mixed into| RealtimeManager

    %% Click Events
    click FlutterApp "https://github.com/yata-repos/yata/blob/main/lib/app/app.dart"
    click Mobile "https://github.com/yata-repos/yata/blob/main/lib/app/main.dart"
    click Router "https://github.com/yata-repos/yata/blob/main/lib/app/router/app_router.dart"
    click Router "https://github.com/yata-repos/yata/blob/main/lib/app/router/routes.dart"
    click Router "https://github.com/yata-repos/yata/blob/main/lib/app/router/guards/auth_guard.dart"
    click Widgets "https://github.com/yata-repos/yata/tree/main/lib/features/auth/presentation"
    click AuthService "https://github.com/yata-repos/yata/blob/main/lib/features/auth/services/auth_service.dart"
    click AuthRepo "https://github.com/yata-repos/yata/blob/main/lib/features/auth/repositories/auth_repository.dart"
    click InventoryService "https://github.com/yata-repos/yata/blob/main/lib/features/inventory/services/inventory_service.dart"
    click InventoryRepo "https://github.com/yata-repos/yata/tree/main/lib/features/inventory/repositories"
    click MenuService "https://github.com/yata-repos/yata/blob/main/lib/features/menu/services/menu_service.dart"
    click MenuRepo "https://github.com/yata-repos/yata/tree/main/lib/features/menu/repositories"
    click OrderService "https://github.com/yata-repos/yata/tree/main/lib/features/order/services"
    click OrderRepo "https://github.com/yata-repos/yata/tree/main/lib/features/order/repositories"
    click AnalyticsService "https://github.com/yata-repos/yata/blob/main/lib/features/analytics/services/analytics_service.dart"
    click AnalyticsRepo "https://github.com/yata-repos/yata/blob/main/lib/features/analytics/repositories/daily_summary_repository.dart"
    click CSVExportService "https://github.com/yata-repos/yata/blob/main/lib/features/export/services/csv_export_service.dart"
    click ExportRepo "https://github.com/yata-repos/yata/tree/main/lib/features/export/repositories"
    click SettingsService "https://github.com/yata-repos/yata/blob/main/lib/features/settings/services/settings_service.dart"
    click SettingsLocalDS "https://github.com/yata-repos/yata/blob/main/lib/features/settings/data/settings_local_data_source.dart"
    click Contracts "https://github.com/yata-repos/yata/tree/main/lib/core/contracts/"
    click LoggerBinding "https://github.com/yata-repos/yata/blob/main/lib/core/logging/logger_binding.dart"
    click EnvValidator "https://github.com/yata-repos/yata/blob/main/lib/core/validation/env_validator.dart"
    click SupabaseClient "https://github.com/yata-repos/yata/blob/main/lib/infra/supabase/supabase_client.dart"
    click CacheManager "https://github.com/yata-repos/yata/blob/main/lib/infra/local/cache/cache_manager.dart"
    click CacheManager "https://github.com/yata-repos/yata/blob/main/lib/infra/local/cache/cache_strategy.dart"
    click CacheManager "https://github.com/yata-repos/yata/blob/main/lib/infra/local/cache/ttl_cache.dart"
    click OfflineQueue "https://github.com/yata-repos/yata/tree/main/lib/infra/local/offline_queue/"
    click RealtimeManager "https://github.com/yata-repos/yata/blob/main/lib/infra/realtime/realtime_manager.dart"
    click RealtimeManager "https://github.com/yata-repos/yata/blob/main/lib/infra/realtime/realtime_manager_adapter.dart"
    click LoggingAdapters "https://github.com/yata-repos/yata/blob/main/lib/infra/logging/logger_adapter.dart"
    click LoggingAdapters "https://github.com/yata-repos/yata/blob/main/lib/infra/logging/analytics_logger_adapter.dart"
    click LoggingAdapters "https://github.com/yata-repos/yata/blob/main/lib/infra/logging/sinks.dart"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,color:#000
    classDef domain fill:#D0FFD8,stroke:#028A0F,color:#000
    classDef data fill:#FFE7C0,stroke:#BF7700,color:#000
    classDef infra fill:#EEDCFF,stroke:#7A00BF,color:#000
    classDef external fill:#E0E0E0,stroke:#555,color:#000
    classDef core fill:#F5F5F5,stroke:#888,color:#000
```
