1. Environment Setup & Configuration

Follow these steps to initialize the project dependencies and configuration:

1. Create Python virtual environment: python -m venv .venv
2. Activate: .venv\Scripts\activate (Windows) or source .venv/bin/activate (WSL/Linux)
3. Install packages: pip install -r requirements.txt
4. Create a .env file in the root directory and configure variables:

# Django Base Configuration
DJANGO_SETTINGS_MODULE=ddc_backend.settings.dev
SECRET_KEY=django-insecure-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
CSRF_TRUSTED_ORIGINS=http://localhost:3000

# PostgreSQL Credentials
DB_NAME=ddc_db
DB_USER=postgres
DB_PASSWORD=root
DB_HOST=localhost
DB_PORT=5432

# Redis Cache & Celery Broker
REDIS_URL=redis://localhost:6379/0

# Azure OpenAI Credentials
AZURE_OPENAI_ENDPOINT=https://...
AZURE_OPENAI_API_KEY=your-openai-key
AZURE_OPENAI_MODEL=gpt-4o
TEST_QUESTION_LIMIT=10

# CORS & Frontend Urls
CORS_ALLOWED_ORIGINS=http://localhost:3000
FRONTEND_URL=http://localhost:5176/

# Azure Blob Storage Configuration
AZURE_STORAGE_ACCOUNT_NAME=polaristeststore
AZURE_STORAGE_ACCOUNT_KEY=your-storage-key
AZURE_STORAGE_URL=https://polaristeststore...
AZURE_STORAGE_SSL=true
AZURE_STORAGE_QUERYSTRING_AUTH=True
AZURE_STORAGE_URL_EXPIRATION_SECS=3600

# Azure Communication Services Email
AZURE_EMAIL_CONNECTION_STRING=endpoint=https://...
AZURE_SENDER_EMAIL=DoNotReply@polaris.ddcdev.net
DDC_SUPPORT_ADMIN_EMAIL=admin@ddcgroup.com

2. Migrations & Execution

Launch database tables and start backend background workers:

1. Initialize schemas: python manage.py migrate
2. Launch development server: python manage.py runserver
3. Activate Celery workers: celery -A ddc_backend worker -l info
4. Launch scheduled logs purging: python manage.py run_apscheduler

Project Directory Structure

ddc_backend/               # Root Project Directory
├── apps/                  # Django Apps Directory
│   ├── accounts/          # User registration & JWT auth RBAC
│   ├── common/            # Regions, Currencies & Roles master tables
│   ├── clients/           # Corporate clients & reviewer profiles
│   ├── verticals/         # Standard process categories (P2P, O2C)
│   ├── assessments/       # Diagnostic opportunities & lifecycles
│   ├── questionnaires/    # Question bank, formulas & validation
│   ├── benchmarks/        # Quartile distributions & mappings
│   ├── rate_card/         # Loaded salaries & solution rate cards
│   ├── solution_costing/  # Resource effort sheets & ROI summaries
│   ├── proposals/         # Generated client transformation bids
│   ├── projects/          # Active execution project milestones
│   ├── analysis/          # Core Azure OpenAI report executors
│   ├── reports/           # Saved PDF report structures
│   ├── audit_logs/        # Network & DB modification logs
│   ├── notifications/     # Online WebSockets & offline alerts
│   └── emailer/           # Celery SMTP sending & signals
├── ddc_backend/           # Django settings, WSGI/ASGI config
└── templates/             # Global HTML layouts & static assets

Model Bases

• Region: Master region configurations (e.g. USA, UK, India).
• Currency: Global currency profiles with codes, symbols, countries, and status.
• OperationsRole: Operational roles with day rates (min, max, current) and experience tiers.
• ConsultantRole: Core consulting tiers with experience choices and standard day rate bands.

Master List Endpoints

• GET /api/common/regions/: Lists active regions.
• GET /api/common/currencies/: Lists supported currencies.
• GET /api/common/operations-roles/: Lists operations roles.
• GET /api/common/consultant-roles/: Lists consultant roles.

Entity Management CRUD Endpoints

• POST /api/common/region/: Create a new region.
• PUT /api/common/currency/<id>/update/: Update currency settings.
• POST /api/common/operations-role/: Create operations roles.
• DEL /api/common/consultant-role/<id>/delete/: Delete consultant role.

