Architecture¶

Module structure¶

deputy CLI (typer)
  └─ tools/core.py
       ├─ init → open_database + init_schema + detect_venv
       ├─ sync → get_source_files → deproc parse/link → upsert_entities
       │   └─ --sync-deps → detect_venv → list_installed_packages → process_dependency
       ├─ search → SQLite REGEXP query on entities
       ├─ info → get_entity_by_path / get_entities_by_path + inheritance info
       ├─ subclasses → get_direct_subclasses / get_transitive_subclasses
       ├─ pin-inheritance → upsert_inheritance_pin + eager_resolve_all_inherited_members
       ├─ resolve → InteractiveResolver (import alias chain tracing)
       └─ config → read/write .deputyconfig

  tools/inheritance.py
       ├─ compute_class_mro → delegates to deproc C3 linearisation
       ├─ get_inherited_members → collect from MRO chain
       ├─ eager_resolve_all_inherited_members → create INHERITED_MEMBER entities
       └─ resolve_entity_through_mro → resolve dotted paths via MRO

Data flow¶

Source files (.py/.pyi, .java)
    │
    ▼
deproc parser (language-aware linker + models)
    │
    ▼
SQLite database (.deputy.db)
    ├─ search → REGEXP queries on entities table
    ├─ info → entity lookup + class_bases + inheritance_pins
    ├─ resolve → import alias chain tracing (Python)
    └─ subclasses → class_bases + branch_entities

Multi-language support¶

create_context registers both python (.py/.pyi) and java (.java). _process_files groups source files by extension and processes each language in an isolated Context (fresh EntityRegistry) so parsers/linkers/serializers never interfere:

Python: PythonSourceParser/PythonLinker, module exports, deproc.plugins.python...entity_to_record
Java: JavaSourceParser/JavaLinker, deproc.plugins.java...entity_to_record

search --language java and the info/search Java columns (annotations, superclass, implements, is_abstract, is_final, is_static) surface Java entities. Java IMPORT entities are excluded from search results (mirroring Python's excluded IMPORT_STATEMENT). The inheritance pipeline (class_bases/MRO/inherited members) is Python-only for now — Java classes serialize superclass/implements and are skipped.

Dependencies¶

Package	Role
`deproc-core`	Plugin core — AST models, linker, resolver, entity registry, entity utilities (parent-chain walking, scope classification)
`deproc-python`	Python language parser — tree-sitter based, C3 MRO utilities, module exports builder, entity serialization
`deproc-java`	Java language parser — tree-sitter based, package hierarchy, entity serialization
`deproc-utils-python-env`	Virtual environment detection and package discovery
`deproc-utils-tree-sitter`	Tree-sitter utilities for parsing
`typer`	CLI framework
`rich`	Terminal output (tables, trees, panels)

Branch awareness¶

deputy is branch-aware. The branch_entities and branch_files tables track which entities and files belong to which git branch. The current branch is auto-detected via git branch --show-current.

deputy sync only re-parses files that changed on the current branch
deputy subclasses scopes results to the current branch by default
deputy pin-inheritance pins are branch-scoped