docs: improved write-up

added code documentation

clarified language in `README.md`

updated details in `pyproject.toml`

request_coalescing_py/database.py

@@ -8,10 +8,27 @@ from request_coalescing_py.models import Item
 
 
 class DatabaseRepo:
+    """The database repository.
+
+    This repository is responsible for database operations.
+
+    Attributes:
+        app (FastAPI): The application instance (for access to the metrics object in state).
+        _db (databases.Database): The database instance used for requests.
+
+    """
+
     def __init__(self, app: FastAPI) -> None:
+        """Initialise the database repository.
+
+        Args:
+            app (FastAPI): The application instance.
+
+        """
         self.app = app
 
     async def start_db(self) -> None:
+        """Opens a database connection and prepare the environment."""
         self._db = Database("sqlite://./test.db")
         await self._db.connect()
         
@@ -22,9 +39,19 @@ class DatabaseRepo:
             pass
 
     async def stop_db(self) -> None:
+        """Gracefully closes the database connection."""
         await self._db.disconnect()
 
     async def get_by_id(self, item_id: int) -> Optional[Item]:
+        """Get an item by a specified id (from the database).
+
+        Args:
+            item_id (int): The requested item's id.
+
+        Returns:
+            Optional[Item]: The item details (if found) or None.
+
+        """
         self.app.state.metrics["db_calls"] += 1
 
         # Simulate expensive read (50ms)