feat: Add support for Demo DB (#237)

* feat: Add support for Demo DB

Enable a Demo DB to trial the application without the need to introduce credentials.

Disabled NVIDIA: There seems to be a bug generating Demos with stock that went through a split scenario

* feat: Enhance demo database functionality and update handling

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: ctasada

.gitignore

@@ -60,6 +60,8 @@ coverage.xml
 *.log
 local_settings.py
 *.sqlite3
+# Exception: Allow bundled demo database template for distribution
+!src/stonks_overwatch/fixtures/demo_db.sqlite3
 *.sqlite3-journal
 
 # Flask stuff:

CHANGELOG.md

@@ -10,6 +10,8 @@ _This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) a
 
 ### Added
 
+- **Application:**
+    - Added "Demo Mode" for exploring the application without a broker connection
 - **Dividends**:
     - Added diversification filter by year
     - Added calendar navigation bars to quickly switch between years
@@ -68,6 +70,7 @@ _This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) a
     - Added tooltip showing the Gross/Tax dividend breakdown
 - **Application:**
     - Added "Release Notes" information
+    - Added "Demo Mode" for exploring the application without a broker connection
 
 ### Changed
 

docs/Developing-Stonks-Overwatch.md

@@ -1,6 +1,8 @@
 # Developing Stonks Overwatch
 
-Stonks Overwatch is a portfolio tracker integrating with multiple brokers (DeGiro, Bitvavo, IBKR) using a **unified modern architecture** (2025). The system features factory patterns, dependency injection, interface-based design, and a centralized broker registry that dramatically simplifies development and maintenance.
+Stonks Overwatch is a portfolio tracker integrating with multiple brokers (DeGiro, Bitvavo, IBKR) using a
+**unified modern architecture** (2025). The system features factory patterns, dependency injection,
+interface-based design, and a centralized broker registry that dramatically simplifies development and maintenance.
 
 ## First Steps
 
@@ -151,7 +153,7 @@ for broker in ["degiro", "bitvavo", "ibkr"]:
             print(f"❌ {broker} {service_type.value}: {e}")
 ```
 
-The demo database can use used with `make run demo=true`
+The demo database can be used with `make run demo=true`. The application will automatically route all database operations to the demo database using the built-in database routing system.
 
 ```shell
 make briefcase-package
@@ -232,15 +234,112 @@ The modern configuration supports multiple brokers:
 
 ### Create a Demo Database
 
+The demo database allows users to explore the application features without connecting to real broker accounts. It contains synthetic transaction data and market information for demonstration purposes.
+
+#### For Developers: Generating the Demo Database
+
+To regenerate the demo database from scratch:
+
+```shell
+poetry run python -m scripts.generate_demo_db \
+    --start-date "2024-01-01" \
+    --num-transactions 150 \
+    --initial-deposit 10000 \
+    --monthly-deposit 500
+```
+
+This command will:
+1. Create a fresh demo database with synthetic transaction data
+2. Generate realistic market data for popular stocks and ETFs
+3. Copy the database to `src/stonks_overwatch/fixtures/demo_db.sqlite3` for bundling with Briefcase distributions
+4. The bundled template should be committed to version control
+
+For more details on available parameters:
+
 ```shell
-poetry run python ./scripts/generate_demo_db.py --help
+poetry run python -m scripts.generate_demo_db --help
 ```
 
-This command will create a demo database with sample data for multiple brokers. It is useful for testing purposes or to showcase the application without needing real broker accounts.
+> **Important**: After generating a new demo database, commit the updated `src/stonks_overwatch/fixtures/demo_db.sqlite3` file to git. This ensures the latest demo data is bundled with all distributions.
+
+#### For Users: Demo Mode in the Native App
+
+When users activate demo mode via the application menu:
+1. The application checks if a demo database exists in the user's data directory
+2. If the bundled demo database is different (detected by comparing SHA256 hashes):
+   - The existing demo database is backed up to `demo_db.sqlite3.backup`
+   - The new demo database is copied from the application bundle
+   - This ensures users always get the latest demo data after app updates
+3. The application switches to demo mode and applies any pending migrations
+4. All broker API connections are disabled in demo mode
+
+The demo database is distributed as a pre-populated SQLite file (approximately 384KB), providing instant access to demo features.
+
+> **Note**: When updating the application to a new version with updated demo data, the old demo database is automatically backed up. Users' actual portfolio data in the production database is never affected by demo mode operations.
+
+#### Demo Database Location
+
+- **Bundled template**: `src/stonks_overwatch/fixtures/demo_db.sqlite3` (read-only, in git)
+- **User's working copy**: `$STONKS_OVERWATCH_DATA_DIR/demo_db.sqlite3` (created on first demo activation)
+
+The demo database can be used with `make run demo=true`. The application will automatically route all database operations to the demo database using the built-in database routing system.
+
+### Demo Mode Database Routing
+
+The application features an advanced database routing system that allows seamless switching between production and demo databases without requiring server restarts.
+
+#### How It Works
+
+The application supports two database configurations:
+- **Production Database** (`db.sqlite3`): Contains real user data
+- **Demo Database** (`demo_db.sqlite3`): Contains demo/sample data for testing
 
