category: reference

tags: [design, performance, lambda, architecture, cold-start]

last_updated: 2026-03-14

**Relates to:** [[Dev/E-1_Cold_Start_Benchmarks]], [[Design/CDN_Read_Path]], [[Design/Platform_Overview]]

Importing `otterwiki.server` takes ~3.5s on Lambda because `server.py` is a monolithic script that executes the entire application lifecycle at import time: Flask app creation, SQLAlchemy binding, git repo opening, plugin discovery, renderer initialization, DB DDL, config queries, and route registration with all transitive dependencies. See [[Dev/E-1_Cold_Start_Benchmarks]] for the full breakdown.

The CDN Read Path ([[Design/CDN_Read_Path]]) solves the read-side cold start by bypassing the heavy Lambda entirely. This design addresses the **write-path cold start** (MCP, API) by restructuring how we load Otterwiki — treating it as a library of components rather than a monolithic application.

Every module in Otterwiki imports from `otterwiki.server`:

If we provide our own module that exports the same names but initializes lazily, all of Otterwiki's business logic works unchanged — it just resolves `otterwiki.server` to our module.

Python's `sys.modules` dict controls what `import` returns. If we inject our own module before any Otterwiki code is imported, every `from otterwiki.server import X` resolves to our lazy version.

`lambda_server.py` exports the same names as `otterwiki.server` but uses Werkzeug's `LocalProxy` for expensive singletons:

from flask import Flask

from flask_sqlalchemy import SQLAlchemy

from werkzeug.local import LocalProxy

app = Flask('otterwiki',

template_folder='<otterwiki package>/templates',

static_folder='<otterwiki package>/static')

# ... same defaults as server.py lines 21-77 ...

app.config.from_envvar("OTTERWIKI_SETTINGS", silent=True)

db = SQLAlchemy(app)

if not hasattr(app, f'_lazy_{name}'):

_do_deferred_init()

return getattr(app, f'_lazy_{name}')

import otterwiki.gitstorage

from otterwiki.renderer import OtterwikiRenderer

from otterwiki.plugins import plugin_manager

from flask_mail import Mail

app._lazy_storage = otterwiki.gitstorage.GitStorage(app.config["REPOSITORY"])

app._lazy_app_renderer = OtterwikiRenderer(config=app.config)

app._lazy_mail = Mail(app)

# DB init

with app.app_context():

db.create_all()

from otterwiki.models import Preferences

for item in Preferences.query:

# same config-update logic as server.py lines 177-205

app.config[item.name] = item.value

# Plugin setup

plugin_manager.hook.setup(

app=app, storage=app._lazy_storage, db=db

)

# Git HTTP server (for completeness; may not be needed in Lambda)

import otterwiki.remote

app._lazy_githttpserver = otterwiki.remote.GitHttpServer(

path=app.config["REPOSITORY"]

)

storage = LocalProxy(lambda: _get_or_init('storage'))

app_renderer = LocalProxy(lambda: _get_or_init('app_renderer'))

mail = LocalProxy(lambda: _get_or_init('mail'))

githttpserver = LocalProxy(lambda: _get_or_init('githttpserver'))

from otterwiki.models import Preferences, Drafts, User, Cache

sys.modules['otterwiki.server'] = sys.modules[__name__]

Names that `otterwiki.server` exports and other modules depend on:

| Name | Type | Lazy? | Imported by |

|------|------|-------|-------------|

| `app` | Flask | No — must exist for decorators | everything |

| `db` | SQLAlchemy | No — must exist for Model class definitions | models, auth, helper, wiki, preferences |

| `storage` | GitStorage | **Yes** — nothing touches it until a request | helper, wiki, gitstorage, remote |

| `app_renderer` | OtterwikiRenderer | **Yes** — only used during markdown rendering | helper |

| `mail` | Flask-Mail | **Yes** — only used when sending email | helper |

| `githttpserver` | GitHttpServer | **Yes** — only used for git HTTP routes | views |

| `Preferences` | SQLAlchemy Model | Via re-export from models (needs `db`, not `storage`) | helper |

| `Drafts` | SQLAlchemy Model | Via re-export | wiki |

| `update_app_config` | function | Called internally, deferred | (internal) |

`app` and `db` must be real objects at import time because other modules use them to define models (`class Preferences(db.Model)`) and register routes (`@app.route`). Everything else can be a `LocalProxy`.

These changes benefit all Otterwiki deployments and make library mode cleaner. Listed in order of impact and likelihood of acceptance:

**Current:** `views.py` imports the entire dependency tree at module level:

from otterwiki.wiki import Page, Changelog, Search, AutoRoute # triggers PIL, feedgen, unidiff, bs4

from otterwiki.sitemap import sitemap as generate_sitemap

import otterwiki.auth # triggers flask_login, werkzeug.security

**Proposed:** Move imports into route handler function bodies:

from otterwiki.wiki import AutoRoute

p = AutoRoute(path, values=request.values)

return p.view()

