⚡
Challenges
Integrating two independent services — a store and a booking system — into a single unified platform required a modular architecture with a shared User model. The complex inventory management in the Multi-Vendor model with variations in color, size, and scent was solved by designing an independent Owners model for each combination.
Simultaneous implementation of two payment gateways — Sepehr and ZarinPal — with different structures was achieved through an independent Service Layer and dedicated callback handling. Full support for the Persian calendar across all sections was implemented using persiantools libraries and dual storage (Gregorian + Persian).
The OTP-based SMS authentication system via the Ghasedak service, and the management of 5 access levels using Boolean fields with precise permission checks in every view, provided the necessary security and flexibility. Designing 3 independent Layouts (Panel, Site, SEO) and managing 4 different content types (Article, Question, Video, Experience) within a single model using a type field were other major challenges of the project.
Financial transaction security was ensured by checking for duplicate tracking codes, using UUID for InvoiceID, and verifying the amount at the Advice stage. Scalability was achieved through query optimization, using select_related, and caching frequently repeated results.
💡
Solutions
The project is built on a modular architecture with 10 independent Django applications, where the User model serves as the central connection point between all services. The authentication system is implemented using 4-digit OTP SMS via the Ghasedak service, storing the code in the random_pass field.
Management of 5 access levels is handled through Boolean fields in the User model, with precise permission checks at the beginning of each view. All views follow a unified pattern of @login_required + is_ajax() + i=action_name parameter + JsonResponse, which simplifies code maintenance.
Product inventory in Multi-Vendor mode is managed independently for each combination through the Owners model with fields owner_id, color, size, and scent. The Sepehr and ZarinPal payment gateways are implemented with independent Service Layers, Session management, Advice verification, and amount matching checks.
Persian calendar support is provided using persiantools libraries with dual storage (Gregorian + Persian) in the jalil_record_data field. The automated SMS system is designed with independent functions for each scenario (registration, login, order, deposit) and dynamic templates in myclass.py.
The multi-step conversational consultation system uses the Counseling model with a ManyToMany connection to Conversation, enabling file uploads, conversation continuation, and automatic archiving. The SEO system integrates content management using a single Seo model with a type field (Article, Question, Experience, Video) and type-specific fields.
Three custom Layouts (shared_panel, shared_index, shared_seo) with shared components provide visual variety without code duplication. Financial security is ensured through UUID for InvoiceID, duplicate tracking code verification, and amount matching at the Advice stage.
📚
Outcomes
The Mahdis project has been fully launched and is now online at mahdiss.com, offering an integrated platform for cosmetics retail and barbershop appointment booking. The project includes 10 modular Django applications, over 50 dedicated pages, 25+ data models, and 5 user access levels, implemented across 3 different Layouts.
From a technical standpoint, two reliable payment gateways (Sepehr and ZarinPal) have been successfully integrated, the OTP-based SMS authentication system is active, and features such as wallet, online consultation, SEO, Excel reporting, and automated SMS have been fully implemented. System security is ensured by adhering to CSRF Protection, XSS Prevention, and SQL Injection Prevention principles across all sections.
The project's architecture is designed to be modular and scalable, simplifying the development of future features. This project has successfully addressed complex challenges such as integrating two independent services, managing Multi-Vendor inventory, and processing two payment gateways simultaneously, ultimately becoming a production-ready product.
🔧
Technical Highlights
The Mahdis project is built on Django 4.2.6 (LTS) with a MySQL database and a Bootstrap 5 (RTL) user interface, utilizing a modular architecture with 10 independent applications. All views follow a unified pattern of @login_required + is_ajax() + i=action_name parameter + JsonResponse, which simplifies both development and maintenance.
The authentication system is based on SMS OTP via the Ghasedak service, storing the code in the random_pass field, while access management is verified at the beginning of each view using 5 Boolean Flag levels (admin_access, shop_access, barber_access, response_access, is_superuser). The Sepehr payment gateway (with GetToken/Advice/Session) and ZarinPal (with Authority/Verify) are each implemented in independent Service Layers.
Persian calendar support is provided using persiantools and django-jalali libraries with dual storage (Gregorian + Persian in jalil_record_data). The automated SMS system is designed with independent functions in myclass.py for each scenario (registration, login, order, deposit) and dynamic templates.
In the SEO section, a single Seo model with a type field is used to distinguish four content types (Article, Question, Experience, Video), with type-specific fields (case result, video_id, state, city) applied conditionally. Three custom Layouts (shared_panel, shared_index, shared_seo) with shared components provide visual variety without code duplication.
Financial security is ensured through UUID for unique InvoiceID, duplicate tracking code verification (digitalreceipt/ref_id), amount matching at the Advice stage, and using csrf_exempt only for the gateway Callback. Scalability is achieved through query optimization (select_related, prefetch_related) and caching frequently repeated results.
🏗️
Architecture
The Mahdis project is built on a Modular Architecture and divided into 10 independent Django applications: account (users), barber (barbershops), product (products), cart (shopping cart), marketing (marketing), payment (Sepehr gateway), zarinpal (ZarinPal gateway), site_profile (site profile), seo (content management), and resume (resumes). Each app has a specific responsibility, with the User model serving as the central connection point between all services.
Communication between applications is established through ForeignKey and ManyToMany relations; for instance, Products is connected to User via owner_shoper_id, and its inventory is maintained in the Owners model with fields owner_id, color, size, and scent. The presentation layer is implemented with 3 custom Layouts (shared_panel, shared_index, shared_seo) and shared components (header_component, side_bar_component, footer_component, left_pop_up).
The business logic layer in views follows a unified pattern of @login_required + permission check + is_ajax() + i=action_name + JsonResponse, which simplifies both maintenance and development. Payment gateways are each implemented in an independent Service Layer with dedicated logic (GetToken/Advice for Sepehr and Authority/Verify for ZarinPal).
Security is ensured by adhering to CSRF Protection, XSS Prevention, and SQL Injection Prevention principles, while scalability is achieved through query optimization (select_related, prefetch_related) and caching frequently repeated results. The overall design allows adding a new application or feature without affecting other parts of the system.
📐
Project Scale
In terms of scale, the Mahdis project is considered a medium-to-large platform, comprising 10 independent Django applications, over 25 data models, and approximately 80+ views. The user interface includes more than 50 dedicated HTML pages, implemented across 3 different Layouts (shared_panel, shared_index, shared_seo).
The system features 5 user access levels (Super Admin, Vendor, Barber, Responder, Regular User) and 2 active payment gateways (Sepehr and ZarinPal). The SEO section includes 4 content types (Article, Question, Experience, Video) with fully separate management, and the comprehensive admin panel provides Excel reporting along with full control over users, products, orders, shops, and barbershops.
In terms of codebase, the project consists of over 15,000 lines of Python code and more than 20,000 lines of Templates and Frontend code. The database includes over 30 tables interconnected through complex ForeignKey and ManyToMany relations. The project is currently online and active at mahdiss.com, ready for commercial use.
