odysseus/specs/architecture-runtime-inventory.md

Architecture Runtime Inventory

Last updated: dev@e57f60b | 2026-07-20

Purpose: current runtime/module inventory for codebase readability work originally discussed around #4071/#4082. This is a source snapshot, not a refactor plan. Recompute metrics against current dev before treating any count as authoritative.

This document maps the current runtime module structure, high-risk boundaries, and behavior-preserving refactor candidates. It does not move files, change imports, or alter runtime behavior.

Current Structure

odysseus/
├── app.py                    # FastAPI app entrypoint and route registry
├── conf/                     # Configuration helpers
├── core/                     # database, auth, middleware, session helpers
├── routes/                   # HTTP routes plus selected domain subpackages
│   ├── contacts/             # canonical contacts/CardDAV route package
│   ├── gallery/              # canonical gallery route/helper package
│   ├── history/              # canonical chat history route package
│   ├── memory/               # canonical memory route package
│   ├── note/                 # canonical notes/reminders route package
│   └── research/             # canonical research route package
├── src/                      # agent/model/runtime services and facades
│   ├── agent_tools/          # native tool handler classes
│   ├── model_capability_readers/ # provider model-metadata normalization
│   ├── search/               # compatibility aliases for services.search
│   └── tools/                # split do_* tool implementation domains
├── services/                 # service facades and canonical search/youtube paths
├── mcp_servers/              # built-in MCP server implementations
├── scripts/                  # local CLI tools and one-shot scripts
├── static/                   # no-build browser SPA
├── tests/                    # pytest, Node, and static source-shape tests
└── specs/                    # implementation-truth notes

Directory Flatness

Directory	Flat .py Files	Subdirectories	Current Concern
src/	100	agent_tools/, model_capability_readers/, search/, tools/	Still broad, but tool handlers, capability readers, and do_* implementations now have packages.
routes/	54	contacts/, gallery/, history/, memory/, note/, research/	Route grouping has started; most domains remain flat top-level route files.
core/	11	none	Manageable count, but database.py remains oversized and highly imported.

Largest Runtime Modules

Python Backend