-> This script expects the `config/config.json` file to be present and properly configured.
+The `DatabaseRouter` class automatically routes all database operations to the appropriate database based on the `DEMO_MODE` environment variable:
+
+- When `DEMO_MODE=False` (or unset): Routes to the production database
+- When `DEMO_MODE=True`: Routes to the demo database
+
+#### Database Configuration
+
+Both databases are defined in `settings.py`:
+
+```python
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": Path(STONKS_OVERWATCH_DATA_DIR).resolve().joinpath("db.sqlite3"),
+        # ... production database settings
+    },
+    "demo": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": Path(STONKS_OVERWATCH_DATA_DIR).resolve().joinpath("demo_db.sqlite3"),
+        # ... demo database settings
+    },
+}
+
+DATABASE_ROUTERS = ["stonks_overwatch.utils.database.db_router.DatabaseRouter"]
+```
+
+#### Benefits of Database Routing
+
+1. **No Server Restart Required**: Database switching happens instantly
+2. **Data Isolation**: Production and demo data are completely separate
+3. **Transparent Operation**: All existing code works without modification
+4. **Consistent Schema**: Both databases maintain the same structure through migrations
+
+#### Migration Handling
+
+Both databases support migrations independently:
+
+```shell
+# Apply migrations to production database
+python manage.py migrate --database=default
+
+# Apply migrations to demo database
+python manage.py migrate --database=demo
+```
 
-The demo database can be used with `make run demo=true`
+The router ensures migrations can be applied to both databases as needed, maintaining schema consistency.
 
 ## Dump and Load a Database
 
@@ -275,7 +374,7 @@ Example configuration to enable offline mode for multiple brokers:
 }
 ```
 
-The offline mode can be used together with `demo=true` to load the demo database and run the application without any external API calls.
+The offline mode can be used together with `demo=true` to load the demo database and run the application without any external API calls. The database routing system ensures that demo data is completely isolated from production data, making it safe to experiment with different configurations.
 
 ### Broker-Specific Development
 

scripts/dump_db.py

@@ -14,7 +14,6 @@
 
 import argparse
 import os
-from pathlib import Path
 
 # Django setup
 from django.core import serializers
@@ -26,17 +25,20 @@
 # Set up Django environment and logging
 setup_script_environment()
 
-from stonks_overwatch.settings import STONKS_OVERWATCH_DATA_DIR  # noqa: E402
+from stonks_overwatch.settings import DATABASES  # noqa: E402
 from stonks_overwatch.utils.database.db_utils import dump_database  # noqa: E402
 
 
-def load_database(input_file):
+def load_database(input_file, database="default"):
     """Load database content from the JSON file"""
     if not os.path.exists(input_file):
         print(f"Error: Input file {input_file} not found")
         return
 
-    existing_db_file = Path(STONKS_OVERWATCH_DATA_DIR).resolve().joinpath("db.sqlite3")
+    if database == "demo":
+        os.environ["DEMO_MODE"] = "True"
+
+    existing_db_file = DATABASES[database]["NAME"]
 
     if os.path.exists(existing_db_file):
         print(f"Warning: Existing database file '{existing_db_file}' found.")
@@ -61,7 +63,7 @@ def load_database(input_file):
             return
 
     print("Creating new database...")
-    call_command("migrate")
+    call_command("migrate", database=database)
 
     print(f"Loading database from {input_file}...")
 
@@ -70,11 +72,11 @@ def load_database(input_file):
         with open(input_file, "r", encoding="utf-8") as f:
             data = f.read()
 
-        # Deserialize and save
+        # Deserialize and save to the correct database
         objects_loaded = 0
-        with transaction.atomic():
+        with transaction.atomic(using=database):
             for obj in serializers.deserialize("json", data):
-                obj.save()
+                obj.save(using=database)
                 objects_loaded += 1
 
         print(f"Successfully loaded {objects_loaded} objects from {input_file}")
@@ -91,10 +93,24 @@ def main():
     # Dump command
     dump_parser = subparsers.add_parser("dump", help="Dump database to file")
     dump_parser.add_argument("--output", "-o", default="db_dump.zip", help="Output file name (default: db_dump.zip)")
+    dump_parser.add_argument(
+        "--database",
+        "-d",
+        default="default",
+        choices=["default", "demo"],
+        help="Database to use (default: default, options: default, demo)",
+    )
 
     # Load command
     load_parser = subparsers.add_parser("load", help="Load database from file")
     load_parser.add_argument("--input", "-i", required=True, help="Input file name")
+    load_parser.add_argument(
+        "--database",
+        "-d",
+        default="default",
+        choices=["default", "demo"],
+        help="Database to use (default: default, options: default, demo)",
+    )
 
     args = parser.parse_args()
 
@@ -103,9 +119,9 @@ def main():
         return
 
     if args.command == "dump":
-        dump_database(output_file=args.output)
+        dump_database(output_file=args.output, database=args.database)
     elif args.command == "load":
-        load_database(input_file=args.input)
+        load_database(input_file=args.input, database=args.database)
 
 
 if __name__ == "__main__":