JSON Operations Role Creation

{
  "name": "Order to Cash Team Lead",
  "code": "O2C_TL",
  "experience_level": "SENIOR",
  "day_rate_min": "350.00",
  "day_rate_max": "550.00",
  "day_rate_current": "450.00",
  "number_of_days": 20,
  "is_active": true
}

User & Profile Models

• User Model: Extends AbstractUser; uses email as unique username identifier. Fields include role, company_name, parent, industry_type, and active status.
• Soft-Deletes: Includes custom soft_delete() and restore() methods that deactivate credentials and cascade client user profile updates safely.
• UserProfile Model: Stores extended contact details (e.g. phone_number, address, city, state, zip_code, country).

Role Definitions & Scope

• ADMIN: CRUD companies, verticals, and prompts.
• REVIEWER: Reviews assessments generated by consultants to approve or reject them.
• CONSULTANT: Score questionnaires and costing sheets.
• CLIENT: Can only view their own assessments, and approve or reject them.

Authentication Endpoints

• POST /api/auth/login/: Obtains JWT access and refresh tokens.
• POST /api/auth/token/refresh/: Renews expired access token using refresh token.

JSON Login Payload Sample

{
  "email": "consultant@ddc.com",
  "password": "securepassword123"
}

JSON Token Response Sample

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ..."
}

Company & Client APIs

Manage corporate subsidiaries (Companies) and their contact users (Clients) with assigned consultant reviewer pairs:

• POST /api/common/company/: Creates a new corporate client parent record.
• DEL /api/common/company/<id>/delete/: Soft deletes the company and cascades to its client users.
• GET /api/clients/: Lists all client users.
• POST /api/clients/add/: Provisions a client user profile and assigns consultant verticals.
• PUT /api/clients/<id>/update/: Updates client details and reviewer/vertical associations.
• DEL /api/clients/<id>/delete/: Soft deletes a client user profile and deactivates their login account.

Client Activity History

GET /api/clients/<user_id>/history/: Reads combined historical assessments, costing snapshots, and proposals stats.

JSON Add Client Payload

{
  "contact_email": "operations@acme-global.com",
  "contact_name": "John Doe",
  "company_id": 5,
  "industry_id": 1,
  "reviewer_id": 2,
  "verticals_and_consultants": [
    {
      "vertical_id": 2,
      "consultant_id": 4
    }
  ]
}

ProcessVertical Model

Acts as a template filter. When creating questionnaires, questions are linked to specific verticals to isolate calculations:

• name: Full process description (e.g. "Procure to Pay").
• code: Unique identifier (e.g. "P2P").
• is_active: Toggles availability on assessments.

Verticals API Endpoints

• GET /api/common/verticals/: Lists all process verticals (e.g. O2C, P2P).
• POST /api/common/vertical/: Adds a new process vertical.
• DEL /api/common/vertical/<id>/delete/: Deactivates or soft deletes a process vertical.

JSON Create Vertical Payload

{
  "name": "Order to Cash",
  "code": "O2C",
  "description": "Customer ordering, billing, and collections process",
  "is_active": true
}

Assessment & IndustryType Models

• Assessment Model: Core entity storing name, status (choices: DRAFT, RUNNING, COMPLETED, REWORK, LOCKED), step metrics, assigned stakeholders, region, verticals, and cached report_data. Supports cascades on soft-delete.
• IndustryType Model: Dynamic metadata lookups (e.g. Retail, Manufacturing) referenced by assessments.

Strict Client Isolation

Clients are strictly isolated at the database query layer. The API filters queries by user ID so that a CLIENT role can only view their own assessments, and approve or reject them, protecting proprietary client details.

Assessment API Endpoints

• GET /api/assessments/: Lists active assessments (with role-based access).
• POST /api/assessments/: Initializes a new assessment workflow.
• POST /api/assessments/<id>/comments/: Attaches comments when requesting rework or feedback.

JSON Create Assessment Payload

{
  "name": "Finance Discovery Survey",
  "client": 12,
  "industry_type": 1,
  "managed_by": 4,
  "input_method": "QUESTIONNAIRE",
  "region_id": 2,
  "vertical_ids": [2, 3],
  "current_step": 1,
  "total_steps": 5
}

