Complete Tutorial

End-to-end ARCLUX tutorial (verified against real repos)

ARCLUX Complete Tutorial

Learn ARCLUX end to end — from first install to daemon, detectors, rules, and CI gating.

Every command and output in this tutorial was verified against a real open-source repository (Flask, 83 modules). Where output is shown, it is the actual output ARCLUX produced, so you know what to expect before you run it.

---

Part 1 — What ARCLUX is

ARCLUX builds an accurate structural model of a codebase:

repository -> parser -> index -> graph -> impact -> detectors
                                   \-> rules (framework conventions)

It answers questions like:

• Which files depend on which? (graph)
• What breaks if I change file X? (impact)
• Where are circular dependencies, dead code, orphan files? (doctor)
• Does this repo follow framework conventions? (verify)
• Did the architecture change between two commits? (diff)

ARCLUX is a deterministic structural-truth engine: every fact it reports is traceable to a real import statement, export declaration, or resolved path. No AI, no guessing.

Supported languages today: TypeScript, JavaScript, Python, Go, Java, PHP, Ruby, Rust, C++, C#, Bash, C, Dart, Elixir, Kotlin, Lua, Objective-C, OCaml, Scala, Solidity, Swift, Vue, Zig, Elm, ReScript (25 via web-tree-sitter, 2 via TypeScript Compiler API) plus manifest parsers for package.json, go.mod, Cargo.toml, Gemfile, composer.json, .csproj, Gradle/POM, requirements.txt.

Part 2 — Install & setup

Requirements: Node 20+, pnpm.

git clone https://github.com/GSF-001/ARCLUX.git
cd ARCLUX
pnpm install

Run the CLI with tsx (no build step needed):

npx tsx apps/cli/index.ts --help

Or add an alias so you don’t type the prefix every time:

alias arclux="npx tsx $(pwd)/apps/cli/index.ts"

Verify it works:

arclux analyze .

Part 3 — Your first analysis

Point ARCLUX at any repository on disk (it needs no network for local analysis):

arclux analyze ~/flask

Real output (analyzing Flask):

●  Repository: flask
│
●  Frameworks: none detected
│
●  Package manager: uv
│
◆  83 modules indexed
│
●  Scan: 83 files, 83 parsed, 0 skipped (no parser)
│
◆  83 nodes, 118 edges in dependency graph
│
●  Detectors: 184 issues — circular 43, unused 116, orphan 25, layer 0
│
●  Elapsed: 2.19s

Reading the output:

• modules indexed — how many files made it into the model
• Scan: X parsed, Y skipped — the population guard. If a repo has files in a language without a parser yet, they are counted as skipped, not silently dropped. 0 skipped means the whole repo got into the graph.
• nodes / edges — the size of the dependency graph
• Detectors — a first-pass summary of what doctor will report in detail

Part 4 — Working with the graph

The dependency graph can be printed or saved as JSON:

arclux graph ~/flask
arclux graph ~/flask -o graph.json

Real output:

●  83 nodes, 118 edges
│
│    [file] conf.py
│
│    [file] make_celery.py
│
│    [file] __init__.py
│
│    [file] tasks.py
│
│    [file] views.py

Graph variants available in packages/graph/:

• buildDependencyGraph — module-level import graph (what graph prints)
• buildImportGraph — same shape, import edges
• buildCallGraph — which module’s functions are actually called, edge weight = distinct call sites
• buildExportGraph — export/re-export chains
• buildFolderGraph — folder-level tree (used by the web dashboard)

Part 5 — Impact analysis

The killer feature: what is affected if this file changes?

arclux impact <file> [repoPath]

Real output for src/flask/app.py:

●  Direct consumers (6):
│
│    src/flask/__init__.py
│
│    src/flask/cli.py
│
│    src/flask/ctx.py
│
│    src/flask/globals.py
│
│    src/flask/sessions.py

impact traces both directions — direct consumers (importers) and, on the web side, the full affected-files tree. Use it before any refactor: change the file, know exactly who breaks.

Part 6 — Doctor: 20 detectors

doctor runs the full detector suite and normalizes every finding to checkId + severity + message:

arclux doctor ~/flask

Real output (excerpt):

▲  43 circular dependencies found:
│
│    examples/celery/src/task_app/__init__.py → examples/celery/src/task_app/__init__.py
│
│    examples/tutorial/flaskr/__init__.py → examples/tutorial/flaskr/__init__.py
│
│    src/flask/__init__.py → src/flask/__init__.py
│
│    src/flask/__init__.py → src/flask/app.py → src/flask/__init__.py
│
│    src/flask/__init__.py → src/flask/app.py → src/flask/ctx.py → src/flask/__init__.py

The 20 detectors (all crash-isolated — a detector that throws becomes an error finding, it never kills the run):

