Proxy-based Message System

A modular and extensible message-sending system built with Python that demonstrates the Proxy Pattern, Composite Pattern, and Factory Pattern. The project allows multiple proxies such as access control, logging, and caching to be chained dynamically while keeping the core message sender completely independent from cross-cutting concerns.

---

✨ Features

• Access Control Proxy for role-based permission checking
• Logging Proxy for recording requests using Python's built-in logging module (console and file output)
• Caching Proxy to prevent redundant processing by caching repeated messages
• Composite Proxy for chaining multiple proxies in any order
• Dynamic Proxy with transparent delegation of unknown methods to the target object
• Factory Pattern for building proxy chains from a simple configuration dictionary
• Clean architecture with clear Separation of Concerns
• Follows the Open/Closed Principle, making it easy to introduce new proxies without modifying existing business logic
• Designed with maintainability, extensibility, and SOLID principles in mind

---

📂 Project Structure

message-system/
├── core/                   # Interfaces and real message sender
├── proxies/                # Proxy implementations
├── factories/              # ProxyFactory for building proxy chains
├── config/                 # Configuration files
├── tests/                  # Unit tests
├── docs/
│   └── sample-chapters/    # Free sample chapters from the full book
│       ├── chapter-01-introduction.md
│       └── chapter-02-components.md
├── utils/                  # Utility modules (optional)
├── main.py                 # Application entry point
├── README.md
└── .gitignore

---

🚀 Quick Start

from core.real_sender import RealMessageSender
from core.interfaces import User
from factories.proxy_factory import ProxyFactory
from config.settings import DEFAULT_CONFIG, DEFAULT_USER

# Create the real sender
real_sender = RealMessageSender()

# Create a user
user = User(**DEFAULT_USER)

# Build the proxy chain from configuration
proxy = ProxyFactory.create_proxy(
    target=real_sender,
    config=DEFAULT_CONFIG,
    user=user
)

# Send messages
proxy.send("Hello World!")
proxy.send("Hello World!")   # Returned from cache
proxy.send("Another message")

---

⚙️ Architecture

The project is composed of several independent layers:

• RealMessageSender handles the actual message delivery.
• ProxyFactory creates and connects proxies based on configuration.
• CompositeProxy combines multiple proxies into a single processing pipeline.
• Individual proxy classes each implement one specific responsibility:
  • Access Control
  • Logging
  • Caching

This design keeps the system flexible and allows behaviors to be added or removed simply by changing the configuration.

---

➕ Adding a New Proxy

Adding a custom proxy requires only a few steps:

1. Create a new proxy class that inherits from MessageSubject.
2. Register the class inside ProxyFactory._PROXY_CLASSES.
3. Add its execution order to ProxyFactory._PROXY_ORDER.
4. Update settings.py if the proxy requires configuration.

No changes to the existing business logic are required.

---

📚 Documentation & Book

📖 Free Sample Chapters

The first two chapters of the complete Persian book are available for free right inside this repository:

• Chapter 1: Introduction, Goal, and Architecture
• Chapter 2: Component Breakdown and Relationships

These chapters give you a solid overview of the project, its architecture, and how all the pieces work together.

📘 Full Book (Coming Soon on Ketabrah)

If you want to go much deeper, the full book covers:

• All 9 chapters with detailed analysis of every component
• Execution flow and what happens under the hood
• Deep dive into CompositeProxy and ProxyFactory
• Complete breakdown of DynamicProxy and its real-world applications
• Design principles, SOLID, and patterns used in the project
• Common mistakes and lessons learned during development
• How to turn this project into a real-world library
• Final mental model and complete project review

🔗 Link to purchase the full book on Ketabrah (coming soon)

The book is written in Persian and is perfect for intermediate-to-advanced Python developers who want to master design patterns and clean architecture through a practical, hands-on project.

---

🧪 Testing

Unit tests are available under the tests/ directory.

Run all tests with:

python -m unittest discover tests -v

---

🏗️ Design Principles

This project emphasizes:

• SOLID Principles
  • Single Responsibility Principle (SRP)
  • Open/Closed Principle (OCP)
• Composition over Inheritance
• Design Patterns:
  • Proxy Pattern
  • Composite Pattern
  • Factory Pattern
  • Chain of Responsibility (implicitly)
  • Registry Pattern
  • Decorator Pattern

---

📄 License

This project is licensed under the MIT License.
You are free to use, modify, and distribute the code for any purpose, including commercial projects, as long as you retain the copyright notice.

See the LICENSE file for full details.

---

🤝 Contributing

Contributions are welcome.

If you would like to improve the project:

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a Pull Request.

Please keep the code modular, maintainable, and consistent with the project's architecture and SOLID principles.