JSON Rework Comment Payload

{
  "question": 142,
  "comment_text": "FTE numbers look higher than typical benchmarks. Please confirm."
}

Calculation stabilization loop

The backend validation engine re-evaluates formulas up to 10+ times in a loop to ensure that dependent calculations (e.g. calculating total processing costs from salaries and FTEs) stabilize before validation checks are applied.

Questionnaires & Import Endpoints

• GET /api/questionnaires/questions/: Fetches the master bank of diagnostic questions.
• POST /api/assessments/<id>/upload-questions/: Imports questions from an Excel/CSV template (Multipart form upload with file key).
• POST /api/assessments/<id>/submit-answers/: Bulk saves answers and sub-answers for the specified assessment.
• POST /api/questionnaires/validate-answers/: Stabilizes formula dependencies and validates answers for errors before submission.

JSON Submit Answers Payload

{
  "assessment_id": 42,
  "answers": [
    {
      "question_id": 101,
      "value": "25000",
      "sub_answer": {}
    },
    {
      "question_id": 102,
      "value": "8",
      "sub_answer": {}
    }
  ]
}

Quartiles Metric Mappings

Metrics are matched by region (USA, UK, India) to account for salary variations. Distributions are divided into standard quartiles:

• Top Quartile: Highly efficient operations.
• Median: Standard baseline performance.
• Bottom Quartile: Gaps to resolve (e.g. excessive cycle times).

Matching Algorithm Details

Looks up matching rules using the linked question code. If missing, it falls back to a case-insensitive, whitespace-trimmed comparison of the question text.

API Query Example

GET /api/benchmarks/: Fetches industry quartile benchmarks using target region/vertical/industry codes.

GET /api/benchmarks/?industry=1&vertical=2&region=USA

Response Payload

{
  "metric": "Cycle Time Hours",
  "top_quartile": "4.5",
  "median": "12.0",
  "bottom_quartile": "24.0"
}

Standard & Custom Rate Card Models

• RateCard Model: Defines standard/custom rate catalogs (fields: name, version, currency, scope, status, and associations to client/assessment).
• Through Models: RateCardOperationsRole and RateCardConsultantRole map roles to specific day rate parameters.

Solution Rate Card Models

• SolutionCostingRateCard Model: Costing overrides containing PMO and support rate modifiers (pmo_percentage, support_percentage).
• SolutionCostingRateCardItem & SolutionComponent: Store itemized solution costs linked to master components (e.g. RPA, IDP) with custom units, rates, complexity, and multipliers.

Rate Cards API Endpoints

• GET /api/rate_card/: Lists active rate cards with regional currencies.
• POST /api/rate_card/: Creates a new base or client-specific rate card.
• PUT /api/rate_card/<id>/: Overwrites loaded salaries, overheads, and role benefit details.

JSON Create Rate Card Payload

{
  "name": "Custom Northeast USA Rate Card",
  "client": 12,
  "assessment": null,
  "region": "USA",
  "currency": 1
}

Solution Costing Models

• SolutionCosting Model: Aggregates build, PMO, and support costs mapped to assessment opportunities. Stores quantitative parameters (bots, processes, FTE days, durations) alongside detailed cost breakdowns and ROI summaries (annual savings, ROI %, payback period).
• SolutionCostingLineItem Model: Stores individual component items (quantity, unit rate, complexity, and multipliers) matching the solution costing parameters.

Solution Costing API Endpoints

• POST /api/solution_costing/: Creates a costing sheet mapped to assessment opportunities.
• POST /api/solution_costing/line-items/: Adds child role/FTE details to estimate build/support margins.

JSON Costing & Line-Item Payload

# Create costing
{
  "name": "Consulting ROI Estimate",
  "assessment_opportunities": [1, 2],
  "rate_card": 5
}

# Add Line Item
{
  "solution_costing": 3,
  "role": 2,
  "headcount": 1.5,
  "location": "US-East",
  "duration_months": 6
}

Proposal Model & Validation

• Proposal Model: Maps a OneToOne relation to SolutionCosting. Stores title, summaries, scope, timeline, validity, deliverables (JSONField list), status, creators, and approval metadata.
• Constraint Check: The database level clean() method enforces that a proposal can ONLY be created/linked to a SolutionCosting that is in the APPROVED status.