Severity	Detectors
error	circularDependency, unusedExports, orphanFiles, layerViolation, ambiguousSymbolResolution
warning	largeModules, duplicateModules, indexFiles, deadCode, componentConvention, featureStructure, missingExports, repositoryPattern, routeConvention, storyConvention, testConvention, unusedFiles
info	sharedModules, entryPoints

Part 7 — Verify: the CI gate

verify runs detectors + framework rules and gives a single PASS/FAIL verdict — this is the command to gate CI on:

arclux verify ~/flask

Real output:

●  Detectors: 246 issue(s) across 10 checks
│
●  Rules: 0 violation(s) (0 error, 0 warning) — frameworks checked: none detected
│
■  FAIL — 246 detector issue(s), 0 rule error(s)

The 14 framework rules (Next.js, NestJS, Express, Vite, Electron, React, Laravel) only fire when the corresponding framework is detected — a plain Python repo reports frameworks checked: none detected and only detectors matter.

Part 8 — Diff: architectural change between refs

arclux diff <refA> <refB> [repoPath]

Shows the architectural impact of changes between two git refs — which modules gained/lost dependencies, which edges changed. Run it in code review or before merge to catch unintended architectural drift.

Part 9 — Diagnose

diagnose runs the wired diagnostic adapters (circularDependency, deadCode, ambiguousSymbolResolution) with impact context and fix suggestions — not just “what”, but “who it affects”:

arclux diagnose ~/flask

Real output (excerpt):

▲  387 diagnostic event(s) found:
│
│    [error] examples/celery/src/task_app/__init__.py — Circular dependency: ...
│
│      affects 1 file(s)

Part 10 — Config

arclux config ~/flask

Real output:

●  name: flask
│
●  frameworks: none detected
│
●  packageManager: uv
│
●  rootPath: /root/flask

Shows the auto-detected repository metadata (framework + package manager detection). Config file support is not built yet — detection is automatic.

Part 11 — The daemon (always-on analysis)

The daemon watches a repo and re-analyzes on every change:

arclux daemon <path>            # foreground
arclux daemon <path> --detach   # background process
arclux daemon <path> --status   # is it running?
arclux daemon <path> --health   # is the bridge actually responding?
arclux daemon <path> --stop     # stop it

Re-analysis is routed through a job scheduler (ported from the Linux kernel’s workqueue pattern): change bursts coalesce (N saves = 1 re-analysis), analyses never overlap, and the local HTTP+SSE bridge lets any tool subscribe:

• GET /analysis — current analysis
• GET /events — SSE stream (analysis, diagnostics events)
• GET /diagnostics — last diagnostics run

A minimal VS Code extension (apps/vscode-extension/) connects to a running daemon: Problems-panel diagnostics + status-bar module count.

Part 12 — Platform commands

Commands that work on a workspace model (the kernel process/service/job registry):

Command	What it does
ps	List processes registered with the ARCLUX kernel
run <service>	Start a named internal service (web, …)
exec <cmd> [args...]	Run a command through the sandboxed terminal layer (capability checks + session recording)
work <file> <newContentFile>	Apply a file’s new content via the Change Pipeline (ChangePlan → PatchSet → ChangeExecutor)
edit <file>	Show a file’s dependencies and consumers before you edit it
open <file>	Resolve a file to its module in the repository model
logs	View daemon or CLI logs
workspace <path>	Open a workspace session and print its snapshot
system	System state: workspaces + processes + services + jobs + health
language <file>	Parse a single file and print its exports/imports/calls
security <path>	Run the security-analysis pipeline (secrets, unsafe patterns, trust boundaries, attack surface)

Part 13 — The web dashboard

cd apps/web
pnpm run dev

The dashboard analyzes a remote repo URL (clone → analyze → visualize), then renders:

• Interactive dependency graph (SVG + d3-force physics layout)
• Graph variants: import / call / folder views, expand-on-demand
• Impact halo — hover a node, see who is affected
• Search across the repo (fuzzy filename + export-name matching)
• Detector findings and route/component resolution

Part 14 — CI / team workflow

Gate CI on the structural truth:

arclux verify .       # FAIL → block the PR
arclux diff main..HEAD .   # show what the PR changes architecturally

Team conventions:

• Keep PRs scoped to one package or one concern
• main is protected — everything goes through a PR
• Run arclux doctor before opening a PR; fix at least the error severity findings

Part 15 — Troubleshooting

• Ports shift / zombie node processes — before debugging weird web responses, check ps aux | grep node and confirm the port you’re hitting matches the Local: line of the dev server.
• Empty analysis on local dirs — local-path analysis never caches by design (stale results mid-edit would be worse). Re-run if results feel stale.
• Files skipped, not parsed — check the Scan: line. skipped (no parser) means the language isn’t supported yet, not that ARCLUX broke.
• Termux/Android — no /tmp; ARCLUX uses ~ for scratch space. The web app uses Webpack, not Turbopack.

---

That’s the whole tool. The shortest useful loop: analyze to look, impact before you change, doctor to find, verify to gate, daemon to stay current.