|
| 1 | +# Auth Module |
| 2 | + |
| 3 | +Self-contained authentication feature module using MVVM + Repository pattern. |
| 4 | + |
| 5 | +## Structure |
| 6 | + |
| 7 | +``` |
| 8 | +auth/ |
| 9 | +├── data/ |
| 10 | +│ ├── api/ # Retrofit API service |
| 11 | +│ ├── datastore/ # Token persistence (DataStore) |
| 12 | +│ ├── di/ # Hilt modules |
| 13 | +│ ├── dto/ # API response models |
| 14 | +│ ├── repository/ # AuthRepository implementation |
| 15 | +│ ├── tokenholder/ # In-memory token storage |
| 16 | +│ └── workmanager/ # Background token refresh |
| 17 | +├── domain/ |
| 18 | +│ ├── model/ # Domain models |
| 19 | +│ └── repository/ # Repository interface |
| 20 | +└── presentation/ |
| 21 | + ├── screen/ # Login screens (QR, Username) |
| 22 | + ├── state/ # UI state classes |
| 23 | + └── viewmodel/ # AuthViewModel |
| 24 | +``` |
| 25 | + |
| 26 | +## API Endpoints |
| 27 | + |
| 28 | +| Endpoint | Method | Purpose | |
| 29 | +|----------|--------|---------| |
| 30 | +| `/auth/login` | POST | Username/password login | |
| 31 | +| `/auth/pair?code=` | GET | QR code pairing | |
| 32 | +| `/auth/refresh` | POST | Token refresh | |
| 33 | +| `/auth/users` | GET | Get all users | |
| 34 | +| `/auth/profile/create` | POST | Create user | |
| 35 | + |
| 36 | +## Authentication Flows |
| 37 | + |
| 38 | +### Username/Password |
| 39 | +1. User enters server URL + credentials |
| 40 | +2. ViewModel validates input, calls API |
| 41 | +3. Tokens stored in DataStore + memory |
| 42 | +4. Navigate to home |
| 43 | + |
| 44 | +### QR Code |
| 45 | +1. Scan QR from web client (format: `URL CODE`) |
| 46 | +2. API call to `/auth/pair` |
| 47 | +3. Same token storage and navigation |
| 48 | + |
| 49 | +### Token Refresh |
| 50 | +- `TokenRefreshWorker` runs every 6 hours via WorkManager |
| 51 | +- Automatically refreshes tokens in background |
| 52 | + |
| 53 | +## Key Classes |
| 54 | + |
| 55 | +| Class | Location | Responsibility | |
| 56 | +|-------|----------|----------------| |
| 57 | +| `AuthApiService` | `data/api/` | Retrofit API calls | |
| 58 | +| `AuthTokensDataStore` | `data/datastore/` | Persistent token storage | |
| 59 | +| `AuthTokenHolder` | `data/tokenholder/` | In-memory token access | |
| 60 | +| `DataAuthRepository` | `data/repository/` | Coordinates API + storage | |
| 61 | +| `AuthViewModel` | `presentation/viewmodel/` | UI state management | |
| 62 | +| `LoginWithQrCode` | `presentation/screen/` | QR scanner screen | |
| 63 | +| `LoginWithUsername` | `presentation/screen/` | Form login screen | |
| 64 | + |
| 65 | +## State Management |
| 66 | + |
| 67 | +```kotlin |
| 68 | +data class AuthUiState( |
| 69 | + val baseUrl: String?, |
| 70 | + val username: String?, |
| 71 | + val password: String?, |
| 72 | + val authState: AuthState, // LOGGED_OUT | AUTHENTICATED |
| 73 | + val isLoading: Boolean, |
| 74 | + val authError: AuthError // None | InputError | LoginError |
| 75 | +) |
| 76 | +``` |
| 77 | + |
| 78 | +## Dependencies |
| 79 | + |
| 80 | +- `:database` - User entity, DAOs |
| 81 | +- `:core` - Resource wrapper |
| 82 | +- `:uicomponent` - UI components |
| 83 | + |
| 84 | +## Error Codes |
| 85 | + |
| 86 | +- `401` - Incorrect password |
| 87 | +- `404` - User not found |
0 commit comments