How Ranex Works (Atlas + Dependency Firewall)

This document explains the two main Ranex features in two layers:

• A plain-English explanation for non-technical stakeholders
• A developer explanation for people integrating Ranex into daily development, CI, or AI tooling

Ranex is local-first: it analyzes a project on your machine and stores project state inside your project directory.

Part 1: Plain-English explanation (non-technical)

Atlas (Code Intelligence)

Think of Atlas like a searchable map of your codebase.

• You point Atlas at a project folder.
• Atlas scans your Python files and builds a local "index" (like an internal table-of-contents).
• After that, you can ask questions like:
  • "Where is the create_user function?"
  • "Which files are affected if I change this module?"
  • "What endpoints exist in this API?"

Atlas helps teams and AI assistants avoid:

• wasting time hunting for code
• accidentally duplicating existing functionality
• making risky changes without knowing what will break

Atlas also includes additional features:

• FastAPI endpoint extraction and FastAPI-specific reports (only when endpoint artifacts are detected)
• Import graph (records imports as edges and exposes dependency queries)
• Call graph (records function-call edges and exposes call/impact queries)
• Span tools that return exact (file, start_line, end_line) locations

Atlas is not "AI that understands your business logic". It is structured code discovery.

Dependency Firewall (Import Safety)

Think of the Dependency Firewall like a security gate for dependencies.

It answers questions like:

• "Are we allowed to use this new library?"
• "Is this import dangerous?"
• "Did someone (or an AI) accidentally type a fake package name?"

It protects against three classes of real-world problems:

• Risky patterns (imports tied to high-risk behavior like shell execution)
• Typosquatting (a malicious package that looks like a popular one)
• Accidental/hallucinated dependencies (a package name that doesn't exist in your organization's allowed list)

The goal is not to block development. The goal is to ensure dependency changes are intentional and reviewable.

Part 2: Developer explanation

Where Ranex stores and reads project state

Ranex uses two "control planes" inside your project:

• .ranex/ (project-local Ranex configuration and databases)
• .ranexignore (project-root ignore file)

Project state files:

• .ranex/atlas.sqlite - Atlas index database
• .ranex/firewall.yaml - Dependency Firewall policy
• .ranex/fastapi_scaling.yaml - FastAPI scaling policy (optional)
• .ranex/config.toml - Ranex configuration (optional)

Atlas: what it does (developer)

This section explains Atlas features in terms of:

• How it works (what Atlas actually does on disk)
• Why it exists (what practical failure mode it prevents)

For CLI usage, see the CLI Reference. For config knobs, see the Configuration Reference.

1. Input

Atlas takes:

• A project root
• Your Python source files (files with extension .py)

It also respects ignores defined in .ranexignore and configuration settings.

2. Scanning process

When you run ranex atlas scan:

• Atlas walks your project directory
• Parses Python files using a Rust-based parser
• Extracts artifacts (functions, classes, methods, endpoints, etc.)
• Records relationships (imports, calls, dependencies)
• Stores everything in .ranex/atlas.sqlite

3. Search and queries

After scanning, you can:

• Search by name or feature tag
• Query dependencies and dependents
• Analyze impact of changes
• Detect cycles and duplicates
• Extract FastAPI-specific insights

Dependency Firewall: what it does (developer)

The Dependency Firewall validates imports against a policy file at .ranex/firewall.yaml.

Policy modes

• strict - Not-allowed packages are blocked
• audit_only - Violations are reported but not enforced
• disabled - Firewall is turned off

What it checks

• Is the import in the allowed packages list?
• Does it match a blocked pattern?
• Is it a potential typosquat?

Integration points

• CLI - ranex firewall check-import, analyze-file
• Python API - Firewall(project_root).check_import(...)
• MCP - Tools exposed to AI assistants
• CI - Run checks on changed files

Why local-first matters

Ranex is designed to work without cloud dependencies:

• Your code never leaves your machine
• No API keys or external services required
• Fast queries (no network latency)
• Works offline
• Full control over your data

Typical workflows

Daily development

1. Run ranex atlas scan after pulling changes
2. Search for relevant code before making changes
3. Check impact before refactoring
4. Validate new dependencies with firewall

CI/CD integration

1. Scan codebase in CI
2. Run firewall checks on changed files
3. Generate reports for code review
4. Block PRs with policy violations

AI-assisted development

1. Configure MCP server with RANEX_PROJECT_ROOT
2. AI assistant uses Atlas to search codebase
3. AI checks impact before suggesting changes
4. AI validates dependencies with firewall before adding imports