t1k:nakama:service-graph

Field	Value
Module	`base`
Version	`1.6.2`
Effort	`medium`
Tools	—

Keywords: er-diagram, go-mod-graph, godepgraph, lua-rpc, nakama, nakama-architecture, register_rpc, rpc-graph, service-graph, sql-schema

How to invoke

/t1k:nakama:service-graph

t1k-nakama-service-graph

Nakama diagram adapter for the T1K diagram toolchain. Produces a three-layer service graph for Nakama backends that mix:

Go module layer — go mod graph wrapper, filtered to the nakama-* adjacency, rendered as a Mermaid graph LR.
Lua RPC handler layer — regex scan of .lua sources for nk.register_rpc, nakama.register_rpc, nk.register_rt_before, nk.register_match. Emits a Mermaid flowchart listing handlers per file.
DB schema ER layer — regex scan of migrations/*.sql (configurable) for CREATE TABLE + REFERENCES + FOREIGN KEY clauses. Emits a Mermaid erDiagram block.

Output mode is selected by --layer go|lua|db|all (default all). Missing sources degrade gracefully — each layer is optional, and the adapter records a warnings[] entry when a layer is skipped instead of failing.

Prerequisites

t1k diagram install --preset nakama

Installs mermaid-cli, godepgraph, and (optionally) graphviz. godepgraph install requires Go 1.21+ SDK — verified by the installer’s prerequisite check.

The lua and db layers work without Go. Only the go layer requires the Go toolchain + godepgraph.

Usage

# Refresh mode — stacked three-layer diagram
node scripts/generate.cjs --type services --out-dir /tmp/out            # all layers (default)
node scripts/generate.cjs --type services --layer go --out-dir /tmp/out
node scripts/generate.cjs --type services --layer lua --out-dir /tmp/out
node scripts/generate.cjs --type services --layer db --out-dir /tmp/out

# Flags
--full                     # Go layer: disable nakama-* adjacency filter
--migrations-dir <rel>     # DB layer: override migrations dir (default: migrations/, sql/, db/migrations/)
--tables-match <regex>     # DB layer: include only tables matching regex

# Check if this adapter applies to current project
node scripts/detect.cjs   # exit 0 = match

# List available capabilities
node scripts/list-capabilities.cjs

# Show tool requirements
node scripts/requirements.cjs

Output Files

Capability	Layer	Output
`services`	`all`	`services.md` — three stacked subgraphs (Go, Lua, DB)
`services`	`go`	`services.md` — Go module graph only
`services`	`lua`	`services.md` — Lua RPC handlers only
`services`	`db`	`services.md` — DB ER diagram only

Layer Details

Go layer

Shells out to go mod graph via execFileSync with { windowsHide: true }.
Parses lines of the form A@v B@v into directed edges.
Default filter: includes edges where either endpoint matches /(^|\/)nakama/ — keeps diagrams readable for backends with hundreds of indirect deps.
--full disables the filter.
If go binary is missing OR go.mod is absent the layer is skipped with warnings: ["go layer skipped — no go.mod found"].

Lua layer (regex-based — intentional MVP)

The Lua RPC scanner uses a regex-based parser, not a full Lua parser. This is a deliberate MVP tradeoff:

Supported patterns:
- nk.register_rpc("name", fn)
- nakama.register_rpc("name", fn) (alt binding)
- nk.register_rt_before("name", fn)
- nk.register_match("name", fn)
Known limitation: indirect bindings (local r = nk.register_rpc; r(...)) are not detected. Document these with an @rpc comment marker if you need them surfaced (future: opt-in override).
Each match emits a summary: "N handlers found across M files" with per-handler provenance (file + 1-indexed line).

If no .lua files contain register_* calls the layer is skipped with warnings: ["lua layer skipped — no register_rpc calls found"].

DB ER layer (Postgres dialect)

Default probe order for migrations dir: migrations/, sql/, db/migrations/.
Regex scans for:
- CREATE TABLE (?:IF NOT EXISTS )?(\w+) \(
- REFERENCES (\w+)\s*\(\s*(\w+)\s*\)
- FOREIGN KEY\s*\([^)]*\)\s*REFERENCES (\w+)
Emits Mermaid erDiagram with ||--o{ edges (one-to-many).
Dialect: Postgres is the primary target (Nakama’s default). MySQL / SQLite support is planned for v1.1.0 — unknown dialects emit a warning and skip unrecognized statements.
--tables-match <regex> narrows the table set when a backend has many tables.

Known Limitations

Lua parser is regex-based (see above). Indirect register_rpc bindings and dynamic RPC names not detected.
Go layer requires go.mod at the project root. Nested go.mod in subdirectories is not traversed (use --cwd if needed).
ER diagram dialect is Postgres-first. Nakama runs on Postgres by default, so this is the common case.
Three-layer diagram in a 50+ table / 500+ dep / 100+ handler project will be large — use --tables-match, --full off, and per-layer output to keep diagrams readable.

References

File	Content
`references/layer-go.md`	`go mod graph` notes, `nakama-*` filter heuristic, `--full` override
`references/layer-lua.md`	Supported Nakama Lua APIs; regex-parser tradeoffs
`references/layer-db-er.md`	Postgres dialect notes, migration-file conventions