GigLedger Architecture Expert

Purpose

This skill provides deep expertise on GigLedger's application architecture:

• •[Architecture pattern] architecture
• •Feature-based directory structure
• •[State management] patterns
• •Data flow and layer responsibilities
• •Testing strategy per layer

Source of Truth

Primary Reference: docs/07_app_architecture.md

This document is the authoritative source for all architectural decisions.

Layer Architecture

Every feature in GigLedger follows this structure:

lib/features/{feature_name}/
├── presentation/
│   ├── pages/           # Screen components
│   ├── widgets/         # Reusable UI components
│   └── providers/       # State management
│
├── application/
│   ├── use_cases/       # Business logic operations
│   └── services/        # Coordinating services
│
├── domain/
│   ├── models/          # Core business entities
│   └── repositories/    # Repository interfaces (contracts)
│
└── data/
    ├── dto/             # Data Transfer Objects
    ├── data_sources/    # Database/API implementations
    └── repository_impl/ # Repository interface implementations

Layer Responsibilities

Presentation Layer

What it does:

• •Displays UI
• •Manages user interactions
• •Holds screen-specific state
• •Reacts to state changes

What it CANNOT do:

• •Call repositories directly
• •Contain business logic
• •Make API/database calls
• •Transform DTOs to domain models

Dependencies: Application layer only (use cases)

Application Layer

What it does:

• •Implements use cases (business operations)
• •Orchestrates data flow
• •Calls repository interfaces
• •Transforms domain models for presentation

What it CANNOT do:

• •Know about UI
• •Know about database/DTOs
• •Call data sources directly

Dependencies: Domain layer only (models, repository interfaces)

Domain Layer

What it does:

• •Defines core business entities (models)
• •Defines repository contracts (interfaces)
• •Contains business rules and validation
• •Platform and framework agnostic

What it CANNOT do:

• •Know about database/DTOs
• •Know about UI
• •Contain implementation details

Dependencies: None (pure code)

Data Layer

What it does:

• •Implements repository interfaces from domain
• •Communicates with database/external APIs
• •Transforms DTOs ↔ domain models
• •Handles caching and error recovery

What it CANNOT do:

• •Contain business logic
• •Be called directly by presentation layer

Dependencies: Domain layer (implements interfaces, uses models)

Data Flow

The complete data flow through all layers:

User Action (UI)
  ↓
Presentation Layer (Component/Provider)
  ↓
Application Layer (Use Case)
  ↓
Domain Layer (Repository Interface)
  ↓
Data Layer (Repository Implementation)
  ↓
Database / Backend
  ↓
Data Layer (DTO → Domain Model)
  ↓
Application Layer (Business Logic)
  ↓
Presentation Layer (Display)

State Management

Provider/State Types

Reference your framework's state management patterns here.

State Guidelines

• •One state object per screen
• •Immutable state
• •Async data handled properly

Feature Module Structure

When creating a new feature (e.g., profile):

mkdir -p lib/features/profile/{presentation,application,domain,data}
mkdir -p lib/features/profile/presentation/{pages,widgets,providers}
mkdir -p lib/features/profile/application/{use_cases,services}
mkdir -p lib/features/profile/domain/{models,repositories}
mkdir -p lib/features/profile/data/{dto,data_sources,repository_impl}

Testing Strategy per Layer

Reference: docs/07_app_architecture.md testing section

Unit Tests

What to test:

• •Domain models (business logic methods)
• •Use cases (application layer)
• •DTO transformations
• •Repository implementations (mocked database)

Widget/Component Tests

What to test:

• •Screen rendering
• •User interactions
• •State transitions
• •Error states

Integration Tests

What to test:

• •Database read flows (with emulator if available)
• •Navigation paths
• •End-to-end user journeys

Core Module (Shared Code)

Shared utilities live in lib/core/:

lib/core/
├── config/          # Configuration
├── constants/       # App-wide constants
├── domain/models/   # Shared domain models
├── error/           # Error types and handlers
├── logging/         # Logging utilities
├── network/         # Network utilities
├── services/        # Shared services
├── theme/           # Theming
├── utils/           # Helper functions
└── widgets/         # Shared widgets

Critical Architectural Rules

1. Never Skip Layers

Wrong: Presentation → Data Correct: Presentation → Application → Domain → Data

2. Dependencies Point Inward

• •Presentation depends on Application
• •Application depends on Domain
• •Data depends on Domain (implements interfaces)
• •Domain depends on nothing

3. DTOs Stay in Data Layer

Wrong: Pass DTOs to use cases or presentation Correct: Transform DTOs to domain models in data layer

4. Business Logic in Use Cases

Wrong: Business logic in widgets or repositories Correct: Business logic in application layer use cases

5. State Management for All State

Wrong: Local component state for shared data Correct: Proper state management providers

Platform Considerations

• •Responsive layouts
• •Test on all target platforms
• •Avoid platform-specific code where possible
• •Optimize for performance

Performance Best Practices

• •Enable database persistence (offline cache)
• •Avoid rebuilding expensive components
• •Cache computed data in memory
• •Use pagination for large lists

When to Use This Skill

Use this skill when:

• •Creating a new feature module
• •Understanding layer responsibilities
• •Setting up state providers
• •Writing tests for specific layers
• •Refactoring code to follow architecture
• •Reviewing code for architectural compliance

Quick Reference Checklist

When implementing a feature:

• • Create four-layer directory structure
• • Define domain models (pure code, no dependencies)
• • Define repository interface in domain layer
• • Implement repository in data layer with DTOs
• • Create use case in application layer
• • Set up state providers in presentation layer
• • Build UI components consuming providers
• • Write unit tests for use cases and models
• • Write component tests for screens
• • Verify no layers are skipped in data flow

Summary

GigLedger's architecture ensures:

• •Clean separation of concerns
• •Testability at every layer
• •Scalability for future features
• •Framework independence in domain layer
• •Consistent patterns across all features

Remember: Always reference docs/07_app_architecture.md as the ultimate source of truth for architectural decisions.