overview architecture

Architecture

Lode has one package, src/lode, with a CLI, a local HTTP daemon, and a shared indexing/search core. The current codebase has 55 tracked files and 7,810 lines, with Python making up 5,233 lines and the core source tree making up 14 files.

Component map

graph TD
    subgraph Entrypoints
        CLI[src/lode/cli.py]
        Daemon[src/lode/daemon.py]
    end

    subgraph Core
        Indexer[src/lode/indexer.py]
        Storage[src/lode/storage.py]
        Graph[src/lode/graph.py]
        Context[src/lode/context.py]
    end

    subgraph Optional
        Embeddings[src/lode/embeddings.py]
        Kuzu[src/lode/kuzu_store.py]
    end

    CLI --> Indexer
    CLI --> Storage
    CLI --> Graph
    CLI --> Context
    Daemon --> Indexer
    Daemon --> Storage
    Daemon --> Graph
    Daemon --> Context
    Indexer --> Storage
    Storage --> SQLite[(lode.sqlite)]
    Graph --> SQLite
    Context --> SQLite
    Embeddings --> SQLite
    Kuzu --> SQLite

Loading

Main data flow

src/lode/indexer.py walks source files, skips generated and cache directories, hashes file contents, parses language-specific facts, writes them through src/lode/storage.py, then calls resolve_graph() in src/lode/graph.py to connect imports, calls, and inheritance edges.

sequenceDiagram
    participant User as User or agent
    participant CLI as src/lode/cli.py
    participant IDX as src/lode/indexer.py
    participant DB as src/lode/storage.py
    participant GR as src/lode/graph.py

    User->>CLI: lode index PATH
    CLI->>IDX: index_repo(path)
    IDX->>IDX: scan, hash, parse
    IDX->>DB: replace_file_index()
    IDX->>GR: resolve_graph()
    GR->>DB: write resolved edges
    CLI-->>User: JSON stats

Loading

Storage choices

SQLite is the hot path in src/lode/storage.py. It owns repository records, file records, nodes, edges, FTS5 search rows, an embedding queue, and persisted vectors. Kuzu is optional through src/lode/kuzu_store.py and is rebuilt from SQLite facts when lode kuzu-sync runs.

Runtime shape

The CLI in src/lode/cli.py and daemon in src/lode/daemon.py share the same storage and graph functions. This keeps command-line behavior and daemon responses aligned, while src/lode/observability.py adds structured logs and local request counters for the daemon.

Related pages

• CLI and daemon
• Storage and search
• Graph and impact
• Data models