> ## Documentation Index > Fetch the complete documentation index at: https://arclux-os.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```bash theme={null} git clone https://github.com/GSF-001/ARCLUX.git cd ARCLUX pnpm install ``` Run the CLI with tsx (no build step needed): ```bash theme={null} npx tsx apps/cli/index.ts --help ``` Or add an alias so you don't type the prefix every time: ```bash theme={null} alias arclux="npx tsx $(pwd)/apps/cli/index.ts" ``` Verify it works: ```bash theme={null} arclux analyze . ``` ## Part 3 — Your first analysis Point ARCLUX at any repository on disk (it needs no network for local analysis): ```bash theme={null} 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: ```bash theme={null} 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?** ```bash theme={null} arclux impact [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`: ```bash theme={null} 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: ```bash theme={null} 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 ```bash theme={null} arclux diff [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": ```bash theme={null} 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 ```bash theme={null} 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: ```bash theme={null} arclux daemon # foreground arclux daemon --detach # background process arclux daemon --status # is it running? arclux daemon --health # is the bridge actually responding? arclux daemon --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 ` | Start a named internal service (`web`, ...) | | `exec [args...]` | Run a command through the sandboxed terminal layer (capability checks + session recording) | | `work ` | Apply a file's new content via the Change Pipeline (ChangePlan → PatchSet → ChangeExecutor) | | `edit ` | Show a file's dependencies and consumers before you edit it | | `open ` | Resolve a file to its module in the repository model | | `logs` | View daemon or CLI logs | | `workspace ` | Open a workspace session and print its snapshot | | `system` | System state: workspaces + processes + services + jobs + health | | `language ` | Parse a single file and print its exports/imports/calls | | `security ` | Run the security-analysis pipeline (secrets, unsafe patterns, trust boundaries, attack surface) | ## Part 13 — The web dashboard ```bash theme={null} 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: ```bash theme={null} 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.