Architect-Extractor

---

Visual Showcase (The "Star Capture")

Mira cómo Architect-Extractor transforma el código fuente complejo en diagramas de flujo y pseudocódigo comprensible.

1. Extracción de Lógica y Diagrama de Flujo

2. Análisis Detallado

3. Pseudocódigo de Negocio Final

---

Interactive Demo: Step-by-Step Workflow

Observe cómo Architect-Extractor opera de extremo a extremo, manteniendo sus repositorios limpios y su lógica organizada.

1. Búsqueda y Extracción Inteligente

Ejecución del comando ask utilizando el orquestador para analizar el código en tiempo real y generar el artefacto técnico.

2. Almacenamiento en Carpeta Madre Global

Architect-Extractor mantiene sus proyectos 100% limpios guardando la base de datos y los artefactos en un directorio centralizado (C:\.architect-extractor).

Escenario A: Organización del Primer Proyecto

Estructura Global

Resultado del Artefacto

Escenario B: Gestión Multi-repositorio La herramienta identifica automáticamente cada repositorio y separa su lógica de negocio de forma independiente.

Segunda Extracción

Resultado Independiente

---

Multi-language: English · Español

---

English

What is it?

Architect-Extractor is a CLI tool that reverse-engineers TypeScript/JavaScript repositories into business-logic artefacts — structured Markdown documents with flow diagrams (Mermaid.js) and pseudocode — powered by semantic search and an LLM.

Architecture

Repository (TS/JS)
       │
       ▼
FileScanner ──── ts-morph AST ──── Function signatures + body
       │
       ▼
Xenova/Transformers (all-MiniLM-L6-v2)
       │
       ▼
LanceDB vector index
       │
       ▼
User query → similarity search → top-K functions
       │
       ▼
Pipeline (AST chunk + LLM prompt)
       │
       ▼
LLM (Ollama / Gemini / Gemini CLI / MiniMax)
       │
       ▼
Markdown artefact (summary + mermaid + pseudocode)

Features

• Semantic search — Ask questions in natural language, not function names
• Local-first — Embedding model runs entirely offline (no GPU needed)
• Privacy-safe — Source code never leaves your machine with Ollama or Gemini CLI
• Multi-provider LLM — Ollama (local), Gemini CLI (free), Gemini API, MiniMax (Cloud)
• Incremental index — Only re-indexes files that changed (hash-based tracking)
• Global context storage — Artefacts saved automatically outside repos to keep repos clean (C:\.architect-extractor\<repo>)
• RAG-ready output — Artefactos ready to ingest

Installation

The NPM package is named cli-architect-extractor (or cli-architect-extractor), but the command it exposes is architect-extractor.

Option 1: Global Install (Recommended)

npm install -g .

# Then use the command anywhere:
architect-extractor --help

Option 2: Run via npx (Without installing) You must specify the package name when using npx:

npx --package cli-architect-extractor architect-extractor --help

Prerequisites & Tips

1. Ollama (recommended for full offline privacy):

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b

2. Gemini CLI (free, no API key needed):

npm install -g @google/gemini-cli
gemini --version

💡 Pro Tip for Gemini CLI: For 10x faster semantic searching, install Ripgrep (rg):

• Windows: winget install BurntSushi.ripgrep.MSVC
• Mac: brew install ripgrep
• Linux: sudo apt install ripgrep

3. Gemini API & MiniMax API: Requires API keys from their respective portals.

Step-by-Step Workflow

1. Initialize the project:

architect-extractor init

This generates an extractor.config.json file in your directory. If you ever need to start fresh or change providers completely, just delete this file:

• Windows: del extractor.config.json
• Mac/Linux: rm extractor.config.json

2. Configure your LLM Provider:

architect-extractor config

This interactive wizard lets you switch between Ollama, Gemini, MiniMax, or Gemini CLI.

⚠️ Important for Gemini CLI Users: When prompted for the Model Name, make sure to enter the exact string supported by your installed version (e.g., gemini-3-flash-preview or gemini-2.5-flash), otherwise you will get a ModelNotFoundError.

3. Index the repository:

architect-extractor index .

This parses all your TypeScript files, creates embeddings, and saves the LanceDB vector database globally.

4. Ask and Extract:

architect-extractor ask . "how does authentication work?"

The CLI will extract the top matching functions and generate .md files containing diagrams and pseudocode.

Global Context Storage (The "Mother Folder")

By default, Architect-Extractor keeps your repositories 100% clean. It calculates your project's name and stores all databases and generated artefacts in a global directory depending on your OS. For example, in Windows, it saves to:

C:\.architect-extractor\my-repo\
    ├── artifacts\            (Markdown files)
    ├── extractor.config.json (Copy)
    ├── summary.md
    └── .index\               (LanceDB vector index)

CLI Commands

