README

Generate AI-ready documentation and project maps for software projects.

AI Project Scanner helps developers and AI assistants understand existing codebases before making changes.

Instead of asking an AI assistant to explore an unfamiliar project from scratch, AI Project Scanner generates structured project knowledge that can be consumed in minutes.

🚧 Current Status

AI Project Scanner is actively under development.

Current Stable Release

v0.3.5

Current Release

Spring Boot Route Intelligence

Spring Boot framework detection and REST API route extraction are now supported, including controller prefixes, route handlers, HTTP methods, multiple paths, and route metadata.

✨ Features

Recursive project scanning
AI-ready project context generation
Project tree generation
Machine-readable project map
Universal project structure detection
Framework detection
Multi-framework detection
API route extraction
Route statistics
Route quality analysis
Route grouping
Route graph generation
Framework-specific route extractors
.gitignore support
.aiscannerignore support
Intelligent ignore engine with directory pruning
Command-line interface
Composer package installation
PHAR distribution

🧠 Project Vision

AI Project Scanner is evolving beyond documentation generation.

The long-term goal is to build a:

Software Knowledge Engine

that helps both developers and AI assistants understand software projects quickly.

The planned knowledge pipeline is:

Project Files
      ↓
Filesystem Scanner
      ↓
Framework Intelligence
      ↓
Route Intelligence
      ↓
Component Intelligence
      ↓
Relationship Intelligence
      ↓
Business / Feature Intelligence
      ↓
AI-ready Software Knowledge

Each release should make the scanner understand software a little better.

🔍 Framework Detection

AI Project Scanner can detect multiple frameworks and technologies within the same project.

Current framework support includes:

CodeIgniter 4
Laravel
Node.js
Express.js
Spring Boot
React
Next.js
Vue.js

The scanner is designed to work with projects containing multiple frameworks or technologies rather than assuming that a project has only one framework.

🛣️ API Route Extraction

AI Project Scanner currently supports API route extraction for:

CodeIgniter 4
Laravel
Express.js
Spring Boot

Route information is normalized into a framework-independent representation so that generated documentation can describe routes consistently across different ecosystems.

Spring Boot

Spring Boot route extraction supports common Spring MVC controller annotations:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public List<User> index() {
    }

    @GetMapping("/{id}")
    public User details() {
    }
}

The scanner can detect:

Controller names
Class-level route prefixes
HTTP methods
Route paths
Multiple route paths
Multiple HTTP methods
Handler method names
Source files
Route groups

Spring Boot route extraction currently uses source-based analysis rather than a complete Java AST parser. Advanced Java and Spring annotation resolution may be added in future releases.

📊 Route Intelligence

AI Project Scanner generates route documentation including:

API_ROUTES.md
ROUTE_GRAPH.md

Route information is also included in:

SCAN_REPORT.md

Route intelligence includes:

Total route counts
Routes grouped by framework
Routes grouped by HTTP method
Controller/router grouping
Mounted prefixes
Source files
Handler methods
Middleware information where supported
Duplicate route detection
Route quality statistics

📦 Installation

Composer

Install the package:

composer require mohammedsameer/ai-project-scanner

Run:

php vendor/bin/ai-scan scan .

PHAR

Download the latest PHAR from GitHub Releases.

Run:

php ai-project-scanner.phar scan .

🚀 Usage

Scan the Current Project

php vendor/bin/ai-scan scan .

Scan Another Project

php vendor/bin/ai-scan scan /path/to/project

Scan a Laravel Project

php vendor/bin/ai-scan scan ../my-laravel-app

Scan an Express Project

php vendor/bin/ai-scan scan ../my-express-app

Scan a Spring Boot Project

php vendor/bin/ai-scan scan ../spring-boot-api

📁 Generated AI Documentation

The scanner generates an ai/ directory containing structured project knowledge:

ai/
├── PROJECT_CONTEXT.md
├── PROJECT_STRUCTURE.md
├── API_ROUTES.md
├── ROUTE_GRAPH.md
├── PROJECT_TREE.md
├── PROJECT_MAP.json
├── SCAN_REPORT.md
└── FRAMEWORKS.md

🤖 Which File Should AI Read First?

Start with:

ai/PROJECT_CONTEXT.md

Then use:

PROJECT_STRUCTURE.md
    ↓
API_ROUTES.md
    ↓
PROJECT_TREE.md
    ↓
PROJECT_MAP.json
    ↓
