Skip to main content

Current architecture (v1 / MVP)

Note: This section is for curious devs and contributors. It is not required for daily GhostMap use.

Flow diagram​

Workspace
   ↓
Symbol Extraction      (LSP → Tree-sitter → regex/PHP fallback)
   ↓
Anchor Parsing         (reads @ghost line comments in the document)
   ↓
Ownership Resolution   (attaches contextual metadata to the closest symbol;
                         detects detached/ambiguous)
   ↓
Hierarchy Builder      (tree by range containment)
   ↓
Ghost Tree             (filters, search, icons)
   ↓
VS Code UI             (Tree View + Hover + Diagnostics + Code Actions)

When it runs​

The full pipeline runs:

  • When an editor opens or activates.
  • On every edit, with a small debounce so it does not recompute on every keystroke.

In V1, there is no full cross-session workspace persistence: each file open repeats the computation. The exception is the per-document continuity cache described in Local State. The v2 roadmap plans to eliminate this recompute with a persistent workspace index.

Data model (GhostItem)​

interface GhostItem {
  id: string;
  name: string;
  type: 'function' | 'class' | 'anchor';
  range: vscode.Range;
  endLine?: number;
  anchorKind?: 'single' | 'range' | 'contextual';
  description?: string;
  status?: string;
  children?: GhostItem[];
}

Next step​

Continue with Loading Policy to understand how GhostMap handles large files.

Last updated on