odysseus/specs/discovery/system-map.md

Current system map

This document describes the checked-in code at the same commit as this document. It is a subsystem map, not an exhaustive feature catalog or runtime certification. Each section records only current implementation, canonical locations, confirmed current problems, and unresolved factual questions.

Startup and application composition

Current implementation. app.py creates the application, mounts static assets, constructs shared services, registers route factories, and owns lifespan startup and shutdown. src/app_initializer.py prepares application state; core/ provides persistence, authentication, middleware, sessions, and platform helpers.

Canonical code locations. app.py; src/app_initializer.py; core/database.py; core/auth.py; core/middleware.py; routes/.

Confirmed problems. None recorded by this mapping.

Open questions. Which component currently owns startup and shutdown for each long-lived service?

Frontend shell and browser interaction

Current implementation. static/index.html is served by the root and SPA deep-link routes in app.py; static/app.js, static/style.css, and static/js/ implement the client surface.

Canonical code locations. static/index.html; static/app.js; static/js/; static/style.css; app.py deep-link handlers.

Confirmed problems. The /backgrounds route calls serve_html_with_nonce for static/backgrounds.html, but that file is absent from static/. This is a confirmed broken prototype route, not evidence about the rest of the frontend.

Open questions. Is /backgrounds currently an intentionally supported route or an obsolete prototype?

Chat, sessions, and streaming

Current implementation. routes/chat_routes.py and routes/chat_helpers.py coordinate requests, session state, and SSE delivery. src/chat_handler.py, src/chat_processor.py, src/llm_core.py, and src/session_actions.py provide message preparation, provider interaction, and session operations.

Canonical code locations. routes/chat_routes.py; routes/chat_helpers.py; routes/session_routes.py; src/chat_handler.py; src/chat_processor.py; src/llm_core.py; core/session_manager.py.

Confirmed problems. src/agent_loop.py annotates _resolved_tool_event_name with Any but imports no Any and does not enable postponed annotation evaluation. Python evaluates that annotation while importing the module, so this is an import-time defect at the checked baseline.

Open questions. No end-to-end provider or browser streaming run was performed for this map.

Agents, tools, and execution

Current implementation. src/agent_loop.py drives multi-round tool use. src/tool_execution.py dispatches calls and binds workspace context. src/agent_tools/ contains individual implementations; src/tool_security.py and src/tool_policy.py apply role and request policies. Long-running command work is represented by src/bg_jobs.py.

Canonical code locations. src/agent_loop.py; src/tool_execution.py; src/agent_tools/; src/tool_security.py; src/tool_policy.py; src/tool_schemas.py; src/bg_jobs.py.

Confirmed problems. The import-time annotation defect above blocks the main agent/tool path. The shell is intentionally not a filesystem or network sandbox; that is an authority boundary, not by itself a vulnerability claim.

Open questions. Which native, legacy, and MCP-qualified invocation paths reach each policy gate?

Models, providers, and local serving

Current implementation. Model routes delegate to discovery, capabilities, endpoint resolution, and LLM core modules. Cookbook routes and hardware-fit services handle model lifecycle and local-serving support.

Canonical code locations. routes/model_routes.py; src/model_discovery.py; src/model_capabilities.py; src/endpoint_resolver.py; src/llm_core.py; routes/cookbook_routes.py; src/cookbook_serve_lifecycle.py; services/hwfit/.

Confirmed problems. None recorded by this mapping.

Open questions. Which endpoint inputs are administrator-created and permitted to use private provider addresses?

Search and research

Current implementation. HTTP search routes use services/search/; research is exposed through routes/research/ and implemented in services/research/, src/deep_research.py, and related helpers. src/search/ remains an import-compatibility layer for callers not yet moved to services.search.

Canonical code locations. routes/search_routes.py; services/search/; routes/research/research_routes.py; services/research/; src/deep_research.py; src/search/.

Confirmed problems. The two search package paths are a confirmed compatibility arrangement, not two independent canonical implementations: several src/search modules forward to services.search. The remaining wrappers and compatibility imports can drift.

Open questions. No live provider request was made; provider configuration and network access remain unverified.

Documents, retrieval, and personal knowledge

