> ## Documentation Index
> Fetch the complete documentation index at: https://reikon.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Is the code in a structure worth keeping? Name your layers and Reikon flags every import that crosses a boundary.

# Tour: Architecture

**Architecture is the wheel's stage for judging the form** — is the code in a structure worth
keeping? Most tools show you the dependency graph and leave you to read it. Reikon turns it into
a decision: you state the architecture you *intend*, and it flags every place the code drifts
from it. Press `5` to jump here.

## Layers — name them, then let drift surface itself

A **layer** is a set of path globs with a name. You declare which other layers each one is
allowed to import; anything else internal becomes a violation. Two shapes this captures:

* **Strict stacks** — `api → service → data`: `api` may import `service`, `service` may import
  `data`, and `data` reaching back up is a violation.
* **Forbidden siblings** — `main` and `renderer` both sit over `shared`, but must never import
  *each other*. The allow-list expresses that directly (`main` may import `shared`; `renderer`
  may import `shared`; neither lists the other).

A layer that lists nothing is *foundational* — it may import external packages but no other
internal layer. Layers are saved to `.reikon/config.json`, committed and shared with your team.

## Don't start from a blank form

Naming an ideal architecture from scratch is the hardest way to begin. So Reikon doesn't ask you
to. Hit **Suggest my layers** and it reads your directory structure and imports and proposes a
starting set — one layer per top directory, with each layer's allowances pre-ticked to mirror
what your code *actually imports today*. Accepting it as-is reports zero violations (it just
describes your current structure), so the real work is the opposite of authoring: **untick the
arrows that shouldn't be allowed**, and each one becomes a violation to fix. Prune, don't compose.

From that seed you have three more ways to shape it, all in the same form:

* **Start from a preset** — if Reikon recognizes your stack (Electron, Next.js, a layered
  API), one click drops the known-correct topology onto your real directories.
* **Tidy into a strict stack** — orders the layers foundation-last and allows only downward
  imports; anything circular gets flagged as a cycle you can't cleanly layer.
* **Draft with AI** — when an AI CLI is connected, your agent proposes named layers from the
  same structure and import data, merging and naming them in ways deterministic seeding can't.

Aliased imports count too: if your `tsconfig.json` declares path aliases (`@shared/*`), Reikon
resolves them, so `@shared/x` is understood as an internal dependency, not an external package.

## Violations are findings, not lint

Each violation is an aggregated `from → to` edge — the disallowed direction, how many imports
take it, and example offending files you can click straight to. It's the same finding shape as
the rest of the wheel: deterministic, computed over the import graph you already have, and
**dispatchable** — your agent can pull the list via the `get_arch_violations` MCP tool and fix
the dependency direction in its own environment; you review the change in Review. Reikon also
surfaces any **dependency cycles** between your top-level packages, a structural smell even when
they don't cross a named layer.

When every import respects your layers and there are no cycles, the tab reads *Architecture
holds* — the structure is what you said it should be. What you learn here feeds new Goals, and
the wheel closes.

## The ratchet — decide crossings as they appear

You don't have to get the layers perfect up front. As your code changes, a **new** boundary
crossing that isn't in your layers yet shows up as a decision, not a verdict: *is `renderer → main`
allowed?* **Allow** it and Reikon adds it to that layer's imports — your architecture definition
*grows from the decision*. **Keep as violation** and it becomes a tracked item to fix, and won't
prompt you again. So the structure accretes from real judgments over time instead of being authored
in one sitting — and every crossing on screen is either allowed on purpose or flagged on purpose,
never an accident nobody looked at. (Changed your mind later? A tracked violation can still be
promoted to *Allow instead*.)

## When it can't see everything, it says so

Reikon resolves relative imports and `tsconfig` path aliases. It can't yet follow imports that
go through a **workspace package name** (`@org/shared` in a monorepo) or a webpack/Vite alias —
those look like external packages. If your repo uses them, Reikon won't quietly show a green
"Architecture holds" it can't back up: it flags how many of your own imports it couldn't check
and reads *"No violations in the imports we could resolve"* instead of a full all-clear. Adding
`tsconfig` `paths` for your aliases closes the gap. (Same rule as everywhere else in Reikon: it
leaves a signal blank rather than fake a clean number it didn't earn.)

And if the repo isn't JavaScript/TypeScript at all — layer checks currently only read JS/TS
imports — Architecture says *"This repo wasn't checked"* rather than a green "holds" it can't
stand behind. Layer analysis for other languages is a later, demand-driven addition, not something
faked in the meantime.