# Li Lance Android Seraphim Framework Flutter Retrofit Networking

> Retrofit & Dio Networking

- Skill: `tomevault-io/li-lance-android-seraphim-framework-flutter-retrofit-network` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/li-lance-android-seraphim-framework-flutter-retrofit-network`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/li-lance-android-seraphim-framework-flutter-retrofit-network/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/li-lance-android-seraphim-framework-flutter-retrofit-network

---


# Retrofit & Dio Networking

## **Priority: P0 (CRITICAL)**

Type-safe REST API communication using `Dio` and `Retrofit`.

## Structure

```text
infrastructure/
├── data_sources/
│   ├── remote/       # Retrofit abstract classes
│   └── local/        # Cache/Storage
└── network/
    ├── dio_client.dart    # Custom Dio setup
    └── interceptors/      # Auth, Logging, Cache
```

## Implementation Workflow

1. **Define Retrofit clients** — Create abstract classes with `@RestApi()` and HTTP annotations (
   `@GET`, `@POST`). Methods return `Future<DTO>`.
2. **Create DTOs** — Use `@freezed` and `@JsonSerializable` for all request/response bodies.
3. **Map to domain** — Data sources must map DTOs to Domain Entities (e.g., `userDto.toDomain()`).
4. **Guard enums** — Always use `@JsonKey(unknownEnumValue: Status.unknown)` to prevent crashes from
   new backend values.
5. **Add auth interceptor** — Inject `Authorization: Bearer <token>` in `onRequest`.
6. **Handle token refresh** — On 401, lock Dio, call `refreshToken()`, update stored token, retry
   via `dio.fetch(err.requestOptions)`.
7. **Map failures** — Convert `DioException` to typed `Failure` objects (ServerFailure,
   NetworkFailure).

### Retrofit Client & Safe Enum DTO Examples

See [implementation examples](references/implementation.md) for RestClient definitions and safe enum
DTO patterns.

## Anti-Patterns

- ❌ `jsonDecode(response.body)` — use Retrofit's generated mappers, never manual JSON parsing
- ❌ Static global `Dio` instance — inject Dio via DI; avoid global singletons
- ❌ `try-catch` inside Retrofit interface methods — let the repository layer handle exceptions
- ❌ Enum fields without `unknownEnumValue` — new backend values will crash the app

## Reference & Examples

For RestClient definitions and Auth Interceptor implementation:
See [references/REFERENCE.md](references/REFERENCE.md).

## Related Topics

feature-based-clean-architecture | error-handling

---
> Source: [li-lance/android-seraphim-framework](https://github.com/li-lance/android-seraphim-framework) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->