Modules

Modules

Spector is organized as a multi-module Maven project. Each module has a focused responsibility, clear API boundaries, and minimal cross-module coupling.

---

Architecture Hierarchy

graph TB
    subgraph nucleus["nucleus/ (Foundation & Observability)"]
        commons["spector-commons<br/><i>Chunkers, tokenizer</i>"]
        core["spector-core<br/><i>SIMD kernels</i>"]
        config["spector-config<br/><i>SpectorConfig + YAML</i>"]
        storage["spector-storage<br/><i>Panama MemorySegment</i>"]
        events["spector-events<br/><i>Telemetry event bus</i>"]
        metrics["spector-metrics<br/><i>Micrometer + TelemetryBus</i>"]
        testsupport["spector-test-support<br/><i>Integration test harnesses</i>"]
    end

    subgraph memory["memory/ (Cognitive Memory Engine)"]
        spectormemory["spector-memory<br/><i>Cognitive store & search facade</i>"]
        index["spector-index<br/><i>HNSW + IVF-PQ + BM25</i>"]
        query["spector-query<br/><i>Hybrid + RRF + rerank</i>"]
        gpu["spector-gpu<br/><i>CUDA via Panama FFM</i>"]
        providerApi["spector-provider-api<br/><i>Provider SPI</i>"]
        providers["spector-providers<br/><i>AI Providers</i>"]
        ingestion["spector-ingestion<br/><i>File ingest pipeline</i>"]
    end

    subgraph synapse["synapse/ (API, Runtime & CLI Gateways)"]
        runtime["spector-runtime<br/><i>Composition root</i>"]
        synapseapp["spector-synapse<br/><i>Armeria REST/gRPC/SSE server</i>"]
        mcp["spector-mcp<br/><i>MCP Server (stdio/HTTP)</i>"]
        cli["spector-cli<br/><i>spectorctl CLI</i>"]
        client["spector-client<br/><i>Java SDK</i>"]
        spring["spector-spring<br/><i>Spring AI VectorStore</i>"]
        dist["spector-dist<br/><i>Fat JAR distribution</i>"]
    end

    subgraph cortex["cortex/ (UI Dashboard)"]
        spectorcortex["spector-cortex<br/><i>Angular 22 neural UI</i>"]
    end

    subgraph bench["bench/ (Performance)"]
        spectorbench["spector-bench<br/><i>JMH benchmarks</i>"]
    end

    nucleus --> memory --> synapse
    synapse --> cortex
    memory -.-> bench

Loading

---

Module Dependency Graph

graph TD
    synapseapp["🌐 synapse"] --> runtime["⚡ runtime"]
    synapseapp --> mcp["🤖 mcp"]
    synapseapp --> metrics["📈 metrics"]
    synapseapp --> events["📡 events"]
    
    mcp --> runtime
    mcp --> ingestion["📥 ingestion"]
    cli["🖥️ cli"] --> runtime
    cli --> client["📦 client"]

    runtime --> memory["🧠 memory"]
    runtime --> ingestion

    memory --> query["🔍 query"]
    memory --> index["📊 index"]
    memory --> storage["💾 storage"]
    memory --> embedapi["🧬 embed-api"]
    memory -.-> gpu["🎮 gpu"]
    memory --> rag["🤖 rag"]
    memory --> core["🔬 core"]

    metrics --> memory
    metrics --> events

    events --> commons["📄 commons"]

    cortex["🧠 cortex"] -.->|SSE| synapseapp

    ingestion --> config["⚙️ config"]
    ingestion --> embedapi

    rag --> query
    rag --> index
    rag --> storage
    rag --> embedapi

    query --> index
    index --> storage
    index --> config
    storage --> config
    storage --> core
    config --> core

    embedapi --> commons
    gpu --> core
    gpu --> storage

    dist["📦 dist"] --> mcp
    dist --> cli
    dist --> runtime

    spring["🌱 spring"] --> memory
    spring --> metrics
    bench["🧪 bench"] --> memory

Loading

Legend: Solid arrows = compile dependency. Dotted arrows = optional/runtime dependency (gpu = optional Maven dep, cortex = connects via SSE at runtime).

important: Architecture spector-ingestion defines the IngestionPipeline and IngestionTarget interface. spector-memory depends on it to implement both EngineIngestionTarget and CognitiveIngestionTarget. The entry points route requests to SpectorRuntime, which acts as the composition root.

---

Architecture: Entry Points → Runtime → Subsystems

All entry points (MCP, CLI, Server) route through SpectorRuntime:

graph TD
    cli["🖥️ spector-cli<br/><i>SpectorCtl</i>"]
    mcp["🤖 spector-mcp<br/><i>SpectorMcpMain</i>"]
    synapseapp["🌐 spector-synapse<br/><i>SynapseApplication (Armeria)</i>"]

    cli --> runtime
    mcp --> runtime
    synapseapp --> runtime

    runtime["⚡ SpectorRuntime<br/><i>Composition Root</i>"]

    runtime --> sh["SearchHandler<br/><i>mode-aware search</i>"]
    runtime --> ih["IngestionHandler<br/><i>delegates to IngestionPipeline</i>"]

    sh --> memory["SpectorMemory (under memory/)"]
    ih --> pipeline["IngestionPipeline<br/><i>chunk → embed → store</i>"]
    pipeline --> engineTarget["EngineIngestionTarget<br/><i>SEARCH mode (under memory/)</i>"]
    pipeline --> memTarget["CognitiveIngestionTarget<br/><i>MEMORY mode (under memory/)</i>"]

Loading

SpectorRuntime is a thin composition root — it creates and wires subsystems but contains no business logic. Each handler owns its domain:

Handler	Responsibility	Routes to
SearchHandler	Mode-aware search & retrieval	SpectorMemory (SEARCH or MEMORY modes)
IngestionHandler	Delegates to unified IngestionPipeline	Pipeline → EngineIngestionTarget or CognitiveIngestionTarget

---

Module Overview

Foundation Layer

Module	Description
[[spector-commons	Modules--Spector-Commons]]
[[spector-core	Modules--Spector-Core]]
[[spector-config	Modules--Spector-Config]]
[[spector-storage	Modules--Spector-Storage]]

Embedding Layer

Module	Description
[[spector-provider-api	Modules--Spector-Provider-Api]]
[[spector-providers	Modules--Spector-Providers]]

Search Layer

Module	Description
[[spector-index	Modules--Spector-Index]]
[[spector-query	Modules--Spector-Query]]
[[spector-gpu	Modules--Spector-Gpu]]

Intelligence Layer

Module	Description
[[spector-ingestion	Modules--Spector-Ingestion]]
[[spector-memory	Modules--Spector-Memory]]

Runtime Layer

Module	Description
[[spector-runtime	Modules--Spector-Runtime]]
[[spector-mcp	Modules--Spector-Mcp]]
[[spector-synapse	Modules--Spector-Synapse]]

Client Layer

Module	Description
[[spector-cli	Modules--Spector-Cli]]
[[spector-client	Modules--Spector-Client]]
[[spector-spring	Modules--Spector-Spring]]

Infrastructure

Module	Description
[[spector-events	Modules--Spector-Events]]
[[spector-metrics	Modules--Spector-Metrics]]
[[spector-cortex	Modules--Spector-Cortex]]
[[spector-bench	Modules--Spector-Bench]]
[[spector-dist	Modules--Spector-Dist]]