⚡
Challenges
Designing an intelligent matching engine between customers and properties based on dozens of specialized parameters, ensuring concurrency safety when generating unique codes, and implementing a multi-role architecture with dynamic access levels were among the primary challenges of this project.
Modeling the complex real estate domain—including legal property usage, ownership shares, orientation, and title deed information—preventing duplicate data through similarity-matching algorithms, and migrating existing data without information loss required a high level of precision.
Designing a Persian, right-to-left user interface with comprehensive forms, an interactive map, and simultaneous image and video uploads also presented significant UX challenges.
Other major challenges included optimizing database queries to prevent N+1 problems, managing the customer lifecycle, and implementing automatic property locking during the negotiation stage.
Ultimately, by leveraging advanced Django capabilities, atomic transactions, and carefully designed data models, a comprehensive and stable system was built to meet the needs of modern real estate agencies.
💡
Solutions
For the intelligent matching engine, a weighted scoring algorithm was designed in which each parameter—such as property usage, orientation, title deed status, ownership share, budget, and others—has a specific weight. The final score is calculated using normalization techniques. For optimization, `select_related`, `prefetch_related`, and in-memory calculations were utilized.
To prevent race conditions during the generation of unique codes, `select_for_update()` and atomic database transactions were implemented, ensuring that each record receives a unique code without conflicts.
The real estate domain was modeled through a modular architecture consisting of specialized models for property usage, title deeds, orientation, and unit status. To prevent duplicate records, a parameter-by-parameter similarity-matching algorithm with configurable thresholds was implemented.
Existing data was migrated through staged migrations using `RunPython`, with careful handling of `null` and `unique` constraints to ensure zero data loss.
The Persian right-to-left (RTL) user interface was implemented using Bootstrap, real-time number formatting, the Persian calendar, interactive Leaflet maps, and AJAX-based image and video uploads with live previews.
For performance optimization, appropriate database indexing, pagination, and N+1 query elimination were implemented using `select_related` and `prefetch_related`. The customer lifecycle and automatic property locking during the negotiation stage were managed using Django signals (`post_save`).
Ultimately, by leveraging advanced Django capabilities, atomic transactions, and a modular architecture, a comprehensive, stable, and production-ready system was built for modern real estate agencies.
📚
Outcomes
Built a comprehensive and integrated system for the end-to-end management of real estate agencies, covering the entire workflow from customer and property registration to contract management within a unified platform.
Successfully implemented an AI Matching engine with weighted scoring across dozens of specialized parameters, making the property recommendation process more accurate, faster, and data-driven.
Designed a multi-role architecture with dynamic access levels for managers, call-center operators, supervisors, agents, and customers, aligned with the real-world organizational structure of real estate agencies.
Implemented complete customer lifecycle management, from the initial contact through to contract signing, supported by deadlines, alerts, and performance reports.
Developed analytical dashboards and KPI metrics for evaluating agent performance, conversion rates, follow-up rates, and customer acquisition sources.
Implemented a fully Persian and right-to-left (RTL) user interface with comprehensive forms, interactive maps, and simultaneous image and video uploads.
Optimized system performance through database indexing, `select_related`, `prefetch_related`, and pagination to support large volumes of data.
Prevented duplicate records using similarity-matching algorithms and ensured concurrency safety through atomic transactions and `select_for_update`.
Ultimately, delivered a production-ready software product that meets the technical and user experience standards expected from a modern real estate CRM/ERP platform.
🔧
Technical Highlights
Used a modular Django architecture with separated applications (`estate`, `case_management`, `account`) to improve maintainability, scalability, and extensibility.
Implemented a Match Engine using a weighted scoring algorithm, score normalization, and detailed match-result storage in a `JSONField`.
Used `select_for_update()` and `transaction.atomic()` to prevent race conditions when generating sequential unique codes.
Optimized database queries using `select_related`, `prefetch_related`, `distinct()`, and indexing on key fields to eliminate N+1 query problems and improve overall performance.
Designed specialized real estate domain models using `TextChoices`, validators, and structured Many-to-Many (M2M) relationships for greater flexibility.
Implemented Django signals (`pre_save`, `post_save`) to automatically manage the customer process lifecycle, property locking during the negotiation stage, and activity logging.
Developed a custom authentication and authorization system using a custom `User` model, dynamic roles (`Role`, `UserRole`), and view-based permissions through `views_permissions`.
Implemented Duplicate Detection using a parameter-by-parameter similarity-matching algorithm, with detailed matching results stored in a `JSONField`.
Designed REST-style APIs using `JsonResponse` for AJAX communication between the frontend and backend, including matching, image management, status updates, and search operations.
Implemented a fully Persian, right-to-left (RTL) user interface using Bootstrap 5 and Leaflet.js, along with real-time number formatting and AJAX-based image and video uploads.
Used staged migrations with `RunPython` and careful handling of `null` and `unique` constraints to migrate existing data without information loss.
Designed a process logging system (`ProcessLog`) and notes system (`Note`) to provide comprehensive tracking of interactions with customers and properties.
Implemented multi-layer access control for confidential property images (`Showcase Image`), with permission checks at both the view and template levels.
🏗️
Architecture
The project is built on Django’s **MVT (Model-View-Template)** architecture and is organized into several independent applications: `estate` for property and customer management, `case_management` for customer process and lifecycle management, and `account` for user and role management.
**Data Layer (Models):** Includes abstract base models such as `TimeStampedModel`, `SoftDeleteModel`, and `UUIDModel`, along with specialized real estate domain models such as `Customer`, `Property`, `Match`, `Requirement`, `UsageType`, `DocumentType`, and others. Relationships are designed using `ForeignKey`, `ManyToManyField`, and `PROTECT` / `SET_NULL` strategies.
**Business Logic Layer (Views & Utils):** Includes CBV/FBV views for CRUD operations, along with specialized modules such as `MatchCalculator` and `MatchManager` for calculating match scores, and `views_permissions` for access control.
**Presentation Layer (Templates & Frontend):** Uses Django Templates with Bootstrap 5, a fully right-to-left (RTL) interface, Leaflet.js for interactive maps, and JavaScript for validation, number formatting, and AJAX communication with the backend.
**Signals:** Django signals are used to automatically handle events such as activity logging, property locking during the negotiation stage, and configuring deadlines for customer processes.
**Authentication & Authorization:** Built around a custom user model, dynamic roles (`Role`, `UserRole`), and the `views_permissions` mechanism for fine-grained access control over views and user interface elements.
**Database:** PostgreSQL with appropriate indexing on frequently queried fields such as `status`, `display_code`, `city`, and `expert`, along with atomic transactions to maintain data integrity.
**Modular Match Engine:** The match calculation logic (`MatchCalculator`) is separated from the persistence and management logic (`MatchManager`) to improve testability, maintainability, and extensibility.
**API & Communication:** Uses `JsonResponse` for AJAX responses and implements specialized APIs for search, property matching, image management, and location-based data retrieval.
📐
Project Scale
The project is organized into **5 independent Django applications** (`estate`, `case_management`, `account`).
More than **30 data models** have been designed and implemented, including base, location, customer, property, matching, process, note, and specialized real estate domain models.
More than **50 Views** have been implemented, covering complete CRUD operations, AJAX APIs, reporting, and access control.
More than **50 HTML templates** have been developed with a fully Persian and RTL design for various pages, including lists, forms, detail views, dashboards, and search interfaces.
More than **100 specialized data fields** have been designed across the core models (Customer and Property), providing comprehensive coverage of the Iranian real estate domain.
The **AI Matching Engine** is capable of evaluating hundreds of customers against thousands of properties simultaneously and assigning scores based on more than **20 specialized parameters**.
A **multi-role system** supports 5 primary roles—Manager, Call Center Operator, Supervisor, Agent, and Customer—with dynamic access levels.
A **complete customer lifecycle** has been implemented, from initial contact through contract signing, including more than **10 process statuses**, time-based deadlines, and automated alerts.
The **Reporting and KPI system** includes more than **15 analytical indicators** for evaluating agent performance, conversion rates, and customer acquisition sources.
Overall, the project has been developed with **thousands of lines of Python, HTML, CSS, and JavaScript code** and is ready for deployment in a real-world modern real estate agency environment.