yams/docs/developer/architecture/README.md

Developer Architecture Notes

This index points to architecture references that mirror the live implementation. Always validate statements against the cited source modules.

Core Architecture References

• Daemon and services — lifecycle, IPC, plugin hosting
  • Architecture: Daemon and Services
• Plugin pipeline — manifest parsing, trust, runtime loaders
  • Architecture: Plugin and Content Extraction
• Search pipeline — ingestion, ranking, hybrid fusion
  • CLI search and grep reference
• Vector subsystem — embedding providers, storage, repair routines
  • Embeddings guide

Supporting Design Notes

• Content handlers and normalization pathways
  • Design: Content Handler Architecture
• Synchronization protocol details
  • Design: Sync Protocol

API References

• API Overview
• MCP Tools

Operations and Performance Guides

• Admin: Operations
• Performance Report

Contribution Workflow

1. Update architecture docs and any related traceability artifacts in the same change set.
2. Anchor new prose to specific functions, classes, or modules under src/.
3. Capture validation evidence (integration logs, benchmarks) alongside the change with timestamps.
4. Run mkdocs build --strict and archive the log before submitting changes.
5. Flag future work explicitly with issue references; avoid speculative language.

Missing topics should be proposed via issue (outline + intended source references) prior to documentation work.