# dyfcheng/projanitor architecture

> Architecture diagram of the GitHub repository dyfcheng/projanitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dyfcheng/projanitor
- Repository: https://github.com/dyfcheng/projanitor

## Overview

##### Project Type and Purpose
- projanitor is a lightweight, command-line Python auditing tool for software projects (especially embedded/CMake environments). It is an open-source utility, not a multi‐service application. Its core function is to scan a directory tree, detect project root, catalog relevant source files, analyze references, and emit a summary report of duplicates, orphans, and missing files.

##### File Structure Analysis
- Top-level:
- CONTRIBUTING.md, LICENSE, README.md – documentation
- src/projanitor.py – the single Python script containing all logic
- No separate “frontend” or “backend” folders; projanitor is a self-contained CLI tool.
- No external configuration directories or microservices.
- Key external inputs: command-line arguments (argparse), filesystem (os, pathlib).
- Key outputs: console report (stdout).

##### README Insights
- Describes:
- Marker file detection (e.g., CMakeLists.txt, LICENSE) → project root locator
- File scanning (extensions, excluded dirs) → file auditor
- Analysis phases: duplicates, orphans, missing references
- Configurability via CLI flags
- Reporting/verbose logging

a. CLI Interface
- Module: ArgumentParser
- Inputs: --extensions, --exclude-dirs, --marker-files, --verbose
b. Project Root Detector
- Logic: recursively walk up until a marker file is found
c. File Scanner
- Traverses filesystem (os.walk)
- Filters by extensions and excluded directories
- Builds an indexed list of files of interest
d. Reference Parser & Analyzer
- Subcomponents:
- C Source Analyzer (parses #include “…”)
- Python Import Analyzer (parses import statements)
- CMake Reference Analyzer (parses file references in CMakeLists.txt)
- Data structures: dictionaries or collections.Counter for tracking references
e. Analysis Engine
- Duplicate Finder (group by basename)
- Orphan Detector (files never referenced)
- Missing Reference Detector (references without corresponding files)
f. Report Generator
- Formats and prints summary, statistics, warnings, errors
- Honors verbose flag for extra details

##### Relationships and Data Flow
- User invokes CLI → ArgumentParser → feeds parameters into Controller
- Controller → calls Root Detector → returns project root path
- Controller → calls File Scanner on root → returns file inventory
- File inventory → fed into Reference Parser → returns reference map
- Reference map & file inventory → fed into Analysis Engine → returns findings
- Findings → passed to Report Generator → console output

##### Architectural Patterns and Principles
- Single-pass directory traversal for efficiency
- Modular functional design within a single script
- Separation of concerns: detection, scanning, parsing, analysis, reporting
- No external dependencies; uses standard library

- Distinguish external systems (filesystem) vs internal modules
- Which standard libraries are leveraged in each module
- Five major components plus CLI entry point

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    CLI["CLI Interface\n(ArgumentParser)"]:::cli
    RootDetector["Project Root Detector"]:::cli
    FileScanner["File Scanner"]:::io
    ReferenceParser["Reference Parser & Analyzer"]:::analysis
    AnalysisEngine["Analysis Engine"]:::analysis
    ReportGenerator["Report Generator"]:::io
    Filesystem[/Filesystem/]:::external

    %% Data Flow
    CLI -->|"args"| RootDetector
    RootDetector -->|"root path"| FileScanner
    FileScanner -->|"file list"| ReferenceParser
    ReferenceParser -->|"reference map"| AnalysisEngine
    AnalysisEngine -->|"findings"| ReportGenerator

    Filesystem -->|"fs read"| FileScanner
    Filesystem -->|"fs read"| ReferenceParser

    %% Click Events
    click CLI "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"
    click RootDetector "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"
    click FileScanner "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"
    click ReferenceParser "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"
    click AnalysisEngine "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"
    click ReportGenerator "https://github.com/dyfcheng/projanitor/blob/main/src/projanitor.py"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef io fill:#90EE90,stroke:#000,stroke-width:1px
    classDef analysis fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
