yams/docs/developer/architecture

Developer Architecture Notes

This index collects architecture materials for YAMS. It points to system overviews, component designs, and related references. Keep documents technical, accurate, and concise.

Core architecture

• Search system
  • Search pipeline, FTS, metadata, and query flows:
    • Architecture: Search System
• Vector search
  • Embedding ingestion, index layout, retrieval, and fusion strategies:
    • Architecture: Vector Search

Design notes

• Content handlers and extensibility: adapters, media types, and normalization
  • Design: Content Handler Architecture
• Synchronization model and consistency guarantees
  • Design: Sync Protocol

APIs

• High‑level API documentation and OpenAPI
  • API Overview
  • Search API
  • Vector Search API
  • OpenAPI (YAML)
  • MCP Tools

Operations and tuning (reference)

• Admin
  • Configuration
  • Performance Tuning
  • Vector Search Tuning
• Operations
  • Deployment
  • Monitoring
  • Backup
• Benchmarks
  • Performance Report

Data and engine quick facts

• Storage: content‑addressed (SHA‑256), block‑level deduplication (Rabin), compression (zstd/LZMA).
• Indexing: SQLite FTS5 for full‑text; vector index for semantic retrieval.
• Consistency: WAL for crash safety; explicit snapshot and collection semantics where applicable.
• Interfaces: CLI and API; MCP server support for tool integrations.

Contributing to architecture docs

• Location: add new overviews under docs/architecture/; component/feature deep‑dives under docs/design/.
• Scope: one topic per document; link related docs at top.
• Style: concise, diagrams optional (store sources alongside images).
• Versioning: note behavioral differences if the doc applies to specific versions. Pre‑1.0 (v0.x) may change; call out stability caveats.

If a topic is missing, open an issue proposing the outline and intended placement before submitting a PR.