🧬 Project DNA

Understand any codebase in under 60 seconds.

Project DNA is a premium, high-performance developer tool that scans any software codebase and produces a beautiful, interactive, single-page HTML report summarizing its architecture, stats, health metrics, complexity hotspots, and dependencies.

---

📸 Dashboard Preview

+-----------------------------------------------------------------+
|  🧬 PROJECT DNA                                 [ LIGHT / DARK ]|
|  Scanned: 2026-07-12 12:50:00 • Fingerprint: D3FA-7A2B-91CE|
+-----------------------------------------------------------------+
|                                                                 |
|   [ Health: 94% ]        [ Architecture: 88% ]    [ Maintain: 92%]|
|      Excellent                  Good                 Excellent  |
|                                                                 |
|  +---------------------------+   +----------------------------+ |
|  | 📊 Statistics             |   | 💻 Language Distribution   | |
|  | - Total Files: 248        |   | - Python: 68.4%            | |
|  | - Total Folders: 37       |   | - JavaScript: 22.1%        | |
|  | - LOC: 24,800             |   | - TypeScript: 9.5%         | |
|  +---------------------------+   +----------------------------+ |
|                                                                 |
|  +------------------------------------------------------------+ |
|  | 🕸️ Interactive Dependency Graph (Vis.js Canvas)             | |
|  |  ( )--->( )--->( )                                         | |
|  |    \     ^                                                 | |
|  |     v   /                                                  | |
|  |      ( )                                                   | |
|  +------------------------------------------------------------+ |
+-----------------------------------------------------------------+

(Interactive Vis.js graph rendering, file search exploration tree, and live ApexCharts can be experienced directly in ProjectDNA_Report.html)

---

✨ Features

• ⚡ High Performance: Multithreaded file scanning scales to 10,000+ files without UI freezes.
• 🎨 Glassmorphism UI: Beautiful static HTML dashboard with clean animations, dark/light theme switcher, and soft glowing card layouts.
• 🕸️ Interactive Graphs: Complete visual dependency graph (using Vis.js Network) with zooming, node-dragging, and highlight capabilities.
• 📉 ApexCharts Integration: Vibrant interactive charts for language breakdowns, directory file volumes, and historical Git commit timelines.
• 🔍 File Explorer & Viewer: Client-side code browser with live file search and multi-language syntax highlighting (using Prism.js).
• 🧩 Architecture Detection: Classifies system layers (Controllers, Models, Services, Components, Tests) automatically.
• ⚠️ AI Heuristic Engine: Highlights codebase hotspots, circular dependencies, clone copies, dead assets, and provides actionable code remedies.
• 📦 Multi-format Exports: Generate HTML, JSON data feeds, CSV stats sheets, and Markdown summary files.

---

🏗️ Architecture

graph TD
    CLI[CLI Main Controller] --> Scanner[Multithreaded Scanner]
    Scanner --> AnalyzerSuite[Analyzer Pipeline]
    
    subgraph AnalyzerSuite [Analysis Engine]
        LA[Language Analyzer]
        GA[Git History Analyzer]
        DA[Dependency Network Analyzer]
        CA[Complexity Estimator]
        DPA[Duplicate & Clone Finder]
        EA[Empty Files & Unused Assets]
        COA[Config Signature Identifier]
        RA[README Quality Reviewer]
    end
    
    AnalyzerSuite --> RuleEngine[AI Rule Heuristics Engine]
    RuleEngine --> ReportGenerator[Report Writer]
    
    ReportGenerator --> HTML[Interactive HTML Dashboard]
    ReportGenerator --> JSON[Structured Data JSON]
    ReportGenerator --> CSV[Metrics Table CSV]
    ReportGenerator --> MD[Summary Document Markdown]

Loading

---

🚀 Installation

Project DNA runs locally without any web backends or external servers.

1. Clone the project

git clone https://github.com/allan-abraham/project-dna.git
cd project-dna

2. Install dependencies

pip install -r requirements.txt

3. Install in development mode (optional, adds dna CLI executable)

pip install -e .

---

💻 CLI Commands

Run Project DNA from your console:

🔍 Full Analysis & Open Report

Scans the project folder, generates ProjectDNA_Report.html, and opens it immediately in the browser:

python -m project_dna analyze <project-folder>

If dna is installed as a script:

dna analyze <project-folder>

📊 Quick Terminal Stats

Scans and prints a text summary table directly in the console:

dna stats <project-folder>

💾 Bulk Export Data

Generates HTML, JSON, CSV, and Markdown summaries simultaneously:

dna export <project-folder>

🔑 Print Project Fingerprint

Computes and prints only the 12-char SHA-256 fingerprint (ideal for CI/CD checks):

dna fingerprint <project-folder>

---

🛠️ Heuristic AI Rule Examples

The analysis engine highlights structure weaknesses and recommends code remedies:

• Circular Dependencies: Refactor import loops using Dependency Inversion.
• Large Methods: split functions exceeding 120 lines into focused helper units.
• Unused Assets: Remove fonts/images not imported or mentioned in the source code.
• Root Clutter: Move loose code files from root into a structured source directory.

---

🗺️ Roadmap

• Add cyclomatic complexity calculation via AST tree.
• Support custom regex configuration rules via dna.config.json.
• Implement incremental scanning for ultra-fast delta analyses.
• Slack & GitHub Actions export integration.

---

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your Changes (git commit -m 'Add some AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.