Merge pull request #5 from tldrwtf/fix

feat: Enhance documentation and synchronization features; update authentication methods and dependencies

Author: tldrwtf

.gitignore

@@ -15,6 +15,9 @@ __pycache__/
 *.class
 scratch.py
 venv/
+.ruff_cache/
+.pytest_cache/
+.venv/
 
 
 # Environment variables

README.md

@@ -32,7 +32,7 @@ A Pokemon-themed CLI task manager and wellbeing tracker. Complete tasks to catch
 - Catch Pokemon by completing tasks
 - **All 1025 Pokemon** from Gen 1 (Kanto) through Gen 9 (Paldea)
 - Pokemon rarity based on task difficulty
-- Pokemon **EVs (Effort Values) and IVs (Individual Values)** for stat training (in progress)
+- Pokemon **EVs (Effort Values) and IVs (Individual Values)** for stat training (partial implementation)
 - Shiny Pokemon (rare variants with boosted rates from streaks)
 - Legendary, Mythical, Pseudo-Legendary, and Ultra Beast encounters
 - Paradox Pokemon from Scarlet/Violet
@@ -102,7 +102,7 @@ pokedo
 ### Initialize
 
 ```bash
-# Full initialization (all 1025 Pokemon - takes a few minutes first time)
+# Full initialization (all 1025 Pokemon, takes a few minutes first time)
 pokedo init --name "Ash"
 
 # Quick start with Gen 1 only (151 Pokemon)
@@ -202,7 +202,7 @@ pokedo stats history --days 14
 
 ### Server Usage (Optional)
 
-PokeDo is developing a FastAPI server to enable cloud synchronization and multi-user features. You can run the development server and test its authentication endpoints.
+PokeDo is developing a FastAPI server to enable cloud synchronization and multi-user features. This system uses `requests` for client-side pushing and `bcrypt` for secure authentication.
 
 1.  **Run the Server:**
 

docs/ARCHITECTURE.md

@@ -21,16 +21,18 @@ PokeDo is a gamified task manager that combines productivity tracking with Pokem
 - **Presentation Layer** (CLI) - User interface and command handling
 - **Business Logic Layer** (Core) - Domain models and game mechanics
 - **Data Access Layer** (Data) - Database operations and API clients
+- **Synchronization Layer** (Sync) - Client-side change queuing and server communication
 
 **Technology Stack:**
 - Python 3.10+
 - Typer (CLI framework)
 - Rich (Terminal UI)
 - Pydantic (Data validation)
 - SQLite (Local storage)
-- FastAPI (Server & Sync)
-- JWT/Bcrypt (Authentication)
-- httpx (Async HTTP client)
+- FastAPI (Server)
+- Bcrypt (Direct password hashing)
+- httpx (Async HTTP client for PokeAPI)
+- requests (Sync HTTP client for Server Sync)
 
 ---
 
@@ -44,16 +46,17 @@ pokedo/
 │   ├── app.py            # Main Typer application
 │   └── ...
 ├── core/                 # Business Logic Layer
-│   ├── auth.py           # NEW: Authentication logic
+│   ├── auth.py           # Authentication logic (Bcrypt/JWT)
 │   ├── task.py           # Task model and enums
 │   ├── trainer.py        # Trainer model and progression
 │   ├── pokemon.py        # Pokemon and Pokedex models
 │   ├── rewards.py        # Encounter and reward system
 │   └── wellbeing.py      # Wellbeing tracking models
 ├── data/                 # Data Access Layer
 │   ├── database.py       # SQLite operations
-│   └── pokeapi.py        # PokeAPI client
-├── server.py             # NEW: FastAPI server entry point
+│   ├── pokeapi.py        # PokeAPI client
+│   └── sync.py           # NEW: Sync client and change queue
+├── server.py             # FastAPI server entry point
 └── utils/                # Utilities
     ├── config.py         # Configuration management
     └── helpers.py        # Helper functions
@@ -96,7 +99,7 @@ Handles centralized operations and synchronization.
 The core layer contains domain models and game logic.
 
 **`auth.py`** - Authentication
-- Password hashing (Bcrypt)
+- Password hashing (Direct Bcrypt usage)
 - JWT Token generation and verification
 
 **`task.py`** - Task Management
@@ -157,23 +160,42 @@ class DailyWellbeing:
 - Query builders
 
 **`pokeapi.py`** - External API Client
-- Async HTTP client using httpx
+- Async HTTP client using `httpx`
 - Response caching (JSON files)
 - Sprite downloading
 - Evolution chain parsing
 
-### Utilities (`utils/`)
+**`sync.py`** - Synchronization Client
+- Local change queue management (SQLModel `Change` entity)
+- Sync push operations using `requests`
 
-**`config.py`** - Configuration
-- Data directory paths
-- Game constants (XP values, catch rates)
-- Generation ID ranges
-- Rarity thresholds
+---
+
+## Synchronization Layer
+
+This layer enables local-first data handling with cloud synchronization.
+
+**Concept:**
+- **Local-First:** All user actions (Task Create, Pokemon Catch) are committed to the local SQLite database immediately.
+- **Change Queue:** Simultaneously, a record of the action is written to a `change` table in the local DB.
+- **Push Sync:** A background process (or manual command) reads unsynced changes from the `change` table and pushes them to the server via HTTP POST.
+
+**Change Entity:**
+```python
+class Change(SQLModel):
+    id: str (UUID)
+    entity_id: str
+    entity_type: str (e.g., "task", "pokemon")
+    action: str (CREATE, UPDATE, DELETE)
+    payload: JSON
+    timestamp: datetime
+    synced: bool
+```
 
-**`helpers.py`** - Helper Functions
-- Date parsing and formatting
-- Input validation
-- Common utilities
+**Sync Process:**
+1.  `queue_change()`: Called by CRUD functions in `database.py` whenever data modifies.
+2.  `push_changes()`: Reads unsynced records, sends to `POST /sync`.
+3.  On 200 OK, marks records as `synced=True`.
 
 ---
 
@@ -182,7 +204,7 @@ class DailyWellbeing:
 ### Task Completion Flow
 
 ```