Proposal Lifecycle States

Tracks proposal progress from creation to client sign-off:

Only approved proposals can be converted to active projects.

Proposals API Endpoints

• GET /api/proposals/: Lists generated proposals (allows client/reviewer filters).
• POST /api/proposals/: Creates a new proposal from an approved solution costing.
• POST /api/proposals/<id>/approve/: Approves the proposal, launching implementation.

JSON Create Proposal Payload

{
  "solution_costing_id": 3,
  "title": "DDC Automation Transformation Proposal",
  "executive_summary": "Proposal generated from approved solution costing and assessment insights.",
  "scope_of_work": "Implement automation roadmap across selected verticals.",
  "timeline_weeks": 16,
  "validity_days": 30,
  "deliverables": [
    "Solution blueprint",
    "Implementation plan",
    "Benefit tracking dashboard"
  ],
  "terms_and_conditions": "Commercial terms as per MSA and SOW.",
  "status": "DRAFT"
}

Project & Opportunity Models

• Project Model: Formed on proposal approval (OneToOne to Proposal). Stores stage details (choices: NOT_STARTED, IN_PROGRESS, ON_HOLD, COMPLETED, CANCELLED), delivery status (choices: ON_TRACK, AT_RISK, DELAYED), budget limit, dates, PM name, and notes.
• ProjectOpportunity Model: Links a project opportunity to AssessmentOpportunity for individual tracking stage mapping with unique constraints.

From Proposal to Project

Approved proposals trigger the creation of a Project record. The system links implementation milestones, vertical process scopes, and budget parameters automatically.

Projects API Endpoints

• GET /api/projects/: Lists active projects and execution milestones.
• POST /api/projects/: Disabled (Project creation is automatic upon proposal approval).
• PUT /api/projects/<id>/status/: Updates execution stage (e.g. IN_PROGRESS, COMPLETED).

JSON Create Project Payload

{
  "proposal": 4,
  "name": "Finance Process Automation",
  "start_date": "2026-07-01",
  "end_date": "2027-01-31",
  "budget_limit": 150000.00,
  "milestones": ["Requirements", "Pilot", "Go-Live"]
}

Step 1: Input Validation

Ensures input data is complete. The system checks validation rules (group sums, cross-row bounds, limits) before launching Step 2.

GET /api/questionnaires/validate-answers/

Step 2: BLE Engine Execution

Triggers calculations (FTE savings, payback months, NPV) and calls the Azure OpenAI service using structured prompt files to compose mature text narratives.

POST /api/assessments/<id>/run-analysis/

Step 3: OpenAI Narrative Creation

Integrates prompts dynamically with client answers. The LLM produces maturity evaluations, process gap audits, and a 3-year roadmap schedule.

Step 4 & 5: Sync & Database Persistence

Parses BLE outputs and syncs them back into apps.reports model structures: AssessmentReport, AssessmentReportSection, and AssessmentOpportunity.

Dashboard Stats

Aggregates operational volumes across the entire backend database:

• Total active company assessments count.
• Number of pending proposals awaiting customer approval.
• Aggregated ROI percentages and yearly baseline savings.
• Counts of active projects and completed project milestones.

Endpoint: GET /api/dashboards/stats/ (calculates high-level metrics).

Dashboard Details Endpoint

GET /api/dashboards/details/: Returns granular records (recent assessments, proposals, and projects) to populate dashboard tables.

Contribution Analytics (/api/analytics/)

Tracks productivity metrics for consultants and client contributors:

• Completion Velocity: Average time from assessment start to submit.
• Rework Rates: Count of sections rejected by consultants.
• Question completion: Matrix of answered vs empty questions per vertical.

Endpoint: GET /api/analytics/contributions/ (retrieves aggregate analytics).

AuditLog Model

Tracks database modifications (CREATED, UPDATED, DELETED):

• user: User triggering the event.
• action: Short summary (e.g. "company created").
• details: JSON logging parameters.

HttpRequestActivity Model

Tracks network request statistics: path, response status codes, execution latency, and source client IP address.

Audit API Endpoints

