first commit

api/scripts/README.md

@@ -0,0 +1,124 @@
+# Scripts Directory
+
+This directory contains utility scripts for database initialization, migrations, and other maintenance tasks.
+
+## Database Initialization
+
+### `init_database.py`
+
+Initializes all database tables in Appwrite with the correct schema, columns, and indexes.
+
+**Usage:**
+
+```bash
+# Ensure virtual environment is activated
+source venv/bin/activate
+
+# Run the initialization script
+python scripts/init_database.py
+```
+
+**Prerequisites:**
+
+1. Appwrite instance running and accessible
+2. `.env` file configured with Appwrite credentials:
+   - `APPWRITE_ENDPOINT`
+   - `APPWRITE_PROJECT_ID`
+   - `APPWRITE_API_KEY`
+   - `APPWRITE_DATABASE_ID`
+
+**What it does:**
+
+1. Validates environment configuration
+2. Creates the following tables:
+   - **characters**: Player character data with userId indexing
+
+3. Creates necessary columns and indexes for efficient querying
+4. Skips tables/columns/indexes that already exist (idempotent)
+
+**Output:**
+
+```
+============================================================
+Code of Conquest - Database Initialization
+============================================================
+
+✓ Environment variables loaded
+  Endpoint: https://your-appwrite-instance.com/v1
+  Project: your-project-id
+  Database: main
+
+Initializing database tables...
+
+============================================================
+Initialization Results
+============================================================
+
+✓ characters: SUCCESS
+
+Total: 1 succeeded, 0 failed
+
+✓ All tables initialized successfully!
+
+You can now start the application.
+```
+
+## Adding New Tables
+
+To add a new table to the initialization process:
+
+1. Open `app/services/database_init.py`
+2. Create a new method following the pattern of `init_characters_table()`
+3. Add the table initialization to `init_all_tables()` method
+4. Run the initialization script
+
+Example:
+
+```python
+def init_sessions_table(self) -> bool:
+    """Initialize the sessions table."""
+    table_id = 'sessions'
+
+    # Create table
+    table = self.tables_db.create_table(
+        database_id=self.database_id,
+        table_id=table_id,
+        name='Sessions'
+    )
+
+    # Create columns
+    self._create_column(
+        table_id=table_id,
+        column_id='userId',
+        column_type='string',
+        size=255,
+        required=True
+    )
+
+    # Create indexes
+    self._create_index(
+        table_id=table_id,
+        index_id='idx_userId',
+        index_type='key',
+        attributes=['userId']
+    )
+
+    return True
+```
+
+## Troubleshooting
+
+### Missing Environment Variables
+
+If you see errors about missing environment variables, ensure your `.env` file contains all required Appwrite configuration.
+
+### Connection Errors
+
+If the script cannot connect to Appwrite:
+- Verify the `APPWRITE_ENDPOINT` is correct and accessible
+- Check that the API key has sufficient permissions
+- Ensure the database exists in your Appwrite project
+
+### Column/Index Already Exists
+
+The script is idempotent and will log warnings for existing columns/indexes without failing. This is normal if you run the script multiple times.