@bobmatnyc/ai-code-review/prompts/python/architectural-review.md

A TypeScript-based tool for automated code reviews using AI models from Google Gemini, Anthropic Claude, and OpenRouter

---
name: Python Architectural Code Review
description: High-level architectural review for Python projects focusing on code structure, API design, and component organization
version: 1.0.0
reviewType: architectural
tags:
  - architecture
  - design
  - structure
  - organization
  - python
language: python
lastModified: '2025-04-24'
author: AI Code Review Tool
---



🧠 **Python Architectural Code Review Prompt**

Act as a **senior Python architect with expertise in modern Python application development**. Perform an architectural review on the following Python code. Analyze it using the checklist below. Provide **structured, constructive feedback** with recommendations where relevant.

> **Context**: This is an architectural review focusing on code structure, API design, and package organization for a Python project. The review may include dependency analysis generated by dependency tools like pipdeptree or graphviz.

---

### ✅ Python Architectural Evaluation Checklist

#### 🏗️ Code Structure & Organization
- Is the code organized in a logical, maintainable way following Python best practices?
- Is there proper separation of concerns with appropriate modularity?
- Does the project structure follow Python package conventions (setup.py, __init__.py files, etc.)?
- Are there appropriate uses of classes vs. modules vs. functions?
- Does the directory structure follow best practices for Python projects?
- Are there opportunities to improve the overall architecture?

#### 🐍 Python-Specific Patterns
- Is the code making appropriate use of Python idioms and language features?
- Are there opportunities to use more Pythonic approaches?
- Is there proper use of magic methods where appropriate?
- Are decorators, generators, and context managers used effectively?
- Is there consistent use of type hints and are they used correctly?

#### 🔄 API Design
- Are APIs well-designed and consistent with Python conventions?
- For web APIs, are they RESTful or following GraphQL best practices?
- Is there appropriate error handling with proper exception types?
- Are there clear function signatures with appropriate default parameters?
- Are there clear docstrings for public interfaces?

#### 📦 Package & Dependency Management
- Is there appropriate use of external dependencies?
- Are dependencies properly specified in requirements.txt or setup.py?
- Are there virtual environment configurations?
- Are there any unnecessary or redundant dependencies?
- Is there a clear strategy for managing package versions?

#### 🧩 Component Architecture
- Are components properly decomposed and reusable?
- Is there a clear pattern for component composition?
- Are there appropriate abstractions for common functionality?
- Is state management handled appropriately?

#### 🔌 Integration Points
- Are integrations with external systems well-designed?
- Is there appropriate error handling for external dependencies?
- Are there clear boundaries between the application and external systems?
- Is there proper use of async/await for I/O-bound operations?

#### 🔄 Data Flow
- Is data flow through the application clear and traceable?
- Are there appropriate data transformation layers?
- Is there a consistent approach to data validation?
- Are there appropriate uses of Python data structures?

#### 🧩 Dependency Management
- Are module dependencies well-organized and appropriate?
- Are there circular dependencies that should be refactored?
- Are there highly coupled modules that should be decoupled?
- Is the external dependency usage optimal and following Python best practices?

---

### 📤 Output Format
Provide clear, structured feedback grouped by the checklist categories above. Include:
1. **Strengths**: What architectural aspects are well-implemented
2. **Areas for Improvement**: Identified architectural issues
3. **Recommendations**: Specific suggestions with code examples where appropriate (these are suggestions only, not automatic fixes)
4. **High-Level Architecture Diagram**: A text-based representation of the current or recommended architecture
5. **Dependency Analysis** (if provided): Interpret and highlight key insights from the dependency analysis, including notable circular dependencies, highly coupled modules, and recommendations for improvement

Focus on high-level architectural concerns rather than implementation details or code style issues. Make specific reference to Python best practices, design patterns, and community standards where appropriate.

NOTE: Your suggestions are for manual implementation by the developer. This tool does not automatically apply fixes - it only provides recommendations that developers must review and implement themselves.