From 6592b3575599271765be1c08f6d2cfb01cebb49e Mon Sep 17 00:00:00 2001
From: Maxiwere45 <amdjad9857@gmail.com>
Date: Tue, 17 Mar 2026 16:05:17 +0100
Subject: [PATCH] docs: Add initial project README and architecture
 documentation.

---
 docs/ARCHITECTURE.md | 32 ++++++++++++++++++++++++++++++++
 docs/README.md       | 28 ++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 docs/ARCHITECTURE.md
 create mode 100644 docs/README.md

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..2508680
--- /dev/null
+++ b/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.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..999aba1
--- /dev/null
+++ b/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.