Skip to content

sysmledgraph-CODEBASE_STRUCTURE.md

Latest commit

 

History

History
134 lines (106 loc) · 6 KB

sysmledgraph-CODEBASE_STRUCTURE.md

File metadata and controls

134 lines (106 loc) · 6 KB

sysmledgraph – codebase structure (plan)

Purpose: Layout for the sysmledgraph implementation (codebase repo). Aligns with sysmledgraph-DEVELOPMENT_PLAN.md and the deploy model (deploy-sysmledgraph.sysml).

1. Top-level layout

sysmledgraph/                    # codebase repo root
├── package.json
├── tsconfig.json
├── .nvmrc or engines (Node 20+)
├── README.md
├── src/                         # core (Phase 1–2)
├── bin/                         # CLI entrypoint (Phase 4)
├── mcp/                         # MCP server entrypoint (Phase 3)
├── test/                        # unit + integration
├── schema/                      # graph schema (code or migrations)
├── config.schema.json           # optional: CLI/MCP config schema
└── docs/                        # optional: schema doc, MCP setup

2. src/ – core modules (map to deploy model)

Deploy part Module path / role
Indexer src/indexer/ – file discovery, load order, parser integration, symbol→graph mapping
GraphStore src/graph/ – Kuzu DB open/create, addDocument, addSymbol, addEdge, getConnection, schema init
McpServer src/mcp/ – server setup, tool handlers (query, context, impact, rename, cypher, list_indexed, clean_index), resources
Cli src/cli/ – commander subcommands (analyze, list, clean), delegates to indexer + graph

Shared and cross-cutting:

  • src/discovery/ – file discovery (.sysml/.kerml), config.yaml and model_files load order (Phase 1 step 4).
  • src/parser/ – sysml-v2-lsp integration (library or stdio client); parse → symbol list + relations (Phase 1 step 3).
  • src/symbol-to-graph/ – map LSP symbol kinds → node labels and edge types (Phase 2; single place to avoid schema drift).
  • src/storage/ – storage location policy: per-path vs global registry; list/clean implementation (Phase 2 step 7–9).
  • src/types.ts (or types/) – shared types (Document, Symbol props, edge types, tool params).

Suggested src/ tree:

src/
├── indexer/
│   ├── indexer.ts           # main index pipeline: discovery → parse → symbol-to-graph → graphStore
│   └── indexer.test.ts
├── graph/
│   ├── graph-store.ts       # GraphStore API
│   ├── schema.ts            # node labels, edge types, init/migration
│   └── connection.ts        # getConnection() for Cypher
├── mcp/
│   ├── server.ts            # stdio transport, server name "sysmledgraph"
│   ├── tools/
│   │   ├── index-db-graph.ts
│   │   ├── query.ts
│   │   ├── context.ts
│   │   ├── impact.ts
│   │   ├── rename.ts
│   │   ├── cypher.ts
│   │   ├── list-indexed.ts
│   │   └── clean-index.ts
│   └── resources/
│       ├── context.ts       # sysmledgraph://context (stats, staleness)
│       └── schema.ts        # sysmledgraph://schema
├── cli/
│   └── commands.ts         # analyze, list, clean
├── discovery/
│   ├── find-sysml.ts       # fast-glob or fs+glob
│   └── load-order.ts       # config.yaml model_files, else deterministic
├── parser/
│   ├── lsp-client.ts       # library or stdio client to sysml-v2-lsp
│   └── symbols.ts          # normalized symbol/relation shape for graph
├── symbol-to-graph/
│   └── mapping.ts          # LSP kinds → node labels + edge types (documented)
├── storage/
│   ├── location.ts         # resolve DB path (per-path or registry)
│   ├── list.ts
│   └── clean.ts
└── types.ts

3. Entrypoints

Entrypoint File Purpose
CLI bin/cli.js (or bin/sysmledgraph.js) Requires src/cli/; runs analyze / list / clean.
MCP mcp/index.js (or bin/mcp.js) Requires src/mcp/server; stdio server for Cursor / MCP clients.

package.json scripts example:

  • "bin": { "sysmledgraph": "bin/cli.js" } and/or "bin": { "sysmledgraph-mcp": "mcp/index.js" }
  • "build": "tsc"
  • "test": "vitest" (or jest)

4. Schema and config

  • Graph schema: Define in one place: either src/graph/schema.ts (Kuzu DDL or API calls) or schema/*.cypher / migration scripts. Expose the same text via MCP resource sysmledgraph://schema and README/schema doc.
  • Config: Env (e.g. SYSMEDGRAPH_STORAGE_ROOT) or config file; document in README. Optional config.schema.json for validation.

5. Phase → what gets added

Phase Focus Directories / files to add
1 Repo, pipeline, parser, discovery Root + src/discovery/, src/parser/, src/types.ts; src/symbol-to-graph/mapping.ts (stub or partial); tests for discovery and parser output.
2 Graph, indexer, list/clean src/graph/, src/storage/, src/indexer/, src/symbol-to-graph/ (full mapping); schema init; tests for GraphStore and indexer.
3 MCP server src/mcp/, mcp/index.js; tool and resource implementations.
4 CLI and docs src/cli/, bin/cli.js; README, schema doc, MCP setup.

6. Dependencies (recap)

  • Kuzu – graph DB
  • @modelcontextprotocol/sdk – MCP server (stdio)
  • commander – CLI
  • fast-glob – file discovery
  • sysml-v2-lsp – npm package (this repo uses it for MCP); parser/symbols (library or stdio)

7. References