# Pathrule Pattern: Flask Production Applications (1.0.0) # ::pathrule:package:flask ### [RULE] Construct Flask through an application factory (path: /app) A module-global application freezes configuration at import time and turns imports into initialization order. A factory makes the instance boundary explicit and lets each process or test create the application it actually needs. - Create the Flask object inside `create_app`, load configuration before binding extensions, then register blueprints and error handlers in a stable order. - Instantiate extension objects without an app at module scope and bind them with `init_app`; this keeps models importable without constructing the server. - Pass environment-specific configuration into the factory instead of mutating global config after modules have already read it. - Keep CLI commands and background-worker bootstraps dependent on the factory so they use the same extension setup without importing a running web process. See /tests for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Do not let request context leak into service code (path: /app/services) Flask's context-local proxies look like globals but only resolve while the relevant context is active. A service that reads them directly becomes unusable in a job, CLI command, test, or deferred callback. - Resolve the authenticated actor, locale, and request data in the route or decorator, then pass typed values to the service function. - Do not capture `request`, `session`, or `g` in a closure that outlives the response. Copy only the specific immutable value the later task needs. - Open database sessions and transactions around service work with explicit cleanup; do not rely on a request teardown hook for code that also runs outside HTTP. - Use an explicit application context only for framework integration during CLI or worker boot, not as a blanket fix for hidden request dependencies. See /app for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] Blueprints partition transport ownership, not domain ownership (path: /app) A blueprint is a registration unit for Flask surfaces. Treating it as a complete business module often causes models and services to import the blueprint object, creating circular dependencies and preventing the same behavior from being called elsewhere. - Keep route functions, request schemas, response formatting, and blueprint-local error mapping inside the blueprint package. - Move business transitions and repository calls to services that do not import Flask request or response objects. - Register shared error translation at the application level and blueprint-specific errors only where their representation genuinely differs. - Use URL prefixes and blueprint names as public routing decisions; changing them should not move or rename the domain code they adapt. See /app/services for the rule or workflow that puts this decision into practice. --- ### [MEMORY] The development server is a local feedback tool (path: /app) Flask's built-in server optimizes for reload and debugging, not process supervision, worker management, slow-client defense, or graceful restarts. Production topology belongs outside the application while remaining documented beside it. - Serve the factory through a production WSGI server and size workers from measured CPU, memory, blocking I/O, and database-pool capacity rather than a copied formula. - Disable the interactive debugger and never expose a debug PIN path to a network, even behind authentication. - If a reverse proxy supplies forwarding headers, apply proxy middleware with the exact trusted hop counts instead of accepting arbitrary public headers. - Keep health checks cheap and independent from a full dependency transaction; readiness can test critical connectivity without turning every probe into load. See /app for the rule or workflow that puts this decision into practice.