Architecture

Components

• Core (src/core/): Models, errors, config, versioning
• Index (src/index/): Index building, storage, loading
• Query (src/query/): Query planning, execution, verification
• Output (src/output/): SearchOutput formatting
• Connectors (src/connectors/): Source-specific adapters
• CLI (src/cli/): Command-line interface
• Daemon (src/daemon/): Persistent local process
• Security (src/security/): Safety checks, path validation
• Util (src/util/): Shared utilities

Data Flow

1. Config loaded -> Sources registered
2. Index build -> Source scanned -> Segments written -> Manifest committed
3. Query received -> Normalized -> Planned -> Candidates gathered -> Verified -> Sorted -> SearchOutput returned

Index Lifecycle

1. Create: Full scan -> Write segments -> Atomic manifest commit
2. Update: Diff source -> New segments -> Atomic manifest update
3. Compact: Merge segments -> New manifest -> Remove old segments
4. Verify: Check checksums -> Report health

Query Lifecycle

1. Parse query object
2. Normalize text (NFC, case handling)
3. Resolve source selectors to source IDs
4. Plan: Choose most selective index
5. Gather candidates from indexes
6. Intersect candidate sets
7. Verify candidates against metadata
8. Sort results deterministically
9. Paginate and return SearchOutput

Daemon Design

• Persistent process with hot indexes
• Unix domain socket communication
• Newline-delimited JSON protocol
• Supports health checks and graceful shutdown