docs: Add initial project README and architecture documentation.

docs/ARCHITECTURE.md

@@ -0,0 +1,32 @@
+# Application Architecture
+
+## Overview
+
+The application follows a modular structure separated by responsibilities (models, pages, components, services).
+
+## Layers
+
+### 1. Data Layer
+
+- **Models**: `Pokemon` class defines the data structure for a Pokemon, including serialization/deserialization logic.
+- **API**: `PokemonApi` handles communication with the Tyradex REST API using the `http` package.
+- **Database**: `PokedexDatabase` manages local persistence using SQLite (`sqflite`). It uses batch operations for performance during initial sync.
+
+### 2. Business Logic & State
+
+- **State Management**: Uses Flutter's `StatefulWidget` and `setState` for local page state.
+- **Reactivity**: `ValueNotifier` in the database layer notifies the UI when data changes (e.g., catching a Pokemon updates the list).
+- **Persistence**: `shared_preferences` is used for simple key-value storage like best scores.
+
+### 3. UI Layer
+
+- **Pages**: Top-level screens like `MainPage`, `PokemonListPage`, and `GuessPage`.
+- **Components**: Reusable UI elements like `PokemonTile`.
+- **Navigation**: Managed in `MainPage` using `IndexedStack` to preserve tab state across navigation.
+
+## Data Flow
+
+1. At startup, the app checks the local database.
+2. If the database is missing generations, it fetches the full list from Tyradex API and performs a batch insert.
+3. User interactions (like a correct guess) update the local database.
+4. The database triggers a notification, causing relevant UI components to refresh their view.

docs/README.md

@@ -0,0 +1,28 @@
+# Pokeguess
+
+## Description
+
+Pokeguess is a Flutter mobile application that allows users to discover and collect Pokemon through a silhouette guessing game. The app fetch data from the Tyradex API and stores it locally for offline access.
+
+## Features
+
+- National Pokedex: Browse all 1025+ Pokemon from all generations.
+- Guess Game: Identify Pokemon by their silhouette.
+- Scoring System: Earn points for correct guesses, with bonuses for Shiny Pokemon. High scores are saved locally.
+- Collection: Track caught and seen Pokemon.
+- Search and Filter: Filter the collection by all or caught status and search by name.
+
+## Installation
+
+1. Ensure Flutter SDK is installed.
+2. Clone the repository.
+3. Run `flutter pub get` to install dependencies.
+4. Run `flutter run` to start the application.
+
+## Technologies
+
+- Flutter: UI Framework.
+- SQLite (sqflite): Local database.
+- Tyradex API: Pokemon data source.
+- Shared Preferences: High score persistence.
+- Google Fonts: Custom typography.