> ## 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.

# Architecture

> Boundary map: core, extension points, what's safe to touch

Not an implementation list — a **boundary map**. Read this before adding anything new, especially if you're extending ARCLUX with a new capability (search, intelligence layers, RAG), not just fixing an existing stub.

> [!WARNING]
>
> **CORE and CORE-ADJACENT layers**: changes here need a `decisions.md` entry first. These are the packages everything else depends on.

> [!TIP]
>
> **EXTENSION POINTS**: safe to add to without discussion. New parsers, detectors, cache strategies, and framework rules go here.

## Layers

> [accordion] packages/ — CORE
>
> Changes need a `decisions.md` entry first.
>
> * **`engine/`** — the orchestrator (`analyzeRepository()`). Everything else depends on this.
> * **`repository/`** — the domain model (`Repository`, `ModuleInfo`).
> * **`shared/`** — `types.ts` is the shape of everything. Adding fields is fine; changing or removing needs a `decisions.md` entry.

> [accordion] packages/ — CORE-ADJACENT
>
> Care needed, but not a full stop.
>
> * **`indexer/`** — resolves imports into a `Repository`. New resolver passes (routes, components, etc) are fine to add. Changing `buildIndex.ts`'s pass order needs care — later passes depend on earlier ones.
> * **`graph/`** — turns a `Repository` into a `DependencyGraph`. New graph variants (`buildCallGraph`, `buildImportGraph`) are extensions. Changing `buildDependencyGraph.ts`'s core shape is not.
> * **`impact/`** — consumer/dependent tracing.

> [accordion] packages/ — EXTENSION POINTS
>
> Safe to add to without discussion.
>
> * **`parser/`** — new language support, one subfolder per language, implements `LanguageParser`.
> * **`detectors/`** — each detector is independent, takes a `Repository`, returns findings. See `detectAmbiguousSymbolResolution.ts` for the pattern.
> * **`cache/`** — additive by nature. A cache miss should always fall back to the uncached path.
> * **`rules/`** — one subfolder per framework, independent convention checks.

> [accordion] packages/ — MOSTLY STUB
>
> * **`search/`** — see `progres/status-*.md` for current state before assuming this is the place to add semantic search, embeddings, or RAG. See [Where intelligence layers go](#where-intelligence-ai-layers-go) below.

> [accordion] packages/ — FOUNDATION, NOT WIRED IN YET
>
> * **`watcher/`**, **`incremental/`** — see `decisions.md`. Don't build on top of these until they're actually connected to `engine/pipeline.ts`.

> [accordion] apps/ — SURFACES
>
> Consume `packages/`, no business logic here.
>
> * **`cli/`** — consumes `engine/`.
> * **`web/`** — consumes `engine/` via API routes. Graph rendering (SVG/d3-force) lives here, not in `packages/graph/`.

## Where intelligence & AI layers go

ARCLUX's job is building an accurate **structural** model of a codebase: parse index graph impact detect. It is deliberately **not** trying to be a semantic search engine, a RAG system, an agent-facing MCP server, or an embeddings/reranking pipeline — those are legitimate problems, but they consume a structural model, they don't belong inside one.

> [!NOTE]
>
> Adding semantic search, graph RAG, agent tool-calling, embeddings, LSP bridging, or self-healing behavior? It belongs in a **new top-level package** (e.g. `packages/intelligence/`), consuming `DependencyGraph`/`Repository`/`AnalyzeRepositoryResult` as inputs — not woven into `graph/`, `detectors/`, or `engine/`. Treat ARCLUX the way you'd treat a library you don't maintain: depend on its stable outputs, don't reach into its internals.

This boundary exists on purpose, based on comparing notes with a collaborator (ManSio) who maintains a more elaborate codebase-intelligence system (graph RAG, agentic search, embeddings, LSP bridge, sandboxing, 1000+ tests). That project is a good example of what a **consumer** built on top of a structural model like ARCLUX's could look like — not a template for what ARCLUX's own core should become.

## Definition of "done" for anything non-trivial

Not done until all five:

1. **Implemented** — the code exists and typechecks
2. **Tested** — verified against a real fixture or repo, not just `tsc --noEmit` (see TOOLING.md's verification standard)
3. **Integrated** — actually called from somewhere real (`engine/pipeline.ts`, a detector registry, an API route) — see `progres/bugs.md`'s manifest-parser and cache entries for what "implemented but never wired in" costs if skipped
4. **Verified** — for anything touching `apps/web`, confirmed visually in-browser, not just assumed from code review
5. **Documented** — a `progres/*.md` entry exists (status, decision, or bug depending on what it is) — see TOOLING.md section 1

## Changing this file

This file describes **boundaries**, not the current implementation state (that's what `progres/status-*.md` is for) and not package-by-package descriptions (that's `packages/README.md`). If a layer's boundary genuinely needs to move — not just "someone wants an exception" — log the reasoning in `decisions.md` first, then update this file to match.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.