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.

Getting Started

Reference

MMO & Blueprint

Progress Detail

Codebase Map

Release

Complete Tutorial

ARCLUX Complete Tutorial

Part 1 — What ARCLUX is

Part 2 — Install & setup

Part 3 — Your first analysis

Part 4 — Working with the graph

Part 5 — Impact analysis

Part 6 — Doctor: 20 detectors

Part 7 — Verify: the CI gate

Part 8 — Diff: architectural change between refs

Part 9 — Diagnose

Part 10 — Config

Part 11 — The daemon (always-on analysis)

Part 12 — Platform commands

Part 13 — The web dashboard

Part 14 — CI / team workflow

Part 15 — Troubleshooting

​ARCLUX Complete Tutorial

​Part 1 — What ARCLUX is

​Part 2 — Install & setup

​Part 3 — Your first analysis

​Part 4 — Working with the graph

​Part 5 — Impact analysis

​Part 6 — Doctor: 20 detectors

​Part 7 — Verify: the CI gate

​Part 8 — Diff: architectural change between refs

​Part 9 — Diagnose

​Part 10 — Config

​Part 11 — The daemon (always-on analysis)

​Part 12 — Platform commands

​Part 13 — The web dashboard

​Part 14 — CI / team workflow

​Part 15 — Troubleshooting

ARCLUX Complete Tutorial

Part 1 — What ARCLUX is

Part 2 — Install & setup

Part 3 — Your first analysis

Part 4 — Working with the graph

Part 5 — Impact analysis

Part 6 — Doctor: 20 detectors

Part 7 — Verify: the CI gate

Part 8 — Diff: architectural change between refs

Part 9 — Diagnose

Part 10 — Config

Part 11 — The daemon (always-on analysis)

Part 12 — Platform commands

Part 13 — The web dashboard

Part 14 — CI / team workflow

Part 15 — Troubleshooting