{"id":31807869,"url":"https://github.com/leondavi/erlviz","last_synced_at":"2026-05-18T19:02:38.973Z","repository":{"id":311227192,"uuid":"1042776019","full_name":"leondavi/ErlViz","owner":"leondavi","description":"A visualization tool for Erlang OTP that scan the code of OTP behaviors and derives their connections creating a graph","archived":false,"fork":false,"pushed_at":"2025-08-22T21:38:34.000Z","size":1524,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-22T23:59:14.426Z","etag":null,"topics":["automation","documentation","erlang","python","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leondavi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T14:56:58.000Z","updated_at":"2025-08-22T21:38:37.000Z","dependencies_parsed_at":"2025-08-22T23:59:19.274Z","dependency_job_id":"419a9599-0b86-4828-b8d1-628e845ed184","html_url":"https://github.com/leondavi/ErlViz","commit_stats":null,"previous_names":["leondavi/erlviz"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leondavi/ErlViz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leondavi%2FErlViz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leondavi%2FErlViz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leondavi%2FErlViz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leondavi%2FErlViz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leondavi","download_url":"https://codeload.github.com/leondavi/ErlViz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leondavi%2FErlViz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006244,"owners_count":26084061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","documentation","erlang","python","visualization"],"created_at":"2025-10-11T04:38:25.662Z","updated_at":"2025-10-11T04:38:30.065Z","avatar_url":"https://github.com/leondavi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ErlViz - Erlang Project Analyzer and Visualizer\n\nErlViz is a comprehensive Python-based tool that analyzes Erlang/OTP projects to generate dependency graphs, communication diagrams, and documentation. Providing deep insights into OTP behaviors, module dependencies, and communication patterns.\n\n## Features\n\n### 🔍 **Deep Analysis**\n- **OTP Behavior Detection**: Automatically identifies `gen_server`, `gen_statem`, `supervisor`, `application`, and custom behaviors\n- **Module Dependencies**: Maps internal and external dependencies between modules\n- **Communication Patterns**: Analyzes message flows and communication patterns\n- **NIF Analysis**: Identifies Native Implemented Functions and their C/C++ implementations\n\n### 📊 **Rich Visualizations**\n- **Dependency Graphs**: Module dependency relationships with clustering by behavior type\n- **Communication Diagrams**: Visual representation of message flows and patterns\n- **Behavior Hierarchy**: OTP supervision trees and behavior implementations\n- **NIF Integration Maps**: Erlang-to-native code interfaces\n\n### 📚 **Documentation Generation**\n- **Module Documentation**: Extracted from code comments and function signatures\n- **API Reference**: Comprehensive function documentation\n- **Behavior Analysis**: Detailed OTP behavior usage patterns\n- **Architecture Overview**: High-level project structure analysis\n\n### 🌐 **Flexible Input**\n- **Local Repositories**: Analyze local Erlang projects\n- **GitHub Integration**: Direct analysis from GitHub URLs\n- **Submodule Support**: Optional inclusion of Git submodules\n- **Multiple Formats**: PNG, SVG, PDF output for graphs\n\n## Quick Start\n\n### 1. Setup Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/ErlViz.git\ncd ErlViz\n\n# Run setup script (creates virtualenv and installs dependencies)\npython setup.py\n```\n\n### 2. Install System Dependencies\n\n**Graphviz** is required for graph generation:\n\n```bash\n# macOS\nbrew install graphviz\n\n# Ubuntu/Debian\nsudo apt-get install graphviz\n\n# CentOS/RHEL\nsudo yum install graphviz\n\n# Windows\n# Download from https://graphviz.org/download/\n```\n\n### 3. Activate Virtual Environment\n\n```bash\n# Unix/Linux/macOS\nsource venv/bin/activate\n\n# Windows\nvenv\\Scripts\\activate\n```\n\n## Usage\n\n### GUI Mode (Recommended)\n\nLaunch the PySide6-based graphical interface:\n\n```bash\npython main.py\n```\n\nThe GUI provides:\n- Repository input (local path or GitHub URL)\n- Analysis options configuration\n- Real-time progress monitoring\n- Interactive result viewing\n- Graph and documentation export\n\n### CLI Mode\n\nAnalyze projects from the command line:\n\n```bash\n# Analyze a local project\npython main.py --cli /path/to/erlang/project\n\n# Analyze a GitHub repository\npython main.py --cli https://github.com/leondavi/NErlNet\n\n# Customize output options\npython main.py --cli https://github.com/ninenines/cowboy \\\n    --output ./cowboy_analysis \\\n    --format svg \\\n    --include-submodules \\\n    --verbose\n```\n\n#### CLI Options\n\n```\n--cli PROJECT_PATH          Run in CLI mode with specified project\n--output DIR                Output directory (default: ./erlviz_output)\n--format {png,svg,pdf}      Graph output format (default: png)\n--no-graphs                 Skip graph generation\n--no-docs                   Skip documentation generation\n--include-submodules        Include Git submodules\n--no-cache                  Disable repository caching\n--verbose                   Enable verbose logging\n```\n\n## Example Projects\n\n### NErlNet Analysis\n```bash\npython main.py --cli https://github.com/leondavi/NErlNet\n```\n\nNErlNet is a sophisticated distributed machine learning framework that demonstrates:\n- Complex OTP supervision trees\n- State machine implementations (`gen_statem`)\n- HTTP API handling with Cowboy\n- NIF integration for performance-critical operations\n- Multi-application architecture\n\n### Cowboy Analysis\n```bash\npython main.py --cli https://github.com/ninenines/cowboy\n```\n\nCowboy is a clean HTTP server framework showcasing:\n- Standard OTP application patterns\n- Protocol handler behaviors\n- Clean module organization\n- Extensive examples and tests\n\n## Architecture\n\nErlViz is built with a modular architecture:\n\n```\nerlviz/\n├── core/                   # Core analysis engine\n│   ├── analyzer.py         # Erlang code analysis\n│   ├── graph_generator.py  # Graph generation\n│   ├── documentation_generator.py  # Doc generation\n│   ├── repository_manager.py       # Git repository handling\n│   └── erlviz.py          # Main orchestrator\n├── gui/                    # PySide6 GUI application\n│   ├── main_window.py     # Main application window\n│   └── __init__.py\n└── __init__.py            # Package initialization\n```\n\n### Core Components\n\n1. **ErlangAnalyzer**: Parses Erlang source files to extract:\n   - Module metadata and behaviors\n   - Function exports and documentation\n   - Dependencies and imports\n   - NIF implementations\n\n2. **ErlangGraphGenerator**: Creates visualizations using Graphviz:\n   - Dependency graphs with behavior clustering\n   - Communication pattern diagrams\n   - NIF integration maps\n   - OTP behavior hierarchies\n\n3. **ErlangDocumentationGenerator**: Generates comprehensive docs:\n   - Markdown and HTML formats\n   - Module and API references\n   - Behavior analysis reports\n   - Architecture overviews\n\n4. **RepositoryManager**: Handles Git operations:\n   - Repository cloning and caching\n   - Submodule management\n   - GitHub integration\n\n## Output Structure\n\nErlViz generates a comprehensive analysis output:\n\n```\nerlviz_output/\n├── docs/                   # Generated documentation\n│   ├── README.md          # Project overview\n│   ├── modules.md         # Module documentation\n│   ├── behaviors.md       # OTP behavior analysis\n│   ├── nifs.md           # NIF documentation\n│   ├── communication.md   # Communication patterns\n│   ├── dependencies.md    # Dependency analysis\n│   ├── api.md            # API reference\n│   └── *.html            # HTML versions\n├── graphs/                # Generated graphs\n│   ├── dependency_graph.png\n│   ├── communication_diagram.png\n│   ├── behavior_hierarchy.png\n│   └── nif_diagram.png\n└── analysis_results.json  # Raw analysis data\n```\n\n## Development\n\n### Project Structure\n\nThe project follows Python best practices with clear separation of concerns:\n\n- **Core Logic**: Pure Python analysis and generation logic\n- **GUI Layer**: PySide6-based user interface  \n- **CLI Interface**: Command-line tools for automation\n- **Configuration**: JSON-based configuration management\n\n### Adding New Features\n\n1. **New Analysis Types**: Extend `ErlangAnalyzer` with additional parsing logic\n2. **New Visualizations**: Add methods to `ErlangGraphGenerator`\n3. **New Documentation**: Extend `ErlangDocumentationGenerator`\n4. **GUI Enhancements**: Modify `main_window.py` and related components\n\n### Testing\n\n```bash\n# Run with example projects\npython main.py --cli https://github.com/ninenines/cowboy --verbose\n\n# Test specific components\npython -c \"from erlviz import ErlangAnalyzer; print('Import successful')\"\n```\n\n## Configuration\n\nCreate custom configurations in `config/`:\n\n```json\n{\n  \"output_format\": \"png\",\n  \"generate_graphs\": true,\n  \"generate_docs\": true,\n  \"include_submodules\": false,\n  \"cache_dir\": \"~/.erlviz/cache\",\n  \"graph_options\": {\n    \"dpi\": 300,\n    \"rankdir\": \"TB\"\n  }\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Graphviz not found**: Install system Graphviz package\n2. **PySide6 import error**: Install with `pip install PySide6`\n3. **Git authentication**: Use HTTPS URLs or configure SSH keys\n4. **Large repositories**: Enable caching and use `--no-submodules`\n\n### Debug Mode\n\nEnable verbose logging for troubleshooting:\n\n```bash\npython main.py --cli \u003cproject\u003e --verbose\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\nQuick start for contributors:\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### Third Party Licenses\n\nErlViz uses several open source libraries. See [NOTICE](NOTICE) file for complete attribution.\n\n## Acknowledgments\n\n- **NErlNet**: Example of complex Erlang ML framework\n- **Cowboy**: Clean OTP application example  \n- **Graphviz**: Graph visualization engine\n- **PySide6**: GUI framework\n- **Erlang/OTP**: The language and platform we analyze\n- **Open Source Community**: For the amazing tools that make this possible\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleondavi%2Ferlviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleondavi%2Ferlviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleondavi%2Ferlviz/lists"}