• GET /api/audit_logs/: Retrieves standard models audit trail history.
• GET /api/audit_logs/http-activities/: Exposes collected HTTP request/response metrics.

WebSocket Architecture

Utilizes Django Channels and Daphne ASGI server to maintain persistent connection streams. Real-time tasks notify consumers under the /ws/analysis/<assessment_id>/ endpoint path.

Notification Model & APIs

Persists alerts (unread/read flags, recipient user mappings, message blocks) to DB storage when clients are offline.

• GET /api/notifications/: Lists unread and read alerts for the active session user.
• POST /api/notifications/<id>/read/: Marks a specific notification record as read.

Status Event Payload Example

{
  "event": "analysis_progress",
  "assessment_id": 42,
  "step_name": "data_validation",
  "status": "running",
  "progress": 20,
  "message": "Step 1/5 completed: Data Validation"
}

EmailLog Model Bases

Serves as a minimal database audit trail for troubleshooting and operational tracking:

• kind: Category of email (e.g. SET_PASSWORD, ACCESS_REMOVED).
• to_email: Recipient email address(es).
• subject: Subject header line.
• status: Send status, restricted to choices SENT or FAILED.
• user / actor: Linked user profile and the triggering administrator.
• meta: Additional payload parameters stored as JSON.
• error: Verbose trace log stored upon SMTP connection/send failure.

Celery Asynchronous Email Pipeline

Avoids blocking request-response cycles. Email dispatching is processed out-of-band:

• send_email_task: Celery task handling mail formation, HTML template formatting, SMTP server communication, and logging.
• Retries & Backoff: Automates up to 3 retries with a 60-second backoff delay in case of transient mail server interruptions.

Security & Account Signals

Listens directly to User model updates to automatically trigger alert dispatches:

• post_save (User): Sends notification emails immediately when a user account is deactivated.
• pre_delete (User): Warns active users via email prior to administrative profile deletions.

1. Seeding Lookups & Metadata

Run these commands to seed static entities after migrating databases:

• load_verticals: Seeds process verticals (P2P, O2C, R2R).
• load_industry_types: Seeds industry verticals (Mfg, Retail, Tech).
• load_default_currencies: Seeds currencies (USD, EUR, INR).

2. Seeding Questionnaires & Templates

• import_questionnaire_snapshot: Loads question sets from json template banks.
• import_validation_rules_json: Imports math evaluation rules and group bounds.
• import_review_questions: Populates scoring questionnaires.

3. Seeding Benchmarks

Loads quartile boundaries and standard deviations for process models:

• import_benchmarks: Imports metrics from standard CSV tables.
• extract_benchmarks: Exports benchmark rows to spreadsheets.

4. AI Prompts Syncing & Schedulers

• sync_prompts: Syncs prompts from local text files to DB prompts app.
• run_apscheduler: Activates scheduler for cleanup / logs purging.
• send_azure_test_email: Verifies SMTP/ACS credentials.

1. Database Constraints & Transactions

Always execute multi-row updates (e.g. cascading deletes) inside atomic transaction blocks (transaction.atomic()) to prevent orphaned rows or corrupted states.

2. Case-Insensitive Matching

Avoid duplicate registry records by enforcing case-insensitive checks (e.g., using __iexact) for emails, codes, and benchmark lookups.

3. Strict Query Isolation (RBAC)

Ensure querysets and views restrict client access boundaries (e.g. client_id=request.user.id) to prevent unauthorized horizontal data access.

4. Soft Delete Cascading

Maintain data integrity by ensuring soft-deletes (is_deleted=True) propagate cleanly to downstream models (Assessments -> Costing -> Proposals -> Projects).

5. AI Prompt Safety & Sync

Prompts must not be hardcoded. Store them in database models and update via sync_prompts command for dynamic run-time adjustments.

6. Celery Task Offloading

Heavy processing, Excel spreadsheet uploads, and OpenAI report generation should run asynchronously in workers to avoid thread blocking.

7. Formula Stabilization Loop

Run validation engines through a multi-pass loop (up to 10+ times) to stabilize dependent formulas before checking for errors.

8. Audit Logs & Latency Logs

Record all database modifications (via AuditLog) and incoming request latencies to track performance and security compliance.