Command	Description
init <path>	Generate config in target directory
extract <path>	Extract artefacts from a single file or directory
ask <path> <query>	Semantic search + extract artefacts
interactive <path>	Interactive shell mode
index <path>	Build/update the vector index
status <path>	Show index statistics
config	Open setup wizard to change providers / models

Contributing & License

See CONTRIBUTING.md. License: MIT

---

Español

¿Qué es?

Architect-Extractor es una CLI que transforma repositorios TypeScript/JavaScript en artefactos de lógica de negocio — documentos Markdown estructurados con diagramas de flujo (Mermaid.js) y pseudocódigo — impulsados por búsqueda semántica y un LLM.

Arquitectura

Repositorio (TS/JS)
       │
       ▼
FileScanner ──── ts-morph AST ──── Firmas + cuerpo de funciones
       │
       ▼
Xenova/Transformers (all-MiniLM-L6-v2)
       │
       ▼
Índice vectorial LanceDB
       │
       ▼
Consulta → búsqueda por similitud → top-K funciones
       │
       ▼
Pipeline (AST chunk + prompt LLM)
       │
       ▼
LLM (Ollama / Gemini CLI / Gemini API / MiniMax)
       │
       ▼
Artefacto Markdown (resumen + mermaid + pseudocódigo)

Características

• Búsqueda semántica — Pregunta en lenguaje natural, no por nombres de funciones
• Local-first — El modelo de embedding funciona 100% offline (sin GPU)
• Privacidad segura — El código fuente nunca sale de tu máquina con Ollama o Gemini CLI
• Multi-proveedor LLM — Ollama (local), Gemini CLI (gratis), Gemini API, MiniMax (Cloud)
• Índice incremental — Solo re-indexa archivos que cambiaron (tracking por hash)
• Carpeta Madre Global — Guarda los artefactos y la base de datos fuera de tu repo (C:\.architect-extractor\<repo>) para no ensuciar tu control de versiones.

Instalación

Opción 1: Instalación global (Recomendado)

npm install -g .

# Luego usa el comando en cualquier lugar:
architect-extractor --help

Opción 2: Usar npx (Sin instalar)

npx --package cli-architect-extractor architect-extractor --help

Requisitos previos y Tips

1. Ollama (recomendado para privacidad total offline):

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b

2. Gemini CLI (gratis, sin API key):

npm install -g @google/gemini-cli
gemini --version

💡 Tip Pro para Gemini CLI: Para que el análisis de código sea 10x más rápido, instala Ripgrep (rg):

• Windows: winget install BurntSushi.ripgrep.MSVC
• Mac: brew install ripgrep
• Linux: sudo apt install ripgrep

3. Gemini API y MiniMax API: Requieren obtener sus respectivas API keys oficiales.

Flujo de trabajo paso a paso

1. Inicializar el proyecto:

architect-extractor init

Esto genera el archivo extractor.config.json en tu carpeta actual. Si alguna vez te equivocas de configuración o quieres cambiar de proveedor limpiamente, puedes borrarlo:

• Windows: del extractor.config.json
• Mac/Linux: rm extractor.config.json

2. Configurar el Orquestador (LLM):

architect-extractor config

Este asistente interactivo te permite cambiar entre Ollama, Gemini, MiniMax o Gemini CLI.

⚠️ Importante para usuarios de Gemini CLI: Cuando te pida el nombre del modelo, asegúrate de escribir la cadena exacta que soporta tu terminal (por ejemplo, gemini-3-flash-preview o gemini-2.5-flash). De lo contrario, arrojará el error ModelNotFoundError.

3. Indexar el repositorio:

architect-extractor index .

Lee todos tus archivos TypeScript, crea los embeddings offline y construye la base de datos LanceDB.

4. Preguntar y Extraer:

architect-extractor ask . "¿cómo funciona la conexión a la base de datos?"

La CLI buscará las funciones más relevantes y generará archivos Markdown reales (.md) con diagramas Mermaid generados por la IA.

Contexto Global ("Carpeta Madre")

Para mantener tu entorno de trabajo 100% limpio, Architect-Extractor ya no guarda bases de datos dentro de tu proyecto local. La herramienta calcula el nombre de tu proyecto y guarda toda la información en un directorio global. Por ejemplo, en Windows se guarda en:

C:\.architect-extractor\mi-repositorio\
    ├── artifacts\            (Tus diagramas y Markdown)
    ├── extractor.config.json (Copia)
    ├── summary.md
    └── .index\               (Índice vectorial LanceDB)

Comandos CLI

Comando	Descripción
init <path>	Genera la configuración
extract <path>	Extrae artefactos de un archivo directo
ask <path> <query>	Búsqueda semántica + extracción automática
interactive <path>	Inicia el modo de terminal interactiva
index <path>	Construye o actualiza el índice vectorial LanceDB
status <path>	Ver estadísticas de qué se ha indexado
config	Abre el asistente de configuración para cambiar el LLM

Contribuir y Licencia

Ver CONTRIBUTING.md. Licencia: MIT