sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add architecture validation system with comprehensive pattern enforcement

Browse Source 
Implemented automated architecture validation to enforce design decisions:

Architecture Validation System:
- Created .architecture-rules.yaml with comprehensive rule definitions
- Implemented validate_architecture.py script with AST-based validation
- Added pre-commit hook configuration for automatic validation
- Comprehensive documentation in docs/architecture/architecture-patterns.md

Key Design Rules Enforced:
- API-001 to API-004: API endpoint patterns (Pydantic models, no business logic, exception handling, auth)
- SVC-001 to SVC-004: Service layer patterns (domain exceptions, db session params, no HTTP concerns)
- MDL-001 to MDL-002: Model separation (SQLAlchemy vs Pydantic)
- EXC-001 to EXC-002: Exception handling (custom exceptions, no bare except)
- JS-001 to JS-003: JavaScript patterns (apiClient, logger, Alpine components)
- TPL-001: Template patterns (extend base.html)

Features:
- Validates separation of concerns (routes vs services vs models)
- Enforces proper exception handling (domain exceptions in services, HTTP in routes)
- Checks database session patterns and Pydantic model usage
- JavaScript and template validation
- Detailed error reporting with suggestions
- Integration with pre-commit hooks and CI/CD

UI Fix:
- Fixed icon names in content-pages.html (pencil→edit, trash→delete)

Documentation:
- Added architecture patterns guide with examples
- Created scripts/README.md for validator usage
- Updated mkdocs.yml with architecture documentation
- Built and verified documentation successfully

Usage:
  python scripts/validate_architecture.py              # Validate all
  python scripts/validate_architecture.py --verbose    # With details
  python scripts/validate_architecture.py --errors-only # Errors only

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2025-11-28 07:44:51 +01:00
parent 83a6831b2e
commit 1e720ae0e5
7 changed files with 1943 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
scripts/README.md Normal file
View File

