# How Modly Handles Logging and Session Archiving in Its FastAPI Backend

> Discover how Modly's FastAPI backend manages logging and session archiving. Learn about its custom logging filter and workspace directory for artifact storage. Explore the lightningpixel/modly repository.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: internals
- Published: 2026-08-15

---

**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`](https://github.com/lightningpixel/modly/blob/main/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/"`.

```python

# 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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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.

```python

# 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:**

```python
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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/api/runner.py).
- **Filesystem-based archiving**: All session outputs write to subdirectories under `WORKSPACE_DIR` defined in [`api/services/generator_registry.py`](https://github.com/lightningpixel/modly/blob/main/api/services/generator_registry.py).
- **Direct HTTP retrieval**: The `/workspace/{full_path:path}` endpoint in [`api/main.py`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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.