Architecture
============

Current module layout:

- ``pipeworks_name_generation/webapp/server.py``
  Thin public entrypoint that wires CLI/runtime helpers and exposes the
  existing callable surface used by tests and scripts.
- ``pipeworks_name_generation/webapp/handler.py``
  ``BaseHTTPRequestHandler`` implementation focused on transport and dispatch.
- ``pipeworks_name_generation/webapp/endpoint_adapters.py``
  Route adapter functions that bridge dispatch to domain route modules.
- ``pipeworks_name_generation/webapp/route_registry.py``
  Central route-to-handler method mapping for GET/POST dispatch.
- ``pipeworks_name_generation/webapp/routes/*``
  Route-level behavior grouped by domain (static, import, generation, database).
- ``pipeworks_name_generation/webapp/db/*``
  Concrete SQLite connection, schema, metadata repository, table-store, and
  importer helpers.
- ``pipeworks_name_generation/webapp/generation.py``
  Generation-domain mapping, selection stats, and deterministic sampling.
  Includes a lightweight in-process cache for generation package options,
  keyed by database path and invalidated on successful imports.
- ``pipeworks_name_generation/webapp/http/*``
  Request parsing and response transport utilities.
- ``pipeworks_name_generation/webapp/runtime.py``
  Port resolution and server process lifecycle helpers.
- ``pipeworks_name_generation/webapp/cli.py``
  Argument parsing and config->settings composition.
- ``pipeworks_name_generation/webapp/frontend/*``
  Template and static UI assets loaded at runtime.

Design constraints:

- Keep generation deterministic by using request-local ``random.Random(seed)``.
- Keep route handlers thin and side-effect boundaries explicit.
- Keep SQLite access in dedicated helpers to make query behavior testable.
- Initialize SQLite schema once at server startup; request handlers operate
  against an already-prepared database.
- Handler fallback initialization still exists for direct test harness usage and
  runs once per bound handler class.