# Codebase Structure

## Directory Layout

```
worldhopper/
├── lib/                          # Main application code
│   ├── main.dart                # Application entry point with ProviderScope
│   ├── app.dart                 # Root App widget with router and theme
│   ├── config/                  # Configuration files
│   │   ├── router.dart          # GoRouter configuration (AppRouter)
│   │   ├── theme.dart           # Material Design 3 theme (AppTheme)
│   │   └── constants.dart       # App-wide constants
│   ├── database/                # SQLite database layer
│   │   ├── database.dart        # DatabaseHelper singleton
│   │   └── tables/              # Table definitions and schemas
│   │       ├── servers_table.dart
│   │       └── reading_progress_table.dart
│   ├── models/                  # Data models (freezed + json_serializable)
│   │   ├── opds_feed.dart       # OPDS feed model
│   │   ├── opds_entry.dart      # OPDS entry/publication model
│   │   ├── opds_link.dart       # OPDS link model
│   │   ├── opds_stream_link.dart # Streaming link model
│   │   ├── opds_server.dart     # Server configuration model
│   │   ├── reading_progress.dart # Reading progress model
│   │   └── *.freezed.dart       # Generated freezed files
│   │   └── *.g.dart             # Generated json_serializable files
│   ├── providers/               # Riverpod providers
│   │   ├── opds_provider.dart   # OPDS-related state
│   │   ├── server_provider.dart # Server management state
│   │   └── reading_progress_provider.dart # Reading progress state
│   ├── repositories/            # Data access layer
│   │   ├── opds_repository.dart         # OPDS data operations
│   │   ├── server_repository.dart       # Server CRUD operations
│   │   └── reading_progress_repository.dart # Progress tracking
│   ├── services/                # Business logic layer
│   │   ├── opds_service.dart    # OPDS feed fetching
│   │   ├── opds_parser.dart     # XML parsing for OPDS
│   │   ├── auth_service.dart    # Authentication handling
│   │   ├── epub_download_service.dart # EPUB download management
│   │   └── url_helper.dart      # URL manipulation utilities
│   ├── screens/                 # UI screens
│   │   ├── browse/              # Feed browsing screens
│   │   │   ├── library_browser_screen.dart
│   │   │   └── feed_screen.dart
│   │   ├── servers/             # Server management screens
│   │   │   ├── server_list_screen.dart
│   │   │   ├── add_server_screen.dart
│   │   │   └── edit_server_screen.dart
│   │   ├── publication/         # Publication details
│   │   │   └── publication_detail_screen.dart
│   │   └── reader/              # Reading screens
│   │       ├── reader_screen.dart
│   │       ├── epub_reader_screen.dart
│   │       └── widgets/         # Reader-specific widgets
│   └── widgets/                 # Reusable UI components
│       ├── publication_card.dart # Publication display card
│       └── server_card.dart     # Server display card
├── test/                        # Test files
│   └── widget_test.dart
├── android/                     # Android-specific code and configuration
├── ios/                         # iOS-specific code and configuration
├── web/                         # Web platform files
├── macos/                       # macOS desktop files
├── linux/                       # Linux desktop files
├── windows/                     # Windows desktop files
├── pubspec.yaml                 # Package dependencies and metadata
├── analysis_options.yaml        # Dart analyzer configuration
└── README.md                    # Project documentation
```

## Code Organization Patterns

### Data Flow
1. **UI Layer (Screens)** → Consumes providers via Riverpod
2. **Provider Layer** → Manages state and coordinates repositories
3. **Repository Layer** → Orchestrates services and database operations
4. **Service Layer** → Handles business logic (HTTP, parsing, etc.)
5. **Database Layer** → SQLite persistence

### Models
- All data models use **Freezed** for immutability and copyWith
- **json_serializable** for JSON serialization
- Generated files (*.freezed.dart, *.g.dart) are committed to git

### State Management
- **Riverpod** with code generation (riverpod_annotation)
- Providers are defined in `lib/providers/`
- Generated providers in *.g.dart files

### Routing
- **GoRouter** configured in `lib/config/router.dart`
- Declarative routing with type-safe navigation

### Database
- **SQLite** with sqflite
- Table definitions in `lib/database/tables/`
- Singleton DatabaseHelper pattern
- Foreign key constraints enabled