Project Structure

This guide explains the organization and purpose of every directory and major file in the Evolve Payments Platform codebase. The project follows Django best practices with a modular architecture.

Root Level Overview

Directory Structure

my-evolve-platform/
├── App/                        # Main Django application modules
│   ├── admin/                  # Platform administration module  
│   ├── business/               # Business customer module
│   ├── reseller/               # Reseller module with earnings tracking
│   ├── integrations/           # External service integrations
│   ├── migrations/             # Database migrations
│   ├── models.py               # Shared models
│   ├── views.py                # Shared views
│   └── urls.py                 # URL routing
├── config/                     # Django project configuration
│   ├── settings.py             # Main Django settings
│   ├── urls.py                 # Root URL configuration
│   ├── wsgi.py                 # WSGI configuration
│   └── asgi.py                 # ASGI configuration
├── templates/                  # Global HTML templates
├── static/                     # Static files (CSS, JS, images)
├── staticfiles/                # Collected static files (production)
├── docs/                       # Project documentation
├── plans/                      # Project planning documents
├── .github/                    # GitHub workflows and CI/CD
│   └── workflows/              # GitHub Actions workflows
├── manage.py                   # Django management script
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker configuration
├── docker-compose.yml          # Multi-container setup
├── db.sqlite3                  # SQLite database (development)
├── .env                        # Environment variables (local only)
├── .gitignore                  # Git ignore rules
└── run_server.ps1              # PowerShell server startup script

App Module Structure

Each module in the App directory follows a consistent architecture pattern with clear separation of concerns:

Module Architecture Pattern

Every module (admin, business, reseller) follows this structure:

module_name/
├── api/                        # REST API endpoints
│   └── v1/                     # API version 1
│       ├── serializers/        # Data serialization
│       ├── views/              # API view controllers
│       └── urls.py             # API URL routing
├── models/                     # Database models
├── views/                      # Web view controllers
├── forms/                      # Django forms
├── services/                   # Business logic layer
├── repositories/               # Data access layer
├── tests/                      # Unit and integration tests
├── utils/                      # Utility functions
├── exceptions/                 # Custom exception classes
├── migrations/                 # Database migrations
└── management/                 # Custom Django commands
    └── commands/

Module Responsibilities

Admin Module (App/admin/)

Handles platform administration and management functions:

Purpose: Platform owner (Lixnet) management interface
Features: User management, vendor approval, transaction monitoring
API: Admin-specific REST endpoints for management operations

Business Module (App/business/)

Manages business customer functionality:

Purpose: End customer management and services
Features: Account management, subscription handling, software access
Integration: Payment processing, service provisioning

Reseller Module (App/reseller/)

Handles reseller operations and commission tracking:

Purpose: Sales agent functionality and earnings management
Features: Commission calculation, referral tracking, payout management
Special: Contains earnings/ sub-module for complex commission logic

Reseller Earnings Sub-module

reseller/earnings/
├── models/                     # Commission and payout models
├── services/                   # Earnings calculation logic
├── repositories/               # Earnings data access
├── api/                        # Earnings-specific API endpoints
└── forms/                      # Commission and payout forms

Architectural Layers

Layer	Directory	Responsibility	Example
API Layer	`api/v1/`	REST endpoints, data serialization, request/response handling	User registration API, data validation
Web Layer	`views/`	Web interface controllers, template rendering	Dashboard views, form handling
Service Layer	`services/`	Business logic, complex operations, workflow orchestration	Commission calculations, user workflows
Repository Layer	`repositories/`	Data access, database queries, data transformation	User data retrieval, complex database queries
Model Layer	`models/`	Database schema, data validation, relationships	User model, relationship definitions
Form Layer	`forms/`	Web form definitions, input validation	Registration forms, validation rules

Configuration Files

File	Purpose	Contains
`config/settings.py`	Django configuration	Database config, installed apps, middleware, security settings
`requirements.txt`	Python dependencies	Django, python-decouple, requests, and other packages
`.env`	Environment variables (local only)	API keys, database URLs, secret configurations
`Dockerfile`	Container configuration	Docker image build instructions and dependencies
`docker-compose.yml`	Multi-container setup	Service definitions, networking, volume configuration

Development Guidelines

Adding New Features

When implementing new functionality, follow this pattern:

Define models in the appropriate models/ directory
Implement business logic in services/
Create data access methods in repositories/
Build API endpoints in api/v1/
Create web views in views/ if needed
Add templates in the global templates/ directory
Write comprehensive tests in tests/

File Naming Conventions

Models: user_model.py, commission_model.py
Services: user_service.py, payment_service.py
Repositories: user_repository.py, commission_repository.py
APIs: user_views.py, commission_views.py
Tests: test_user_service.py, test_api_endpoints.py

Quick Navigation Tips

Business Logic: Look in App/[module]/services/
Database Queries: Check repositories/ directories
API Development: Navigate to api/v1/ folders
UI Templates: Global templates/ directory
Configuration: config/settings.py
Dependencies: requirements.txt

Best Practice: Always follow the established folder structure when adding new features. This maintains code organization and helps team members locate and understand functionality quickly.