https://github.com/benidevo/drift
Catch architectural violations before they become technical debt. Drift analyzes your code changes to ensure they follow established patterns.
https://github.com/benidevo/drift
architectural-patterns code-analysis-tool code-review github-actions gitlab-ci llm python technical-debt
Last synced: 8 months ago
JSON representation
Catch architectural violations before they become technical debt. Drift analyzes your code changes to ensure they follow established patterns.
- Host: GitHub
- URL: https://github.com/benidevo/drift
- Owner: benidevo
- License: mit
- Created: 2025-07-28T00:22:26.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-07-28T22:43:19.000Z (8 months ago)
- Last Synced: 2025-07-28T23:27:33.800Z (8 months ago)
- Topics: architectural-patterns, code-analysis-tool, code-review, github-actions, gitlab-ci, llm, python, technical-debt
- Language: Python
- Homepage:
- Size: 206 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🌊 Drift
[](https://github.com/benidevo/drift/actions/workflows/ci.yml)
[](https://codecov.io/gh/benidevo/drift)
[](https://www.python.org/downloads/)
[](https://python-poetry.org/)
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
[](https://www.docker.com/)
[](https://github.com/pre-commit/pre-commit)
Catch architectural violations before they become technical debt. Drift analyzes your code changes to ensure they follow established patterns.
## 🎯 The Problem
As codebases grow, they often drift away from their intended architecture:
- Direct database calls bypass the repository layer
- Services become tightly coupled instead of maintaining clean boundaries
- API contracts change without considering downstream impacts
- Established patterns get violated in the rush to ship features
Traditional code reviews catch syntax issues but often miss these architectural concerns.
## 💡 How Drift Helps
Drift integrates into your GitHub or GitLab pipeline to automatically review code changes:
1. **Detects Violations**: Identifies when code breaks architectural patterns
2. **Provides Context**: Understands why changes are being made from PR descriptions
3. **Shows Impact**: Visualizes how changes affect your system architecture
4. **Suggests Fixes**: Offers specific recommendations to maintain consistency
## ✨ Key Features
- **Pattern Detection**: Recognizes repository patterns, service boundaries, and API contracts
- **LLM Agnostic**: Use OpenAI, Gemini, Claude, or any LLM provider
- **Visual Diagrams**: See architectural impact with generated diagrams
- **Non-Blocking**: Advisory feedback that doesn't stop your deployment
- **Context Aware**: Incorporates business requirements from PR descriptions
## 🚀 Quick Start
### Prerequisites
- Python 3.12+
- Poetry (for dependency management)
- Docker (optional, for containerized development)
### Development Setup
1. **Clone the repository**
```bash
git clone https://github.com/benidevo/drift.git
cd drift
```
2. **Install dependencies**
```bash
poetry install
```
3. **Configure environment variables**
```bash
cp .env.example .env
# Edit .env with your API keys and configuration
```
4. **Set up pre-commit hooks**
```bash
make setup-pre-commit
```
5. **Run the application**
```bash
poetry run python -m drift
```
### Docker Development
For a consistent development environment, use Docker:
```bash
# Build the development image
make build
# Run the application
make run
# Run tests
make test
# Run linting
make lint
# Type check with mypy
make type-check
# Format code
make format
```
### Available Commands
Run `make help` to see all available commands:
- `make build`: Build Docker image
- `make run`: Run development container
- `make test`: Run tests in Docker
- `make lint`: Run linting in Docker
- `make format`: Format code in Docker
- `make type-check`: Run type checking with mypy
- `make clean`: Clean Docker images and containers
- `make setup-pre-commit`: Install pre-commit hooks
## 🧪 Testing
Run tests with coverage:
```bash
poetry run pytest
```
Or using Docker:
```bash
make test
```
## ⚙️ Configuration
Drift uses environment variables for configuration. See `.env.example` for all available options:
- **LLM Configuration**: Choose your LLM provider (OpenAI, Anthropic, etc.) and API key
- **Platform Tokens**: GitHub or GitLab tokens for API access
- **JIRA Integration**: Optional integration for pulling context from JIRA tickets
- **Custom Endpoints**: Support for enterprise LLM gateways
Example configuration:
```bash
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
```
## 🔧 Development
### Code Quality
This project uses:
- **Ruff** for linting and formatting
- **Mypy** for type checking
- **Pytest** for testing
- **Pre-commit** for git hooks
Pre-commit hooks automatically run on every commit to ensure code quality. They will:
- Format code with Ruff
- Check for linting issues
- Run type checking with Mypy
- Validate commit message format
- Fix common issues (trailing whitespace, file endings)
### Commit Messages
Follow conventional commits format:
- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation changes
- `chore:` Maintenance tasks
- `test:` Test improvements
- `refactor:` Code refactoring
## 📊 Status
This project is under active development.
## 🛠️ Built With
- Python for broad compatibility
- LiteLLM for flexible LLM integration
- Docker for consistent deployment
- Native CI/CD integration for GitHub Actions and GitLab CI
## 📚 Documentation
- [Project Specification](docs/Project-Specification.md)
- [Technical Design](docs/Technical-Design-Document.md)