99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
# 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
|