ArchRift

Architecture intelligence for NestJS applications. Analyze the system, enforce dependency boundaries, understand the blast radius of changes, and review architecture directly in pull requests.

ArchRift statically reads TypeScript syntax and produces a deterministic, source-linked architecture graph. It does not bootstrap the NestJS application, import project modules, install dependencies, or run repository scripts.

Quick start

Requires Node.js 20 or newer.

npx @archrift/cli analyze .
npx @archrift/cli inspect .

analyze writes architecture.json. inspect analyzes the project and opens a polished local viewer on 127.0.0.1; no account or hosted backend is involved.

To run the repository demo from source:

corepack enable
pnpm install
pnpm build
pnpm inspect:demo

What ArchRift understands

• NestJS modules, imports, controllers, providers, and exports.
• @Controller() routes using @Get, @Post, @Put, @Patch, @Delete, @Options, @Head, and @All.
• Constructor-injected dependencies.
• Class, existing-provider, and forwardRef references in module metadata.
• Common EventEmitter and Nest microservice publishing/consumption patterns when event names are static strings.
• Direct, transitive, and reverse dependencies.
• Strongly connected components for dependency-cycle detection.
• Deterministic snapshots, architecture diffs, and dependency blast radius.
• Declarative architecture rules with source-linked violations.
• GitHub pull-request reports without an external service.

The analyzer intentionally does not pretend to resolve arbitrary dynamic JavaScript. Computed module metadata, runtime-generated providers, dynamic event names, and dependencies hidden behind untyped tokens may be absent. Inferred relationships carry confidence metadata.

Interactive architecture viewer

npx @archrift/cli inspect .

The graph is the primary interface. It supports module and component layouts, pan and zoom, fit-to-screen, search, type filters, keyboard shortcuts, source locations, incoming and outgoing dependencies, cycle highlighting, and light and dark themes.

When a snapshot or rule configuration is present, switch between:

• Current architecture — the analyzed system and dependency direction.
• Changes — added and removed nodes, dependencies, endpoints, and events.
• Impact — direct and transitive dependents of changed components.
• Violations — forbidden relationships with rule and source context.

Use / to focus search and Escape to clear the active UI state.

Snapshots, diffs, and impact

Commit a normalized baseline:

npx @archrift/cli snapshot .
# writes .architecture/snapshot.json

After changing the application:

npx @archrift/cli diff .
npx @archrift/cli impact PaymentsService .

Snapshots contain no timestamps and are sorted before serialization. Repeated analysis of unchanged source produces byte-identical output. Blast radius follows static reverse dependencies and is described as potential architectural impact—not as a prediction of runtime failure.

Architecture rules

Create archrift.config.yml in the project root:

rules:
  - name: controllers-must-not-access-repositories
    from:
      type: controller
    disallow:
      type: repository

  - name: domain-must-not-import-infrastructure
    from:
      module: '*DomainModule'
    disallow:
      module: '*InfrastructureModule'
    relationships: [imports]
    severity: error
    blocking: true

Selectors accept type, name, and module; names and modules support * globs. A rule may be limited to relationship types such as imports, injects, or calls. Severity defaults to error, and error rules block by default. Unknown configuration fields are rejected.

npx @archrift/cli check .

Blocking violations exit with status 2, making the command suitable for any CI provider.

Pull-request architecture review

name: Architecture Review

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: archrift/archrift/github-action@v1
        with:
          project-path: .
          github-token: ${{ github.token }}

The action compares immutable base and head commits, writes a GitHub job summary, and updates one marked pull-request comment instead of creating a new comment for every push. Omit github-token or set comment: 'false' for summary-only operation. GitHub may make fork pull-request tokens read-only; the summary and blocking check still work when comment permission is unavailable.

Example report:

Architecture Review

Risk / Impact: MEDIUM
Changes: +2 dependencies, -1 dependency, +1 module
Affected components: 6
Violations: 1 (1 new)

New dependencies
OrdersService → FraudService
OrdersModule → FraudModule

Potential blast radius
OrdersModule, PaymentsModule, CheckoutModule, NotificationsModule

Blocking rule violations fail the check. Risk is explainable: blocking violations or new cycles are HIGH; non-blocking violations, five affected components, or five architecture changes are MEDIUM; smaller changes are LOW; and an unchanged graph is NONE.

For untrusted forks, use pull_request—not pull_request_target. The action archives commits into temporary directories, rejects paths and symbolic links that escape them, and never executes repository code.

CLI reference

Command	Purpose
archrift analyze [path]	Analyze a project and write deterministic JSON.
archrift snapshot [path]	Write .architecture/snapshot.json for version control.
archrift diff [path]	Compare the current graph with a baseline snapshot.
archrift impact <component> [path]	Show direct and transitive dependents.
archrift check [path]	Evaluate archrift.config.yml.
archrift inspect [path]	Open the local interactive viewer.

Run archrift <command> --help for command-specific options, including custom output, baseline, configuration, port, and JSON modes.

Compatibility

Component	Supported/tested
Node.js	20, 22, and 24
TypeScript	TypeScript 5 syntax through ts-morph
NestJS	Decorator patterns tested against NestJS 11; conventional metadata from earlier maintained NestJS versions is expected to analyze
Operating systems	Linux, macOS, and Windows-compatible Node.js paths; CI runs on Linux
GitHub Action runtime	Node.js 24

ArchRift does not require a successful NestJS build or installed application dependencies to perform syntax-based analysis. A valid tsconfig.json improves project file selection.

Repository architecture

@archrift/analyzer-nestjs ─→ @archrift/analyzer-typescript ─→ @archrift/core
             │                                               ↑
             └───────────────────────────────────────────────┘

@archrift/rules ──────────→ @archrift/core
@archrift/reporter ───────→ @archrift/rules + @archrift/core
@archrift/viewer ─────────→ @archrift/core
@archrift/cli ────────────→ analyzers + rules + viewer
github-action ────────────→ analyzer + reporter + rules

Framework semantics terminate at the common architecture graph. Diff, impact, rules, reporting, and visualization remain independently testable and framework-neutral.

Development

pnpm install
pnpm check

pnpm check verifies formatting, linting, strict type checking, unit and integration tests, and all build artifacts. Analyzer fixtures assert exact semantic graph relationships. The GitHub Action integration test creates real base and head commits locally and verifies blocking behavior.

pnpm prepare:demo deterministically recreates the historical demo baseline used by the Changes and Impact views.

See CONTRIBUTING.md for contribution conventions and SECURITY.md for private vulnerability reporting.

Roadmap

• Broaden coverage of static NestJS provider tokens and common dynamic-module patterns.
• Add performance fixtures and incremental analysis for larger monorepos.
• Improve diff-focused viewer layouts and screenshot automation.
• Consider additional framework adapters only after the NestJS analyzer and common graph contracts are stable.

License

MIT © ArchRift contributors.