Python caches imports, so only the first call to each handler pays the cost. This is a mechanical change — no logic changes, ~30 function edits. It keeps `import otterwiki.views` cheap (just decorator registration) and defers the heavy imports to first request.

**Estimated savings:** ~500ms off import time.

**Current:** Top-level imports only used by specific methods:

import PIL.Image # only used in get_attachment_thumbnail()

from feedgen.feed import FeedGenerator # only used in feed_rss(), feed_atom()

**Proposed:** Move to function bodies.

**Estimated savings:** ~200ms off import time.

**Current:** `plugins.py:269` calls `load_setuptools_entrypoints("otterwiki")` at module level, scanning all installed packages every time `otterwiki.plugins` is imported.

**Proposed:** Add an `init_plugins()` function that performs the scan explicitly:

plugin_manager = pluggy.PluginManager("otterwiki")

plugin_manager.load_setuptools_entrypoints("otterwiki")

Callers (server.py, our lambda_server.py) call `init_plugins()` when ready. On a 180MB Lambda package with numpy, faiss, sqlalchemy, etc., the entrypoint scan is not cheap.

**Estimated savings:** ~200ms, moved from import time to controlled init.

**Current:** `renderer.py:632` creates `render = OtterwikiRenderer()` — a second instance of the full mistune parser chain, used only by the about page and as an unconfigured test renderer.

**Proposed:** Delete it. The about page can use `app_renderer` (or lazy-create). Tests can create their own instance.

**Estimated savings:** ~200ms off import time.

Standard Flask best practice. Would replace the module-level globals with a `create_app()` function that returns a configured Flask app. This would make our `sys.modules` injection unnecessary — we'd just call `create_app(config)` with our own config.

This is a larger conversation and a bigger change. The other four PRs are sufficient for library mode.

| Change | Init savings | Where cost moves | Complexity |

|--------|-------------|-----------------|------------|

| `storage` → LocalProxy | ~200ms | First request | Low — 10 lines in lambda_server |

| `app_renderer` → LocalProxy | ~300ms | First request | Low — same pattern |

| Defer `db.create_all()` + config | ~300ms | First request | Low — before_request hook |

| Lazy imports in views.py (upstream) | ~500ms | First request handler | Medium — ~30 function edits |

| Lazy plugin loading | ~500ms | First request | Low — move 2 imports + init function |

| Lazy PIL/feedgen/unidiff (upstream) | ~200ms | First use of those routes | Low — move 3 imports |

| Remove duplicate renderer (upstream) | ~200ms | N/A (eliminated) | Low — delete 1 line |

| Defer multi-tenant middleware | ~350ms | First request | Low — already in our code |

The coupling surface is the set of names exported by `server.py` and the internal APIs of `GitStorage`, `OtterwikiRenderer`, and the SQLAlchemy models. Mitigation:

1. **CI job** that runs Otterwiki's existing test suite against our replacement server module. Any export surface change (new name added to server.py, model schema change) fails the tests.

2. **Pin to upstream tags** in the fork, not HEAD. Review upstream changes at each version bump.

3. **The export surface is stable.** `app`, `db`, `storage` have been the core exports since Otterwiki's early versions. Template filters and Jinja globals change occasionally but are easy to sync.

The riskiest coupling is to `server.py`'s config defaults (lines 21-77) — if a new config key is added upstream, we need to add it to lambda_server.py. The CI job catches this because Otterwiki's tests exercise config-dependent behavior.

These two designs are complementary:

- **CDN Read Path** ([[Design/CDN_Read_Path]]) eliminates the heavy Lambda from the browser read path entirely. Reads are served by a thin assembly Lambda (<100ms cold start) or CloudFront cache.

- **Library Mode** (this document) reduces the heavy Lambda's cold start for the write path (MCP, API). From ~4.5s to ~2.6s (with upstream PRs) or ~3.0s (without).

Together, they make the platform feel responsive:

- Browser reads: ~10-50ms (cache hit) or ~100-300ms (cache miss)

- MCP/API writes (warm): single-digit ms

- MCP/API writes (cold): ~2.6s first response, then warm for the session

1. **Does `sys.modules` injection interact with pluggy's entrypoint scanner?** Pluggy uses `importlib.metadata` to find plugins, not `import`. Should be fine, but needs verification.

2. **Does Flask-SQLAlchemy's `SQLAlchemy(app)` eagerly connect to the database?** If so, the DB file must exist at import time. May need `db.init_app(app)` pattern instead (deferred binding).

3. **Can `db.create_all()` be safely called in `before_request`?** Flask-SQLAlchemy's `create_all` needs an app context. The `before_request` hook runs inside one, so this should work.

4. **What happens if a `LocalProxy`-wrapped `storage` is accessed during module-level code in another otterwiki module?** Grep for module-level usage of `storage` outside of `server.py` to verify none exists. (Preliminary review: `gitstorage.py` defines `storage = None` at module level but doesn't import from server; `helper.py` imports it but only uses it in functions.)

5. **Template filter registration timing.** Jinja2 template filters must be registered before the first template render. Registering them at import time in lambda_server.py (as server.py does) should be safe.