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

<Tip>
  **EXTENSION POINTS**: safe to add to without discussion. New parsers, detectors, cache strategies, and framework rules go here.
</Tip>

## Layers

<AccordionGroup>
  <Accordion title="packages/ — CORE" icon="triangle-exclamation">
    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>

  <Accordion title="packages/ — CORE-ADJACENT" icon="triangle-exclamation">
    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>

  <Accordion title="packages/ — EXTENSION POINTS" icon="circle-plus">
    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>

  <Accordion title="packages/ — MOSTLY STUB" icon="hourglass-half">
    * **`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>

  <Accordion title="packages/ — FOUNDATION, NOT WIRED IN YET" icon="plug-circle-xmark">
    * **`watcher/`**, **`incremental/`** — see `decisions.md`. Don't build on top of these until they're actually connected to `engine/pipeline.ts`.
  </Accordion>

  <Accordion title="apps/ — SURFACES" icon="window-restore">
    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/`.
  </Accordion>
</AccordionGroup>

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

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.