semantic markup update

backend/src/app.py

@@ -19,7 +19,7 @@ import asyncio
 import os
 
 from .dependencies import get_task_manager, get_scheduler_service
-from .core.logger import logger
+from .core.logger import logger, belief_scope
 from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections
 from .core.database import init_db
 
@@ -33,17 +33,29 @@ app = FastAPI(
 )
 # [/DEF:App:Global]
 
+# [DEF:startup_event:Function]
+# @PURPOSE: Handles application startup tasks, such as starting the scheduler.
+# @PRE: None.
+# @POST: Scheduler is started.
 # Startup event
 @app.on_event("startup")
 async def startup_event():
-    scheduler = get_scheduler_service()
+    with belief_scope("startup_event"):
+        scheduler = get_scheduler_service()
     scheduler.start()
+# [/DEF:startup_event:Function]
 
+# [DEF:shutdown_event:Function]
+# @PURPOSE: Handles application shutdown tasks, such as stopping the scheduler.
+# @PRE: None.
+# @POST: Scheduler is stopped.
 # Shutdown event
 @app.on_event("shutdown")
 async def shutdown_event():
-    scheduler = get_scheduler_service()
+    with belief_scope("shutdown_event"):
+        scheduler = get_scheduler_service()
     scheduler.stop()
+# [/DEF:shutdown_event:Function]
 
 # Configure CORS
 app.add_middleware(
@@ -55,12 +67,20 @@ app.add_middleware(
 )
 
 
+# [DEF:log_requests:Function]
+# @PURPOSE: Middleware to log incoming HTTP requests and their response status.
+# @PRE: request is a FastAPI Request object.
+# @POST: Logs request and response details.
+# @PARAM: request (Request) - The incoming request object.
+# @PARAM: call_next (Callable) - The next middleware or route handler.
 @app.middleware("http")
 async def log_requests(request: Request, call_next):
-    logger.info(f"[DEBUG] Incoming request: {request.method} {request.url.path}")
-    response = await call_next(request)
-    logger.info(f"[DEBUG] Response status: {response.status_code} for {request.url.path}")
-    return response
+    with belief_scope("log_requests", f"{request.method} {request.url.path}"):
+        logger.info(f"[DEBUG] Incoming request: {request.method} {request.url.path}")
+        response = await call_next(request)
+        logger.info(f"[DEBUG] Response status: {response.status_code} for {request.url.path}")
+        return response
+# [/DEF:log_requests:Function]
 
 # Include API routes
 app.include_router(plugins.router, prefix="/api/plugins", tags=["Plugins"])
@@ -71,12 +91,14 @@ app.include_router(environments.router, prefix="/api/environments", tags=["Envir
 app.include_router(mappings.router)
 app.include_router(migration.router)
 
-# [DEF:WebSocketEndpoint:Endpoint]
-# @SEMANTICS: websocket, logs, streaming, real-time
-# @PURPOSE: Provides a WebSocket endpoint for clients to connect to and receive real-time log entries for a specific task.
+# [DEF:websocket_endpoint:Function]
+# @PURPOSE: Provides a WebSocket endpoint for real-time log streaming of a task.
+# @PRE: task_id must be a valid task ID.
+# @POST: WebSocket connection is managed and logs are streamed until disconnect.
 @app.websocket("/ws/logs/{task_id}")
 async def websocket_endpoint(websocket: WebSocket, task_id: str):
-    await websocket.accept()
+    with belief_scope("websocket_endpoint", f"task_id={task_id}"):
+        await websocket.accept()
     logger.info(f"WebSocket connection accepted for task {task_id}")
     task_manager = get_task_manager()
     queue = await task_manager.subscribe_logs(task_id)
@@ -126,7 +148,7 @@ async def websocket_endpoint(websocket: WebSocket, task_id: str):
         logger.error(f"WebSocket error for task {task_id}: {e}")
     finally:
         task_manager.unsubscribe_logs(task_id, queue)
-# [/DEF:WebSocketEndpoint:Endpoint]
+# [/DEF:websocket_endpoint:Function]
 
 # [DEF:StaticFiles:Mount]
 # @SEMANTICS: static, frontend, spa
@@ -136,24 +158,32 @@ if frontend_path.exists():
     app.mount("/_app", StaticFiles(directory=str(frontend_path / "_app")), name="static")
     
     # Serve other static files from the root of build directory
+    # [DEF:serve_spa:Function]
+    # @PURPOSE: Serves frontend static files or index.html for SPA routing.
+    # @PRE: file_path is requested by the client.
+    # @POST: Returns the requested file or index.html as a fallback.
     @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))
-        # Fallback to index.html for SPA routing
-        return FileResponse(str(frontend_path / "index.html"))
+        with belief_scope("serve_spa", f"path={file_path}"):
+            # 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))
+            # Fallback to index.html for SPA routing
+            return FileResponse(str(frontend_path / "index.html"))
+    # [/DEF:serve_spa:Function]
 else:
-    # [DEF:RootEndpoint:Endpoint]
-    # @SEMANTICS: root, healthcheck
-    # @PURPOSE: A simple root endpoint to confirm that the API is running.
+    # [DEF:read_root:Function]
+    # @PURPOSE: A simple root endpoint to confirm that the API is running when frontend is missing.
+    # @PRE: None.
+    # @POST: Returns a JSON message indicating API status.
     @app.get("/")
     async def read_root():
-        return {"message": "Superset Tools API is running (Frontend build not found)"}
-# [/DEF:RootEndpoint:Endpoint]
+        with belief_scope("read_root"):
+            return {"message": "Superset Tools API is running (Frontend build not found)"}
+    # [/DEF:read_root:Function]
 # [/DEF:StaticFiles:Mount]
 # [/DEF:AppModule:Module]