5.1 KiB
5.1 KiB
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
- UI Layer (Screens) → Consumes providers via Riverpod
- Provider Layer → Manages state and coordinates repositories
- Repository Layer → Orchestrates services and database operations
- Service Layer → Handles business logic (HTTP, parsing, etc.)
- 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