chore: Add scaffolded database layer (not yet implemented)

- database.py: PostgreSQL connection setup (TODO)
- models.py: SQLModel schema for Invoice/LineItem (TODO)
- repository.py: CRUD operations placeholder (TODO)

Scaffolded for future human-in-the-loop persistence feature.

src/database.py

@@ -0,0 +1,33 @@
+# src/database.py
+
+from sqlmodel import SQLModel, create_engine, Session
+from typing import Generator
+import os
+
+# --- INSTRUCTIONS ---
+# 1. Get credentials from environment variables (Os.getenv)
+# 2. Construct the DATABASE_URL string: postgresql://user:pass@host:port/db
+# 3. Create the SQLModel engine
+# 4. Implement the init_db and get_session functions
+
+# TODO: Define constants for DB params (POSTGRES_USER, etc.)
+
+# TODO: Define DATABASE_URL
+
+# TODO: Create 'engine' using create_engine(DATABASE_URL)
+
+def init_db():
+    """
+    Idempotent DB initialization.
+    Should create all tables defined in SQLModel metadata.
+    """
+    # TODO: Call SQLModel.metadata.create_all(engine)
+    pass
+
+def get_session() -> Generator[Session, None, None]:
+    """
+    Dependency for yielding a database session.
+    Useful for FastAPI dependencies or context usage.
+    """
+    # TODO: Open a session with the engine, yield it, and ensure it closes
+    pass

src/models.py

@@ -0,0 +1,50 @@
+# src/models.py
+
+from typing import List, Optional
+from datetime import date as DateType
+from decimal import Decimal
+from sqlmodel import SQLModel, Field, Relationship
+
+# --- INSTRUCTIONS ---
+# SQLModel classes should mirror the Pydantic models in src/schema.py
+# but with database-specific configurations (primary keys, foreign keys).
+
+class Invoice(SQLModel, table=True):
+    __tablename__ = "invoices"
+
+    # TODO: Define Primary Key 'id' (int, optional, default=None)
+    
+    # TODO: Add Data Fields
+    # - receipt_number (str, indexed)
+    # - date (DateType)
+    # - total_amount (Decimal, max_digits=10, decimal_places=2)
+    # - vendor (str)
+    # - address (str)
+    # - semantic_hash (str, unique, indexed) -> Critical for deduplication
+    
+    # TODO: Add Metadata Fields
+    # - validation_status (str)
+    # - validation_errors (str) -> Store as JSON string since we don't need to query inside it yet
+    # - created_at (DateType) -> Default to today
+    
+    # TODO: Define relationship to LineItem (One-to-Many)
+    # items: List["LineItem"] = Relationship(...)
+    pass
+
+
+class LineItem(SQLModel, table=True):
+    __tablename__ = "line_items"
+
+    # TODO: Define Primary Key
+    
+    # TODO: Define Foreign Key 'invoice_id' linking to 'invoices.id'
+    
+    # TODO: Add Data Fields
+    # - description (str)
+    # - quantity (int)
+    # - unit_price (Decimal)
+    # - total (Decimal)
+
+    # TODO: Define relationship back to Invoice
+    # invoice: Optional[Invoice] = Relationship(...)
+    pass

src/repository.py

@@ -0,0 +1,41 @@
+# src/repository.py
+
+from sqlmodel import Session, select
+from typing import Dict, Any, Optional
+import json
+
+from src.models import Invoice, LineItem
+from src.database import get_session, engine
+
+class InvoiceRepository:
+    def __init__(self, session: Session = None):
+        """
+        Initialize with an optional session. 
+        Allows dependency injection for testing or API usage.
+        """
+        self.session = session
+
+    def save_invoice(self, invoice_data: Dict[str, Any]) -> Invoice:
+        """
+        Saves an invoice and its line items to the database.
+        
+        Steps to implement:
+        1. Manage Session: If self.session is None, create a new one using 'engine'.
+        2. Clean Data: Separate 'items' list from the main invoice properties.
+        3. Create Invoice: Instantiate the Invoice SQLModel.
+        4. Deserialize Complex Types: e.g. 'validation_errors' list -> JSON string.
+        5. Process Items: Iterate 'items', create LineItem models, check keys match, and append to invoice.items.
+        6. Commit: Add to session, commit, and refresh.
+        7. Error Handling: Wrap in try/except to rollback on failure.
+        """
+        # TODO: Implementation
+        raise NotImplementedError("Implement the save logic.")
+
+    def get_by_hash(self, semantic_hash: str) -> Optional[Invoice]:
+        """
+        Check if invoice already exists using the semantic hash.
+        """
+        # TODO: Create session if needed
+        # TODO: Execute SELECT statement filtering by hash
+        # TODO: Return first result or None
+        raise NotImplementedError("Implement the query logic.")