File	Lines	Notes
routes/email_routes.py	5,226	Largest HTTP domain; route, cache, compose, OAuth, and mutation behavior.
src/agent_loop.py	4,529	Agent orchestration, tool rounds, prompt/context assembly, recovery.
routes/cookbook_routes.py	4,386	Cookbook setup/download/serve/state flows.
src/llm_core.py	2,869	Provider payloads, streaming, fallbacks, provider quirks.
src/builtin_actions.py	2,776	Scheduler/background built-in action helpers.
routes/model_routes.py	2,657	Endpoint CRUD, probing, catalog cache, provider auth links.
src/task_scheduler.py	2,627	Task runner, runs, chained/event/webhook execution.
core/database.py	2,562	SQLAlchemy models plus manual SQLite migrations.
routes/gallery/gallery_routes.py	1,966	Canonical gallery/media route package.
routes/note/note_routes.py	937	Canonical notes/reminders route package.
routes/contacts/contacts_routes.py	916	Canonical contacts/CardDAV route package.
routes/research/research_routes.py	783	Canonical research route package.
routes/history/history_routes.py	794	Canonical chat history route package.
routes/memory/memory_routes.py	552	Canonical memory route package.
src/tool_implementations.py	115	Compatibility facade over src/tools/* and admin tool handlers.

Frontend

File	Lines	Notes
static/style.css	40,453	App-wide CSS remains the largest frontend risk.
static/js/document.js	11,038	Large document editor/library coordinator.
static/js/emailLibrary.js	7,784	Email library UI and cache behavior.
static/js/settings.js	5,795	Settings modal and provider/admin-adjacent wiring.
static/js/chat.js	5,457	Main chat streaming/UI coordinator.
static/app.js	4,389	SPA orchestration and compatibility bridges.

Import Dependency Snapshot

Relationship	Count	Notes
core.database importers	118	Highest-risk split target; routes, services, tests, and helpers depend on it.
src.tool_implementations importers	22	Still a live facade even after the tool split.
src.agent_loop importers	32	Agent loop is an orchestration hub.
src/ import lines referencing routes	36	Mostly function-local compatibility/runtime coupling.
routes/ import lines referencing src	391	Expected route-to-service direction.
routes/ import lines referencing core	139	Expected DB/auth/session dependencies.

Recompute examples:

find src -maxdepth 1 -name '*.py' | wc -l
find routes -maxdepth 1 -name '*.py' | wc -l
find tests -name 'test_*.py' | wc -l
wc -l app.py core/database.py src/agent_loop.py src/tool_implementations.py
rg -l '(^| )from core.database|(^| )import core.database' --glob '*.py' | wc -l
rg -n '(^| )from routes|(^| )import routes' src --glob '*.py' | wc -l

Route Ownership Map

Route modules are still mostly flat, with six landed domain packages:

• routes/gallery/gallery_routes.py and routes/gallery/gallery_helpers.py are canonical. routes/gallery_routes.py and routes/gallery_helpers.py are compatibility shims that replace their sys.modules entries with the canonical module object.
• routes/memory/memory_routes.py is canonical. routes/memory_routes.py is a compatibility shim.
• routes/research/research_routes.py is canonical. routes/research_routes.py is a compatibility shim.
• routes/history/history_routes.py is canonical. routes/history_routes.py is a compatibility shim.
• routes/contacts/contacts_routes.py is canonical. routes/contacts_routes.py is a compatibility shim.
• routes/note/note_routes.py is canonical. routes/note_routes.py is a compatibility shim.

Other major domains remain top-level route modules:

Domain	Primary Route Files	Current Risk
Email	email_routes.py, email_helpers.py, email_pollers.py	High: largest route surface and many side tables/caches.
Chat / Agent	chat_routes.py, chat_helpers.py, shell_routes.py, codex_routes.py, skills_routes.py	High: cross-cuts sessions, tools, research, compare, uploads.
Cookbook	cookbook_routes.py, cookbook_helpers.py, cookbook_output.py	Medium-high: code execution, SSH, model serving, state.
Model / LLM	model_routes.py, assistant_routes.py, copilot_routes.py, chatgpt_subscription_routes.py	Medium-high: secrets, endpoint ownership, provider auth.
Calendar / Contacts	calendar_routes.py, contacts/contacts_routes.py plus shim	Medium: remote sync/writeback and credential handling.
Documents	document_routes.py, document_helpers.py, personal_routes.py, upload_routes.py	Medium: files, ownership, optional renderers, RAG.
Auth / Admin	auth_routes.py, api_token_routes.py, backup_routes.py, diagnostics_routes.py, admin_wipe_routes.py	Medium: security-critical but more modular.

Tool Registry And Implementation Boundaries

Tool execution is no longer concentrated in one 4k-line module.

Component	Owner	Role
Native handler registry	src/agent_tools/__init__.py	Maps native tool names to handler classes for bash/python/web/files/documents/interaction/model/session/background/admin tools.
Low-level native handlers	src/agent_tools/*.py	Filesystem, subprocess, web, document, interaction, model interaction, background job, session, and admin handler classes.
Domain do_* implementations	src/tools/*.py	Calendar, contacts, Cookbook, image, notes, research, search, system, and vault do_* functions.
Compatibility facade	src/tool_implementations.py	Re-exports old do_* names and lazy-loads admin do_* symbols so legacy imports and tests keep working.
Tool schemas	src/tool_schemas.py	Native OpenAI-style schemas and native-call conversion.
Tool retrieval	src/tool_index.py	Built-in and MCP tool retrieval text/indexing.
Tool parsing	src/tool_parsing.py	Prompted/fenced tool-call parsing and aliases.
Tool execution gates	src/tool_execution.py	Dispatch, path confinement, admin/non-admin gates, MCP dispatch, truncation, and UI formatting.

Current src/tools/* do_* domain counts:

Domain File	Count
calendar.py	1
contacts.py	2
cookbook.py	13
image.py	1
notes.py	1
research.py	2
search.py	1
system.py	4
vault.py	3

Admin manage tools for endpoints, MCP, webhooks, tokens, and settings live in src/agent_tools/admin_tools.py and are registered through ADMIN_TOOL_HANDLERS.

Risk Ranking For Future Refactors

Priority	Target	Risk	Notes
1	Remaining route domains into packages	Medium	Do one domain per PR with sys.modules compatibility shims and route-import tests.
2	src/agent_loop.py submodules	Medium-high	Extract prompt/context assembly, classification, verification/recovery, and stream-round helpers without changing behavior.
3	Email route/service split	High	Valuable but risky because account ownership, IMAP cache, side DBs, OAuth, and compose/send are intertwined.
4	Cookbook route/service split	Medium-high	Preserve command validation, shell/SSH boundaries, and state semantics.
5	core/database.py model/migration split	High	Most imported module; should be late and shim-heavy.
6	Frontend CSS/large coordinator splits	Medium	Requires browser/module-order verification, not just source movement.

Already-landed structure that should not be treated as future work:

• src/tool_implementations.py has already been split behind a facade.
• Gallery, research, memory, history, contacts, and note route packages already have canonical subpackage locations plus top-level compatibility shims.

Safety Guardrails For Follow-Up Work

• One domain/slice per PR.
• No behavior changes mixed with file moves.
• Keep compatibility shims for existing import paths until all call sites and tests are intentionally migrated.
• Add import-parity tests for every moved module.
• Validate with focused tests for the moved domain plus compile checks.
• Do not start with core/database.py unless the change is a small migration or helper extraction with dedicated tests.
• Avoid packaging/runtime/tooling migration inside route or module moves.

Validation Commands

python -m compileall app.py core routes src conf services
python -m pytest tests/ -x -q
python -c "from src.tool_implementations import do_search_chats; print('tool facade OK')"
python -c "import routes.gallery_routes as g; import routes.gallery.gallery_routes as c; print(g is c)"
python -c "import routes.memory_routes as m; import routes.memory.memory_routes as c; print(m is c)"
python -c "import routes.research_routes as r; import routes.research.research_routes as c; print(r is c)"
python -c "import routes.history_routes as h; import routes.history.history_routes as c; print(h is c)"
python -c "import routes.contacts_routes as c0; import routes.contacts.contacts_routes as c1; print(c0 is c1)"
python -c "import routes.note_routes as n; import routes.note.note_routes as c; print(n is c)"