semantics update

backend/requirements.txt

@@ -41,3 +41,5 @@ tzlocal==5.3.1
 urllib3==2.6.2
 uvicorn==0.38.0
 websockets==15.0.1
+pandas
+psycopg2-binary

backend/src/api/routes/connections.py

@@ -6,7 +6,7 @@
 # @CONSTRAINT: Must use belief_scope for logging.
 
 # [SECTION: IMPORTS]
-from typing import List
+from typing import List, Optional
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
 from ...core.database import get_db
@@ -19,6 +19,7 @@ from ...core.logger import logger, belief_scope
 router = APIRouter()
 
 # [DEF:ConnectionSchema:Class]
+# @PURPOSE: Pydantic model for connection response.
 class ConnectionSchema(BaseModel):
     id: str
     name: str
@@ -31,8 +32,10 @@ class ConnectionSchema(BaseModel):
 
     class Config:
         orm_mode = True
+# [/DEF:ConnectionSchema:Class]
 
 # [DEF:ConnectionCreate:Class]
+# @PURPOSE: Pydantic model for creating a connection.
 class ConnectionCreate(BaseModel):
     name: str
     type: str
@@ -41,17 +44,28 @@ class ConnectionCreate(BaseModel):
     database: Optional[str] = None
     username: Optional[str] = None
     password: Optional[str] = None
-
-from typing import Optional
+# [/DEF:ConnectionCreate:Class]
 
 # [DEF:list_connections:Function]
+# @PURPOSE: Lists all saved connections.
+# @PRE:     Database session is active.
+# @POST:    Returns list of connection configs.
+# @PARAM:   db (Session) - Database session.
+# @RETURN:  List[ConnectionSchema] - List of connections.
 @router.get("", response_model=List[ConnectionSchema])
 async def list_connections(db: Session = Depends(get_db)):
     with belief_scope("ConnectionsRouter.list_connections"):
         connections = db.query(ConnectionConfig).all()
         return connections
+# [/DEF:list_connections:Function]
 
 # [DEF:create_connection:Function]
+# @PURPOSE: Creates a new connection configuration.
+# @PRE:     Connection name is unique.
+# @POST:    Connection is saved to DB.
+# @PARAM:   connection (ConnectionCreate) - Config data.
+# @PARAM:   db (Session) - Database session.
+# @RETURN:  ConnectionSchema - Created connection.
 @router.post("", response_model=ConnectionSchema, status_code=status.HTTP_201_CREATED)
 async def create_connection(connection: ConnectionCreate, db: Session = Depends(get_db)):
     with belief_scope("ConnectionsRouter.create_connection", f"name={connection.name}"):
@@ -61,8 +75,15 @@ async def create_connection(connection: ConnectionCreate, db: Session = Depends(
         db.refresh(db_connection)
         logger.info(f"[ConnectionsRouter.create_connection][Success] Created connection {db_connection.id}")
         return db_connection
+# [/DEF:create_connection:Function]
 
 # [DEF:delete_connection:Function]
+# @PURPOSE: Deletes a connection configuration.
+# @PRE:     Connection ID exists.
+# @POST:    Connection is removed from DB.
+# @PARAM:   connection_id (str) - ID to delete.
+# @PARAM:   db (Session) - Database session.
+# @RETURN:  None.
 @router.delete("/{connection_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_connection(connection_id: str, db: Session = Depends(get_db)):
     with belief_scope("ConnectionsRouter.delete_connection", f"id={connection_id}"):
@@ -74,5 +95,6 @@ async def delete_connection(connection_id: str, db: Session = Depends(get_db)):
         db.commit()
         logger.info(f"[ConnectionsRouter.delete_connection][Success] Deleted connection {connection_id}")
         return
+# [/DEF:delete_connection:Function]
 
 # [/DEF:ConnectionsRouter:Module]

backend/src/api/routes/plugins.py

@@ -11,7 +11,7 @@ from ...dependencies import get_plugin_loader
 
 router = APIRouter()
 
-@router.get("/", response_model=List[PluginConfig])
+@router.get("", response_model=List[PluginConfig])
 async def list_plugins(
     plugin_loader = Depends(get_plugin_loader)
 ):

backend/src/app.py

@@ -11,7 +11,7 @@ from pathlib import Path
 project_root = Path(__file__).resolve().parent.parent.parent
 sys.path.append(str(project_root))
 
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Depends, Request
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Depends, Request, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
@@ -138,6 +138,10 @@ if frontend_path.exists():
     # Serve other static files from the root of build directory
     @app.get("/{file_path:path}")
     async def serve_spa(file_path: str):
+        # Don't serve SPA for API routes that fell through
+        if file_path.startswith("api/"):
+            raise HTTPException(status_code=404, detail="API endpoint not found")
+            
         full_path = frontend_path / file_path
         if full_path.is_file():
             return FileResponse(str(full_path))

backend/src/plugins/debug.py

@@ -87,6 +87,11 @@ class DebugPlugin(PluginBase):
     # [/DEF:DebugPlugin.execute:Function]
 
     # [DEF:DebugPlugin._test_db_api:Function]
+    # @PURPOSE: Tests database API connectivity for source and target environments.
+    # @PRE:     source_env and target_env params exist.
+    # @POST:    Returns DB counts for both envs.
+    # @PARAM:   params (Dict) - Plugin parameters.
+    # @RETURN:  Dict - Comparison results.
     async def _test_db_api(self, params: Dict[str, Any]) -> Dict[str, Any]:
         source_env_name = params.get("source_env")
         target_env_name = params.get("target_env")
@@ -112,8 +117,14 @@ class DebugPlugin(PluginBase):
             }
             
         return results
+    # [/DEF:DebugPlugin._test_db_api:Function]
 
     # [DEF:DebugPlugin._get_dataset_structure:Function]
+    # @PURPOSE: Retrieves the structure of a dataset.
+    # @PRE:     env and dataset_id params exist.
+    # @POST:    Returns dataset JSON structure.
+    # @PARAM:   params (Dict) - Plugin parameters.
+    # @RETURN:  Dict - Dataset structure.
     async def _get_dataset_structure(self, params: Dict[str, Any]) -> Dict[str, Any]:
         env_name = params.get("env")
         dataset_id = params.get("dataset_id")
@@ -132,6 +143,7 @@ class DebugPlugin(PluginBase):
         
         dataset_response = client.get_dataset(dataset_id)
         return dataset_response.get('result') or {}
+    # [/DEF:DebugPlugin._get_dataset_structure:Function]
 
 # [/DEF:DebugPlugin:Class]
 # [/DEF:DebugPluginModule:Module]