app/db_engine.py

@@ -30,7 +30,15 @@ if DATABASE_TYPE.lower() == "postgresql":
         autorollback=True,  # Automatically rollback failed transactions
     )
 else:
-    # Default SQLite configuration for local development
+    # SQLite configuration for local development only.
+    # Production always uses PostgreSQL (see DATABASE_TYPE env var).
+    #
+    # synchronous=0 (OFF): SQLite skips fsync() after every write, maximising
+    # throughput at the cost of durability — a hard crash could corrupt the DB.
+    # This is an acceptable trade-off in dev where data loss is tolerable and
+    # write speed matters.  WAL journal mode reduces (but does not eliminate)
+    # the corruption window by keeping the main database file consistent while
+    # writes land in the WAL file first.
     db = SqliteDatabase(
         "storage/pd_master.db",
         pragmas={"journal_mode": "wal", "cache_size": -1 * 64000, "synchronous": 0},