FRAMEWORKS.md
    ↓
SCAN_REPORT.md

PROJECT_CONTEXT.md provides the initial project understanding and points AI assistants toward the most relevant project information.

📚 Generated Files

PROJECT_CONTEXT.md

Provides high-level AI onboarding information.

Includes:

Project name
Detected frameworks
Important directories
Important files
AI guidance

PROJECT_STRUCTURE.md

Provides a categorized view of the project structure.

Includes categories such as:

Backend entry points
Frontend entry points
Route files
Controllers
Services
Models/entities
Database files
Configuration files
Tests
Documentation
Deployment files

API_ROUTES.md

Provides framework-independent API route documentation.

Example:

Method	URI	Handler
GET	/api/users	index
GET	/api/users/{id}	details
POST	/api/users	save

ROUTE_GRAPH.md

Provides a readable routing overview grouped by controller or router.

PROJECT_TREE.md

Provides a hierarchical view of the scanned project.

PROJECT_MAP.json

Provides machine-readable project metadata including:

Files
Directories
File extensions
File sizes
Ignored paths
Scan errors

SCAN_REPORT.md

Provides project analysis statistics including:

File counts
Directory counts
File extensions
Ignored paths
Scan errors
Route statistics
Route quality information

FRAMEWORKS.md

Provides detected framework and technology information.

🚫 Ignore Files

AI Project Scanner respects:

.gitignore
.aiscannerignore

Default ignored locations include:

.git/
vendor/
node_modules/
build/
dist/
coverage/
system/
ai/

Ignored directories are pruned during scanning so unnecessary files are not traversed.

💡 Why AI Project Scanner Exists

AI assistants are powerful, but an unfamiliar codebase still requires exploration.

Before making a change, an AI assistant often needs to discover:

Project structure
Frameworks
Entry points
Controllers
Routes
Important files
Configuration
Tests
Generated files
Files that should not be modified

AI Project Scanner creates structured project knowledge so AI assistants can understand a codebase faster and make safer suggestions.

🗺️ Roadmap

Completed

v0.1.x

Project tree generation
JSON project map generation
Scan report generation
CLI support
Composer package

v0.2.x

Framework detection
Framework documentation
Project context generation
Universal project structure detection
Project structure documentation

v0.3.x

PHAR build support
CodeIgniter 4 route extraction
Laravel route extraction
Express.js route extraction
Spring Boot route extraction
API route documentation
Route statistics
Route grouping
Route graph generation
Route source-file detection
Route prefix detection
Middleware detection
Route quality analysis
Framework-specific route extractor architecture

🔭 Next: Component Intelligence

The next knowledge layer is Component Intelligence.

The goal is to allow AI Project Scanner to recognize application components rather than only project files and routes.

Initial component intelligence will focus on:

Component definitions
Component discovery
Framework-aware component classification
Controllers
Services
Repositories
Models/entities
Configurations
Framework-specific components

The component model should remain framework-independent while allowing individual frameworks to provide their own extraction strategies.

🌱 Future

Future knowledge layers may include:

Component relationships
Dependency graph generation
Database relationship detection
Business module discovery
AI prompt packs
Deeper Spring Boot analysis
FastAPI route extraction
Django route extraction
Go HTTP router extraction
NPM / NPX wrapper
Docker image
VS Code / Cursor / Windsurf integrations

🧭 Architecture Philosophy

AI Project Scanner follows a simple architectural principle:

Scan once. Understand progressively. Generate reusable knowledge.

The filesystem scanner discovers the project.

Detectors interpret the discovered files.

Framework-specific extractors provide specialized intelligence.

Framework-independent DTOs carry structured knowledge.

Generators transform that knowledge into documentation.

This keeps the scanner extensible without coupling the filesystem layer to framework-specific behavior.

🧪 Development

Install dependencies:

composer install

Run the complete test suite:

composer test

Or:

vendor/bin/phpunit

The project currently uses PHPUnit for regression testing.

🤝 Contributing

Contributions are welcome.

Before contributing, please review:

CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md

Recommended workflow:

git checkout main
git pull
git checkout -b feature/your-feature-name

Make focused changes, add tests where appropriate, and submit a Pull Request.

🔐 Security

Please do not publicly disclose security vulnerabilities through GitHub Issues.

See:

SECURITY.md

for responsible disclosure information.

📄 License

AI Project Scanner is released under the MIT License.