App

app

Defines the FastAPI Mirumoji Server API

Exposes custom exception handlers, a create_app factory that builds and wires the application, and a run function to start the application

Module Import

• Importing this module has no side effects beyond constructing the FastAPI app object so that it can serve as an entry-point for uvicorn and Docker

• logging configuration, storage/database initialisation, and startup logging all happen inside the lifespan handler

create_app()

Builds and wires the Mirumoji FastAPI application without performing I/O operations

Operations Performed

• App Construction

• Static File Mounting

• CORS Configuration

• Domain / HTTP Exception Handler Registration

• Router Registration

Returns:

Name	Type	Description
FastAPI	FastAPI	The fully-configured application

http_exception_handler(request, exc) async

Custom exception handler for all HTTP errors

Emits the same nested envelope as the domain handler so the frontend has a single error shape to parse. The machine-readable code is derived from the HTTP status phrase (e.g. 404 -> "NotFound")

Parameters:

Name	Type	Description	Default
request	Request	Incoming request object	required
exc	HTTPException	Raised exception object	required

Returns:

Name	Type	Description
JSONResponse	JSONResponse	The exception response to return

lifespan(app) async

Manages the API's lifecycle

Startup Operations

• Logging Configuration

• Database + Media Storage Initialisation

• Lifespan-Scoped Processor Initialisation

• Lifespan-Scoped JobQueueManager Initialisation

Shutdown Operations

• Stops the Async Job Queue Task, marking any running jobs as failed

• Disposes the Database Engine

• Clears Temporary Media

Parameters:

Name	Type	Description	Default
app	FastAPI	The API object	required

Yields:

Type	Description
AsyncGenerator[Any, None]	Control back to the running application

mirumoji_exception_handler(request, exc) async

Translate domain exceptions into the structured error envelope

Reads the HTTP contract (http_status, code) and optional details that each MirumojiServerError subclass carries, so domain code never constructs HTTP responses itself

Parameters:

Name	Type	Description	Default
request	Request	Incoming request object	required
exc	MirumojiServerError	Raised domain exception	required

Returns:

Name	Type	Description
JSONResponse	JSONResponse	The structured error response to return