Fix SSE route dependency and align architecture docs

backend/app/domain/documents/ports.py

@@ -0,0 +1,96 @@
+"""Define domain ports for documents."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .models import Chunk, Document, DocumentStatus, ParsedDocument
+# Keep domain contracts explicit so adapters can swap implementations cleanly.
+
+
+
+class DocumentRepository(ABC):
+    """Provide the Document Repository repository implementation."""
+    @abstractmethod
+    def create(self, document: Document) -> Document:
+        """Handle create for the Document Repository instance."""
+        pass
+
+    @abstractmethod
+    def update(self, document: Document) -> Document:
+        """Handle update for the Document Repository instance."""
+        pass
+
+    @abstractmethod
+    def get(self, doc_id: str) -> Document | None:
+        """Handle get for the Document Repository instance."""
+        pass
+
+    @abstractmethod
+    def list(self, limit: int | None = None) -> list[Document]:
+        """Handle list for the Document Repository instance."""
+        pass
+
+    @abstractmethod
+    def update_status(
+        self,
+        doc_id: str,
+        status: DocumentStatus,
+        *,
+        error_message: str = "",
+        chunk_count: int | None = None,
+        summary: str | None = None,
+        summary_latency_ms: int | None = None,
+        parser_name: str | None = None,
+        index_name: str | None = None,
+        metadata: dict | None = None,
+    ) -> Document | None:
+        """Update status for the Document Repository instance."""
+        pass
+
+
+class DocumentBinaryStore(ABC):
+    """Provide the Document Binary Store store implementation."""
+    @abstractmethod
+    def save(
+        self,
+        *,
+        object_name: str,
+        data: bytes,
+        content_type: str,
+        metadata: dict[str, str] | None = None,
+    ) -> None:
+        """Handle save for the Document Binary Store instance."""
+        pass
+
+    @abstractmethod
+    def read(self, object_name: str) -> bytes:
+        """Handle read for the Document Binary Store instance."""
+        pass
+
+    @abstractmethod
+    def delete(self, object_name: str) -> None:
+        """Handle delete for the Document Binary Store instance."""
+        pass
+
+
+class DocumentParser(ABC):
+    """Provide the Document Parser parser."""
+    @abstractmethod
+    def parse(self, *, file_path: str, doc_id: str, doc_name: str) -> ParsedDocument:
+        """Handle parse for the Document Parser instance."""
+        pass
+
+
+class ChunkBuilder(ABC):
+    """Provide the Chunk Builder builder."""
+    @abstractmethod
+    def build(
+        self,
+        *,
+        parsed_document: ParsedDocument,
+        regulation_type: str,
+        version: str,
+    ) -> list[Chunk]:
+        """Handle build for the Chunk Builder instance."""
+        pass