How Modly Handles Logging and Session Archiving in Its FastAPI Backend

Modly uses Python's standard logging module with a custom _StatusFilter class to suppress noisy status-polling requests, while archiving all session artifacts to a dedicated workspace directory exposed via the /workspace HTTP endpoint.

The lightningpixel/modly repository implements a unified logging and persistence strategy within its FastAPI back-end to support AI generation workflows running inside an Electron application. By filtering high-frequency polling logs and writing all session outputs to a structured workspace directory, the system maintains clean console output while ensuring every generated artifact remains accessible across client restarts.

Logging Architecture and Noise Reduction

Modly’s logging strategy centers on Python’s built-in logging module, configured in api/main.py to handle both HTTP requests and isolated extension processes.

Suppressing Polling Logs with _StatusFilter

To prevent the console from flooding with status-check requests, Modly implements a custom logging.Filter subclass named _StatusFilter. Attached to the uvicorn.access logger, this filter inspects each record’s message content and discards entries containing the substring "/generate/status/".

# api/main.py – logging configuration

class _StatusFilter(logging.Filter):
    def filter(self, record):
        # Suppress logs generated by the status‑polling endpoint

        return "/generate/status/" not in record.getMessage()

logging.getLogger("uvicorn.access").addFilter(_StatusFilter())

Result: The console no longer displays a line for every polling request to the generation status endpoint, making debugging output significantly cleaner.

Capturing Extension Process Output

Beyond HTTP request logging, Modly captures stderr streams from each extension process (the isolated workers that execute AI models) and forwards them to the central logger. As implemented in api/runner.py, the ExtensionProcess class captures stderr separately to ensure that errors or debug prints from model adapters are recorded in the unified log stream.

Session Archiving and File Persistence

Modly automatically persists all intermediate and final artifacts—images, meshes, logs, and metadata—to the host filesystem using a session-scoped workspace structure managed by the generator registry.

Workspace Directory Structure

The api/services/generator_registry.py module defines the WORKSPACE_DIR constant, which serves as the root archive location. Each generation workflow creates a unique subdirectory under this path, named according to the current session ID. This architecture ensures that outputs survive Electron client restarts and remain organized by execution context.

HTTP Access to Archived Files

The FastAPI application exposes these archives through a dedicated route defined in api/main.py. The /workspace/{full_path:path} endpoint validates file existence within WORKSPACE_DIR and returns the content using FileResponse, enabling direct HTTP downloads without additional API layers.

# api/main.py – serving workspace files

@app.get("/workspace/{full_path:path}")
async def serve_workspace_file(full_path: str):
    import services.generator_registry as reg
    file_path = reg.WORKSPACE_DIR / full_path
    if not file_path.exists() or not file_path.is_file():
        raise HTTPException(status_code=404, detail="File not found")
    return FileResponse(str(file_path))

Example retrieval:

import requests

# Fetch an image from session-1234

url = "http://localhost:8000/workspace/session-1234/output.png"
resp = requests.get(url)

if resp.status_code == 200:
    with open("output.png", "wb") as f:
        f.write(resp.content)

Automatic Cleanup Mechanics

Session folders persist until explicitly removed. The model router in api/routers/model.py handles cleanup during model unload operations or explicit session termination, deleting the associated subdirectory from WORKSPACE_DIR to reclaim disk space while maintaining archives only during the active session lifecycle.

Summary

• Custom log filtering: The _StatusFilter class in api/main.py silently drops log entries containing /generate/status/ to eliminate polling noise from uvicorn.access logs.
• Unified error streams: Extension process stderr is captured and funneled into the main log pipeline, as implemented in api/runner.py.
• Filesystem-based archiving: All session outputs write to subdirectories under WORKSPACE_DIR defined in api/services/generator_registry.py.
• Direct HTTP retrieval: The /workspace/{full_path:path} endpoint in api/main.py enables direct file downloads without additional API layers.
• Lifecycle-aware cleanup: Session archives delete automatically during model unloading or manual termination via api/routers/model.py.

Frequently Asked Questions

How does Modly prevent log clutter from status polling?

Modly attaches a custom _StatusFilter class to the uvicorn.access logger in api/main.py. This filter inspects each log record and returns False for any message containing the substring /generate/status/, effectively silencing the frequent health-check requests while preserving other access logs.

Where does Modly store generated session files?

Modly writes all artifacts to a session-specific subdirectory under WORKSPACE_DIR, a constant defined in api/services/generator_registry.py. The subfolder name corresponds to the unique session ID assigned during workflow initialization, ensuring isolated storage for each generation run.

How can I access archived session files in Modly?

Clients retrieve files via the /workspace/{full_path:path} HTTP endpoint implemented in api/main.py. By constructing a URL with the session ID and filename (e.g., /workspace/session-123/output.png), users can download artifacts directly through standard HTTP GET requests using FileResponse.

Does Modly automatically clean up old session archives?

Yes. The cleanup logic resides in api/routers/model.py, which triggers when a model unloads or when the user explicitly terminates a session. This mechanism deletes the associated subdirectory from WORKSPACE_DIR, freeing storage space while maintaining the archive only during the active session lifecycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}