Architecture

Nomik's system architecture — 8 packages in a Turborepo monorepo, data flow pipeline, graph query modules, and design principles.

System Overview

Architectural Component Dependencies

Data Flow Pipeline

Data Flow Pipeline Architecture

Stage	Component	What Happens
Parse	`@nomik/parser`	Tree-sitter parses source code into ASTs. 37 extractors convert AST nodes into typed graph nodes and edges. Config files (.env, Dockerfile, YAML, Terraform, GraphQL, JSON) are dispatched to a dedicated regex-based config parser
Store	`@nomik/graph`	Nodes and edges are batch-ingested into Neo4j via `UNWIND` upserts. QueryCache (30s TTL, 200 entries) with LRU eviction. Exponential retry backoff on transient errors
Sync	`@nomik/watcher`	Chokidar monitors file changes with 500ms debounce. Only changed files are re-parsed — existing nodes for a file are cleared before re-ingestion. Deleted files are automatically cleaned from the graph
Query	MCP / CLI / REST	AI assistants query via 21 MCP tools. Developers use 38 CLI commands. REST API exposes 14 endpoints on port 4242. Viz dashboard for interactive exploration

Packages (8)

Nomik is organized as a Turborepo monorepo with pnpm workspaces. Each package has strict boundaries and no circular dependencies.

`@nomik-ai/cli`

Command-line interface — 38 commands organized into core, analysis, architecture, quality, documentation, setup, server, and project management categories. Standalone bundle via tsup.

`@nomik/core`

Shared infrastructure for all packages:

Types (types/) — GraphNode discriminated union (FileNode, FunctionNode, ClassNode, etc.) and GraphEdge types
Configuration (config/) — Zod-validated config with defineConfig helper
Error handling (errors/) — NomikError base class, ParseError, GraphConnectionError
Logger (logger/) — Pino-based structured JSON logging, configurable via LOG_LEVEL

`@nomik/parser`

Intelligence engine — 37 extractors for 7+ languages:

Code languages: TypeScript, JavaScript, Python, Rust, Markdown, SQL, C#/Django/Alembic
Config files: .env, Dockerfile, docker-compose, Kubernetes YAML, Terraform .tf, GraphQL .graphql/.gql, GitHub Actions, GitLab CI, CloudFormation, OpenAPI, package.json, requirements.txt
Categories: code, API, data, infrastructure, config, security, Python runtime
Resolvers: cross-file CALLS (multi-map with name collision defense), intra-file CALLS, route handling
Config dispatch: config-file-parser.ts routes non-code files to the right extractors without tree-sitter
Monorepo support: tsconfig/jsconfig path alias resolution

`@nomik/graph`

Neo4j persistence layer with 10 query modules:

Module	Queries
`read.ts`	impact, path, chain, stats, recent, DB impact, search, file symbols
`read-health.ts`	dead code, god objects, god files, duplicates
`read-explain.ts`	symbol explain, cross-service links
`read-onboard.ts`	aggregated codebase briefing
`read-community.ts`	Union-Find functional clustering
`read-flows.ts`	execution flow tracing from entry points
`read-diff.ts`	architecture drift between snapshots
`read-rules.ts`	9 built-in rules + custom Cypher evaluation
`read-test-impact.ts`	affected test file detection
`write.ts`	node/edge upsert, file clear, project CRUD, stale file purge

Features: schema auto-initialization, batch UNWIND upserts, QueryCache (30s TTL, LRU), exponential retry, createdAt/updatedAt timestamps on all nodes and edges.

`@nomik/mcp-server`

AI interface via Model Context Protocol:

21 tools — search, impact, explain, health, communities, flows, diff, rules, guard, rename, wiki, and more
9 resources — browsable data endpoints (stats, health, files, schema, etc.)
6 prompts — pre-built conversation starters (onboard, review-change, health-check, etc.)
Role-scoped access — dev, architect, security, pm roles filter available tools
Sampling — server-to-client LLM completion requests for AI-augmented analysis

`@nomik/viz`

React visualization dashboard:

2D graph — Cytoscape.js with 4 layouts (Force, Tree, Radial, Circle)
3D graph — Three.js with DNA/neural network style rotation and animated edge particles
Features — search with ranked results, node type filters, impact overlay, detail panel, stats panel, help modal, project selector, dark theme

@nomik/core
  ├── @nomik/parser
  ├── @nomik/graph
  │     ├── @nomik/mcp-server (+ roles, sampling)
  │     └── @nomik/watcher (+ parser)
  └── @nomik/viz (types only, isolated)

@nomik-ai/cli ── depends on all packages
@nomik/github-bot ── depends on graph

Multi-Project Isolation

Nomik supports multiple projects in a single Neo4j database:

Every node and edge carries a projectId property
All queries filter by the active projectId
CLI commands accept --project <name> to override
Active project is stored in .nomik/project.json

Design Principles

Strict boundaries — No circular dependencies between packages. core is the leaf
Pipeline architecture — Parsing and ingestion are separate, composable steps
Import-aware extraction — All extractors resolve receiver variables from actual imports, not hardcoded names
Observability — Structured JSON logging (Pino) in every package
Typed errors — NomikError with code, severity, and recoverable fields
Project isolation — projectId on all nodes, edges, and queries
Cache-first — QueryCache with TTL and automatic invalidation after writes