Current implementation. Document routes coordinate upload handling, document processing, and editor actions. Personal-document and RAG modules use Chroma and embedding clients. PDF viewing uses the optional-dependency loader in src/pdf_runtime.py; form extraction and filling live separately in src/pdf_forms.py and src/pdf_form_doc.py.

Canonical code locations. routes/document_routes.py; src/upload_handler.py; src/document_processor.py; src/document_actions.py; src/personal_docs.py; src/rag_manager.py; src/embeddings.py; src/pdf_runtime.py; src/pdf_forms.py; src/pdf_form_doc.py.

Confirmed problems. PDF viewing/runtime loading and PDF form processing are separate implementations. That separation is confirmed and intentional in the source; it is not a defect without a reported behavioural failure.

Open questions. Optional PDF dependencies and representative uploaded documents were not exercised.

Memory and skills

Current implementation. Memory routes use services/memory/ and vector helpers. Skills are exposed through routes/skills_routes.py, stored and managed in services/memory/skills.py, and may be imported through services/memory/skill_importer.py.

Canonical code locations. routes/memory/memory_routes.py; services/memory/; src/memory.py; src/memory_vector.py; routes/skills_routes.py; services/memory/skills.py; services/memory/skill_importer.py.

Confirmed problems. None recorded by this mapping.

Open questions. Which imported skill content can reach execution-capable paths, and which validation occurs before that point?

Personal services: email, calendar, contacts, notes, and tasks

Current implementation. Dedicated route modules own email, CalDAV calendar, CardDAV contacts, notes, and tasks. Supporting modules include email helpers and pollers, CalDAV sync and writeback, and the task scheduler.

Canonical code locations. routes/email_routes.py; routes/calendar_routes.py; routes/contacts/contacts_routes.py; routes/note/note_routes.py; routes/task_routes.py; routes/assistant_routes.py; src/caldav_sync.py; src/caldav_writeback.py; src/task_scheduler.py.

Confirmed problems. None recorded by this mapping.

Open questions. External account behaviour, writeback, and delivery require controlled credentials and are not runtime-validated here.

Media, speech, and image work

Current implementation. Gallery and image routes coordinate media features. Service modules own speech and media integrations; src/generated_images.py and src/visual_report.py support artifact handling and presentation.

Canonical code locations. routes/gallery/gallery_routes.py; routes/stt_routes.py; routes/tts_routes.py; src/generated_images.py; services/stt/; services/tts/; services/faces/; src/visual_report.py.

Confirmed problems. None recorded by this mapping.

Open questions. Hardware- and provider-dependent media workflows were not exercised.

Authentication, secrets, and privileged administration

Current implementation. core/auth.py and core/middleware.py provide identity and request gates. src/secret_storage.py encrypts application-managed database secrets with a local Fernet key. Vault handling is separate: routes/vault_routes.py and src/tools/vault.py invoke the Bitwarden CLI and persist its session data in the application data area.

Canonical code locations. core/auth.py; core/middleware.py; routes/auth_routes.py; routes/api_token_routes.py; src/secret_storage.py; routes/vault_routes.py; src/tools/vault.py; routes/admin_wipe/admin_wipe_routes.py.

Confirmed problems. Vault-command handling and local application secret storage are distinct paths with different storage mechanisms. This is a source-confirmed boundary, not evidence that either path is compromised.

Open questions. What are the current confidentiality, ownership, rotation, and backup semantics for vault session data?

Persistence, background work, and operations

Current implementation. SQLite models and persistence are centred in core/database.py; managers use application data paths. The scheduler and background-job monitor can continue work outside a live browser request. Operational routes cover cleanup, backup, and administrative wipe; the repository also provides a backup script and user documentation.

Canonical code locations. core/database.py; src/runtime_paths.py; src/task_scheduler.py; src/bg_jobs.py; src/bg_monitor.py; routes/backup_routes.py; routes/cleanup/cleanup_routes.py; routes/admin_wipe/admin_wipe_routes.py; scripts/odysseus-backup; docs/backup-restore.md.

Confirmed problems. None recorded by this mapping.

Open questions. What current behaviour applies to background execution, cancellation, retries, and authority inheritance?