A comprehensive toolkit for enforcing sustainable software architecture patterns through intelligent analysis, automated refactoring recommendations, and consistent code quality standards.
🔍 ADP Applies to Itself: This project uses its own architectural discipline tools for self-governance. See ARCHITECTURAL_HEALTH.md for our current metrics and improvement plan.
The Architectural Discipline Package provides a complete solution for maintaining high-quality, maintainable software architecture across projects of any size. It combines statistical analysis, ESLint integration, CLI tooling, and project templates to create a unified approach to architectural excellence.
Multi-Language Support: ADP now supports analysis for multiple programming languages including JavaScript/TypeScript, PowerShell, C#, and Rust, allowing you to apply the same architectural discipline principles across your entire codebase.
@plures-adp/core- Statistical analysis engine and rule definitions with multi-language support@plures-adp/eslint-plugin- ESLint plugin for architectural rules (TypeScript/JavaScript)@plures-adp/cli- Command-line interface for analysis and refactoring across all supported languages
@plures-adp/template-vscode-extension- VS Code extension template@plures-adp/template-web-app- Web application template@plures-adp/template-mobile-app- Mobile application template@plures-adp/template-cli-tool- CLI tool template@plures-adp/template-library- Library template@plures-adp/template-api-service- API service template
powershell-module- PowerShell module template (.psm1, .psd1)powershell-cli- PowerShell CLI script template (.ps1)
csharp-library- C# class library template (.csproj)csharp-console- C# console application template
rust-library- Rust library template (lib.rs)rust-cli- Rust CLI binary template (main.rs)
Recommended: Universal Installer (Works with any project type)
# Using npx (no installation required)
npx @plures-adp/installer install
# Or using npm create
npm create adp@latestDirect Package Installation (Node.js/TypeScript)
# Install the CLI globally
npm install -g @plures-adp/cli
# Or install specific packages
npm install --save-dev @plures-adp/cli @plures-adp/core @plures-adp/eslint-pluginDeno Installation
# Add to deno.json and run
deno task adp:analyze
# Or run directly
deno run npm:@plures-adp/cli analyzeOffline Installation (Air-Gapped Environments)
# Download bundle on connected machine
npx @plures-adp/installer download-offline
# Transfer to air-gapped system and install
cd adp-offline
node install-offline.js📖 Complete Installation Guide - Detailed instructions for all platforms and scenarios
# Analyze your project (supports multiple languages automatically)
architectural-discipline analyze
# Analyze specific path
architectural-discipline analyze --path src
# Generate refactoring recommendations
architectural-discipline recommend
# Create a new project with architectural discipline
architectural-discipline create my-project --template web-app
# List all available templates
architectural-discipline create --list-templates
# Create PowerShell module
architectural-discipline create my-module --template powershell-module
# Create C# library
architectural-discipline create my-lib --template csharp-library
# Create Rust CLI
architectural-discipline create my-cli --template rust-cliThe CLI automatically detects and analyzes files from supported languages:
- TypeScript/JavaScript:
.ts,.tsx,.js,.jsx - PowerShell:
.ps1,.psm1 - C#:
.cs,.csx - Rust:
.rs
Analysis results include language-specific metrics and recommendations tailored to each language's conventions.
// eslint.config.js
import architecturalDiscipline from '@plures-adp/eslint-plugin';
export default [
architecturalDiscipline.configs.recommended,
{
rules: {
'@plures-adp/max-lines': 'error',
'@plures-adp/max-complexity': 'warn',
}
}
];The package follows a modular architecture with clear separation of concerns:
packages/
├── core/ # Statistical analysis engine
├── eslint-plugin/ # ESLint integration
├── cli/ # Command-line interface
└── templates/ # Project templates
├── vscode-extension/
├── web-app/
├── mobile-app/
├── cli-tool/
├── library/
└── api-service/
- JavaScript/TypeScript: Full support with ESLint integration
- PowerShell: Analysis for
.ps1,.psm1, and module files - C#: Analysis for
.csand.csxfiles with project structure awareness - Rust: Analysis for
.rsfiles with crate and module understanding - Unified Metrics: Same architectural principles applied consistently across all languages
- Statistical Analysis: Analyzes codebase patterns and identifies outliers per language
- Complexity Metrics: Measures cyclomatic complexity and cognitive load (language-specific)
- Purity Scoring: Evaluates function purity and side effects (language-aware)
- Modularity Assessment: Analyzes module cohesion and coupling
- Refactoring Suggestions: Provides specific, actionable refactoring recommendations
- Priority Classification: Categorizes issues by severity and impact
- Context-Aware: Considers project type and domain-specific patterns
- Incremental Improvement: Supports gradual architectural improvement
- ESLint Integration: Seamless integration with existing linting workflows
- Pre-commit Hooks: Automated quality checks before commits
- CI/CD Integration: Continuous quality monitoring in pipelines
- Customizable Rules: Configurable thresholds and rule sets
- Best Practices: Pre-configured with architectural discipline rules
- Framework Support: Templates for popular frameworks and platforms
- Documentation: Comprehensive guides and examples
- Migration Support: Tools for adding discipline to existing projects
The Architectural Discipline Package is built on the principle that sustainable software architecture requires consistent, measurable practices. It provides:
- Objective Metrics: Quantifiable measures of code quality and maintainability
- Actionable Insights: Specific recommendations rather than abstract principles
- Gradual Adoption: Incremental improvement without disrupting existing workflows
- Community Standards: Shared understanding of architectural excellence
- Self-Governance: ADP uses its own tools to maintain its codebase quality
ADP applies its own architectural discipline principles to itself:
- Current Health Score: 27/100 (baseline established)
- Continuous Monitoring: Automated analysis runs before commits
- Transparent Improvement: All metrics and improvement plans are documented
- Incremental Refactoring: Following the gradual improvement approach we recommend
See ARCHITECTURAL_HEALTH.md for detailed metrics and our improvement roadmap.
ADP builds on and complements existing architectural tooling. Here's how it compares:
ESLint Plugins (eslint-plugin-import, eslint-plugin-boundaries):
- ✅ Deep TypeScript/JavaScript integration
- ✅ Real-time IDE feedback
- ❌ Limited to JavaScript ecosystem
- ❌ Manual rule configuration required
- ❌ No statistical analysis
ADP:
- ✅ Multi-language support (TypeScript, PowerShell, C#, Rust)
- ✅ Statistical analysis automatically determines thresholds
- ✅ File type classification without manual configuration
- ✅ Integrated with ESLint for JavaScript/TypeScript
- ✅ Holistic project health scoring
Use Together: ADP complements ESLint by providing higher-level architectural analysis while ESLint handles syntax and style.
Madge / dependency-cruiser:
- ✅ Excellent dependency visualization
- ✅ Circular dependency detection
- ✅ Detailed module graphs
- ❌ Focused only on dependencies
- ❌ No complexity or size analysis
- ❌ Manual threshold configuration
ADP:
- ✅ Analyzes dependencies, complexity, size, and purity
- ✅ Statistical thresholds adapt to your codebase
- ✅ Provides refactoring recommendations
- ✅ Multi-language support
- ✅ Project health trending over time
- 🔄 Dependency graphing planned (future feature)
Use Together: Combine ADP for overall architecture with Madge for detailed dependency visualization.
ArchUnit (Java) / NetArchTest (.NET):
- ✅ Enforce architectural rules as tests
- ✅ Layer dependency rules
- ✅ Naming conventions
- ✅ Strong type safety
- ❌ Single language per tool
- ❌ Requires writing test code
- ❌ No statistical analysis
- ❌ Binary pass/fail (no gradual improvement)
ADP:
- ✅ Multi-language support in one tool
- ✅ Statistical analysis finds issues automatically
- ✅ Gradual improvement model
- ✅ Works without writing tests
- ✅ Provides concrete refactoring suggestions
- ✅ Tracks improvement over time
- 🔄 Layer rules planned (future feature)
Use Together: Use ArchUnit/NetArchTest for strict architectural constraints in tests, ADP for continuous quality measurement and improvement tracking.
- Multi-Language Consistency: Same architectural principles across TypeScript, PowerShell, C#, Rust, and more
- Statistical Intelligence: Automatically learns your codebase patterns and identifies outliers
- File Type Classification: Understands that components, services, and utilities have different expected characteristics
- Gradual Improvement: Designed for incremental refactoring, not "big bang" changes
- Self-Documenting: Applies its own rules to itself, demonstrating transparency
- Actionable Recommendations: Doesn't just report problems, suggests specific fixes
- Project Health Scoring: Single metric that tracks overall architecture quality
| Scenario | Recommended Tool(s) |
|---|---|
| JavaScript/TypeScript linting | ESLint + ADP |
| Visualize module dependencies | Madge or dependency-cruiser |
| Enforce layer boundaries (Java) | ArchUnit + ADP |
| Enforce layer boundaries (.NET) | NetArchTest + ADP |
| Multi-language architecture analysis | ADP |
| Statistical complexity analysis | ADP |
| Gradual refactoring guidance | ADP |
| Cross-language consistency | ADP |
| Project health trends | ADP |
ADP is designed to work alongside your existing tools:
# Example CI/CD integration
jobs:
quality:
runs-on: ubuntu-latest
steps:
# Syntax and style
- run: npm run lint
# Architecture analysis
- run: architectural-discipline analyze
# Dependency graph (if using Madge)
- run: madge --circular src/
# Unit tests with ArchUnit/NetArchTest
- run: npm testTraditional Tools: "Does this code violate a specific rule?"
ADP: "Is this file an outlier compared to similar files in this codebase?"
Traditional Tools: Manual threshold configuration
ADP: Statistical analysis determines expected ranges
Traditional Tools: Binary pass/fail
ADP: Graduated severity with improvement tracking
Traditional Tools: Single language focus
ADP: Multi-language architectural consistency
- Getting Started
- Multi-Language Usage - Guide for using ADP with PowerShell, C#, Rust, and more
- Installation Guide - Detailed installation instructions for all platforms
- End-to-End Demos - Complete examples showing analyze → recommend → fix workflow
- Rule Catalog Index - Overview of all rules
- TypeScript/JavaScript Rules - Complete rule reference with examples
- PowerShell Rules - PowerShell-specific architectural rules
- C# Rules - C# and .NET guidelines
- Rust Rules - Rust idioms and best practices
- Architectural Health Report - ADP's self-governance metrics
- Development Process - How we use ADP on itself
We welcome contributions! Please see our Contributing Guide for details.
MIT License - see LICENSE for details.
Built with inspiration from:
- Clean Architecture principles
- SOLID design principles
- Statistical analysis methodologies
- Modern JavaScript/TypeScript best practices
- Community-driven quality standards