-User Input -> CLI Command -> Validate Input -> Database Update
+User Input -> CLI Command -> Validate Input -> Database Update -> Queue Change
                                                     |
                                                     v
 Display Result <- UI Components <- Reward System <- Calculate Rewards
@@ -194,7 +216,7 @@ Display Result <- UI Components <- Reward System <- Calculate Rewards
                                    Catch Attempt
                                          |
                                          v
-                                   Update Database
+                                   Update Database -> Queue Change
 ```
 
 ### Pokemon Encounter Flow

docs/CONTRIBUTING.md

@@ -21,14 +21,14 @@
 
 ### Installation
 
-1. Clone the repository:
+1.  Clone the repository:
 
     ```bash
     git clone https://github.com/tldrwtf/pokedo.git
     cd pokedo
     ```
 
-1. Create a virtual environment:
+2.  Create a virtual environment:
 
     ```bash
     python -m venv venv
@@ -40,13 +40,13 @@
     source venv/bin/activate
     ```
 
-1. Install development dependencies (formatter, linter, tests):
+3.  Install development dependencies (formatter, linter, tests):
 
     ```bash
     pip install -e ".[dev]"
     ```
 
-1. Initialize the application (for testing):
+4.  Initialize the application (for testing):
 
     ```bash
     pokedo init --name "Developer" --quick

docs/EV_IV_SPEC.md

@@ -1,4 +1,4 @@
-# EV / IV Spec (Pokedo Expansion) — Minimal Reference
+# EV / IV Spec (Pokedo Expansion) - Minimal Reference
 
 **Status:** Partially Implemented (Core Models & Helpers done; DB persistence pending)
 

docs/GETTING_STARTED.md

@@ -1,50 +1,83 @@
 # Getting Started (Developer)
 
-Prereqs:
+## Prerequisites
 
-- Python 3.11+, pip
-- Docker (for postgres) — optional for server dev
+- Python 3.10+
+- pip (Python package manager)
+- Docker (Optional, for future PostgreSQL support)
 
-Install:
-Windows cmd.exe:
+## Installation
 
-```
+**Windows (cmd.exe):**
+
+```cmd
 python -m venv .venv
-.venv\\Scripts\\activate
+.venv\Scripts\activate
 pip install -e ".[dev]"
 ```
 
-Run CLI examples:
+**Linux/macOS:**
 
-```
-python -m pokedo.cli.app init-db
-python -m pokedo.cli.app add-task "Finish report" --category work --difficulty medium
-python -m pokedo.cli.app add-pokemon "Starter"
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
 ```
 
-Run server (dev):
+## Running the CLI
 
-```
-# Starts FastAPI server on port 8000 with hot reload
+1.  **Initialize the Database:**
+    This downloads the initial Pokemon data cache.
+
+    ```bash
+    pokedo init --name "Dev" --quick
+    ```
+
+2.  **Basic Commands:**
+
+    ```bash
+    pokedo task add "Finish report" --category work --difficulty medium
+    pokedo task list
+    pokedo pokemon box
+    ```
+
+## Running the Server
+
+To test the synchronization features, you can run the local FastAPI development server.
+
+```bash
 uvicorn pokedo.server:app --reload --port 8000
 ```
 
-Test Auth:
+## Testing Authentication
 
-```bash
-# 1. Register
-curl -X POST http://localhost:8000/register -H "Content-Type: application/json" -d "{\"username\": \"me\", \"password\": \"secret\"}"
+You can use `curl` to test the registration and login flow.
 
-# 2. Login
-curl -X POST http://localhost:8000/token -F "username=me" -F "password=secret"
+**1. Register a user:**
+
+```bash
+curl -X POST http://localhost:8000/register \
+  -H "Content-Type: application/json" \
+  -d "{\"username\": \"me\", \"password\": \"secret\"}"
 ```
 
-Run tests:
+**2. Login to get a token:**
 
+```bash
+curl -X POST http://localhost:8000/token \
+  -F "username=me" \
+  -F "password=secret"
 ```
-pytest -q
+
+## Running Tests
+
+Run the full test suite to ensure everything is working correctly.
+
+```bash
+pytest
 ```
 
-Notes:
+## Notes
 
-- The repo uses a local-first SQLite DB for the CLI; if you start Postgres (via docker-compose), set `DATABASE_URL` accordingly.
+- The application uses a local-first SQLite database by default (`~/.pokedo/pokedo.db`).
+- If you are working on the Sync client, remember to initialize the sync table: `python -m pokedo.data.sync init`.