@@ -0,0 +1,227 @@
# Architecture Validation Scripts
This directory contains scripts for validating and enforcing architectural patterns across the codebase.
## Architecture Validator
### Overview
`validate_architecture.py` is an automated tool that checks the codebase against architectural rules defined in `.architecture-rules.yaml`.
### Key Features
- **API Endpoint Validation**: Ensures proper separation of concerns, Pydantic usage, exception handling
- **Service Layer Validation**: Enforces domain exceptions, database session patterns
- **Model Validation**: Checks proper separation of SQLAlchemy and Pydantic models
- **Exception Handling**: Validates proper exception patterns
- **JavaScript Patterns**: Enforces coding standards for frontend code
- **Template Validation**: Ensures templates follow required patterns
### Usage
```bash
# Validate entire codebase
python scripts/validate_architecture.py
# Validate specific directory
python scripts/validate_architecture.py app/api/
# Verbose output with code context
python scripts/validate_architecture.py --verbose
# Show only errors (suppress warnings)
python scripts/validate_architecture.py --errors-only
# Use custom config file
python scripts/validate_architecture.py --config custom-rules.yaml
```
### Exit Codes
- `0`: Validation passed (warnings allowed)
- `1`: Validation failed (errors found)
### Integration with Pre-commit
Install pre-commit hooks to run validation automatically:
```bash
# Install pre-commit
pip install pre-commit
# Setup hooks
pre-commit install
# Run manually on all files
pre-commit run --all-files
# Run on staged files only
pre-commit run
```
### Configuration
The validation rules are defined in `.architecture-rules.yaml` at the project root. This file contains:
- **Core Principles**: Separation of concerns, type safety, exception handling
- **API Endpoint Rules**: (API-001 through API-004)
- **Service Layer Rules**: (SVC-001 through SVC-004)
- **Model Rules**: (MDL-001 through MDL-002)
- **Exception Rules**: (EXC-001 through EXC-002)
- **JavaScript Rules**: (JS-001 through JS-003)
- **Template Rules**: (TPL-001)
### Rule Categories
#### API Endpoint Rules
- **API-001**: Use Pydantic models for request/response
- **API-002**: No business logic in endpoints
- **API-003**: Proper exception handling (catch and convert to HTTPException)
- **API-004**: Authentication on protected endpoints
#### Service Layer Rules
- **SVC-001**: No HTTPException in services (use domain exceptions)
- **SVC-002**: Create custom exception classes (avoid generic Exception)
- **SVC-003**: Database session as parameter (not created internally)
- **SVC-004**: Use Pydantic for input validation
#### Model Rules
- **MDL-001**: Use SQLAlchemy Base for database models
- **MDL-002**: Separate Pydantic from SQLAlchemy models
#### Exception Rules
- **EXC-001**: Define custom exceptions in exceptions module
- **EXC-002**: Never use bare except
#### JavaScript Rules
- **JS-001**: Use apiClient directly (not window.apiClient)
- **JS-002**: Use centralized logger (not console)
- **JS-003**: Alpine components must spread ...data()
### Example Output
```
🔍 Starting architecture validation...
📡 Validating API endpoints...
🔧 Validating service layer...
📦 Validating models...
⚠️ Validating exception handling...
🟨 Validating JavaScript...
📄 Validating templates...
================================================================================
📊 ARCHITECTURE VALIDATION REPORT
================================================================================
Files checked: 145
Total violations: 3
❌ ERRORS (2):
--------------------------------------------------------------------------------
[API-002] Endpoint must NOT contain business logic
File: app/api/v1/admin/vendors.py:45
Issue: Database operations should be in service layer
💡 Suggestion: Move database operations to service layer
[SVC-001] Service must NOT raise HTTPException
File: app/services/vendor_service.py:78
Issue: Service raises HTTPException - use domain exceptions instead
💡 Suggestion: Create custom exception class (e.g., VendorNotFoundError) and raise that
⚠️ WARNINGS (1):
--------------------------------------------------------------------------------
[JS-001] Use apiClient directly
File: static/admin/js/vendors.js:23
Issue: Use apiClient directly instead of window.apiClient
💡 Suggestion: Replace window.apiClient with apiClient
================================================================================
❌ VALIDATION FAILED - Fix errors before committing
================================================================================
```
### CI/CD Integration
Add to your CI pipeline (GitHub Actions example):
```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
validate-architecture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install dependencies
run: |
pip install pyyaml
- name: Validate Architecture
run: |
python scripts/validate_architecture.py
```
### Documentation
For detailed architectural patterns and examples, see:
- [Architecture Patterns Documentation](../docs/architecture/architecture-patterns.md)
- [Architecture Rules Config](../.architecture-rules.yaml)
### Extending the Validator
To add new rules:
1. Add rule definition to `.architecture-rules.yaml`
2. Implement validation logic in `validate_architecture.py`
3. Add examples to `docs/architecture/architecture-patterns.md`
4. Test with `python scripts/validate_architecture.py --verbose`
### Troubleshooting
**Issue**: Validator reports false positives
**Solution**: Add exception patterns to `.architecture-rules.yaml` under `ignore` section
**Issue**: Validator doesn't catch a specific violation
**Solution**: The rule might not be implemented yet. Check `.architecture-rules.yaml` and `validate_architecture.py` to add the rule.
**Issue**: Pre-commit hook fails but manual run passes
**Solution**: Ensure pre-commit is using the same Python environment:
```bash
pre-commit clean
pre-commit install
```
### Contributing
When adding new architectural patterns:
1. Document the pattern in `docs/architecture/architecture-patterns.md`
2. Add validation rule to `.architecture-rules.yaml`
3. Implement validation in `validate_architecture.py`
4. Test thoroughly with existing codebase
5. Update this README with the new rule
---
**Questions?** See the [Architecture Patterns Documentation](../docs/architecture/architecture-patterns.md)