Flutter + Laravel Clean Architecture Template

Development guidelines for working with a Flutter mobile application and Laravel backend following Clean Architecture principles.

Project Structure

This is a mobile-first application with:

Step-by-Step Development Workflow

1. Understanding the Architecture

**Before making any changes**, familiarize yourself with the architecture:

**Flutter App (Clean Architecture):**

**Laravel Backend:**

**Key Relationships:**

2. Setting Up Development Environment

**Flutter App Setup:**

```bash

cd app/

fvm flutter pub get # Install dependencies

make dev # Switch to development environment

make runner # Run code generation

```

**Laravel Backend Setup:**

```bash

cd backend/

composer install # Install dependencies

php artisan storage:link # Create storage symlink (first time only)

php artisan migrate # Run migrations

php artisan serve # Start dev server

```

3. Making Code Changes

**When adding new features:**

1. **Domain Layer First** - Define your business logic:

- Add entities in `lib/domain/entities/`

- Define repository interfaces in `lib/domain/repositories/`

- Create use cases in `lib/domain/usecases/`

2. **Data Layer** - Implement data access:

- Create models in `lib/data/models/` with JSON serialization

- Implement repositories in `lib/data/repositories/`

- Use `ApiClient` for HTTP requests with automatic token management

3. **Presentation Layer** - Build UI:

- Create feature folders in `lib/ui/`

- Use Provider pattern for state management

- Access global session via `AppSession.instance` when needed

4. **Backend API** - Add Laravel endpoints:

- Create controllers in `app/Http/Controllers/Api/V1/`

- Define routes in `routes/api_v1.php`

- Use resource classes for response formatting

- Implement policies for authorization

**When modifying existing features:**

4. API Design Patterns

**Follow these conventions:**

**Anonymous Access (device-based):**

```

GET /api/v1/devices/by-identifier?identifier={device_id}

GET /api/v1/preferences/by-device?device_identifier={device_id}

```

**Authenticated Access (user-based):**

```

GET /api/v1/devices/me

GET /api/v1/preferences/me

```

**Repository Pattern:**

5. Environment Management

**Switch environments before building:**

```bash

cd app/

make dev # Development

make stg # Staging

make prod # Production

```

**Each environment has:**

6. Building and Testing

**Run tests:**

```bash

cd app/

fvm flutter test --coverage --test-randomize-ordering-seed random

make lint # Run dart fix, format, analyze

```

**Build for production:**

```bash

make build-android-prod # Android APK

make build-ios-prod-ipa # iOS IPA

make build-web-prod # Web build

```

**After code generation changes:**

```bash

make runner # Regenerate build_runner files

```

7. Database Changes

**Laravel migrations:**

```bash

cd backend/

php artisan make:migration create_table_name

php artisan migrate

```

**Remember relationships:**

8. Localization

**After adding new strings:**

```bash

cd app/

fvm flutter gen-l10n

```

Languages supported: English, Spanish

Important Constraints

Common Tasks

**Add a new API endpoint:**

1. Create controller method in `backend/app/Http/Controllers/Api/V1/`

2. Add route in `backend/routes/api_v1.php`

3. Create repository interface in `app/lib/domain/repositories/`

4. Implement repository in `app/lib/data/repositories/`

5. Register in dependency injection (`lib/core/dependencies/`)

**Add a new screen:**

1. Create feature folder in `lib/ui/`

2. Add route to `GoRouter` configuration

3. Create ViewModel with Provider if needed

4. Handle authentication state appropriately

**Debug API issues:**

Key Files Reference