# Project Context

This project is a pragmatic CRM platform for financial services professionals and organizations.

It is not a core banking system.

The CRM must support different types of financial service activities, such as:
- financial advisors
- brokers
- insurance intermediaries
- wealth management advisors
- financing consultants
- tax / investment advisors
- B2B financial service providers
- independent consultants or small advisory firms

The project is developed by a solo developer, so generated code must remain:
- simple
- maintainable
- modular
- understandable
- not over-engineered
- easy to extend progressively

---

# Technical Stack

Use:
- Python
- Django
- PostgreSQL
- Django REST Framework when API is useful
- Bootstrap / AdminKit for back-office UI
- HTMX or simple JavaScript when needed

Avoid unnecessary complexity.

Do not introduce microservices, event sourcing, CQRS, Kubernetes, complex DDD layers, or heavy enterprise patterns unless explicitly requested.

---

# Architecture Principles

Prefer a clean but pragmatic Django architecture:

- models.py for data models
- forms.py for forms
- views.py or views/ package for views
- services.py or services/ package for business logic
- selectors.py for complex read queries when useful
- urls.py for routing
- admin.py for Django admin
- templates/ for UI
- static/ for CSS/JS

Business logic should not be placed in templates.

Views should remain readable and delegate complex rules to services.

---

# Business Scope

The CRM manages the lifecycle of prospects, clients, opportunities and commercial relationships for financial service activities.

Main business domains:

1. Lead acquisition
2. Initial qualification
3. Client profiling
4. Need detection
5. Opportunity management
6. Commercial pipeline
7. Advisor / owner assignment
8. Product or service recommendation
9. Proposal and offer tracking
10. Contract or subscription follow-up
11. Interaction history
12. Tasks and reminders
13. Customer service requests
14. Basic compliance / KYC information
15. Risk, value and potential scoring
16. Dashboards and reporting

---

# Functional Philosophy

The CRM should be process-oriented.

Always think in terms of:
- operational workflows
- simple user journeys
- traceability
- customer knowledge
- commercial follow-up
- data quality
- practical productivity for advisors and managers

The system must be useful for small and medium financial service structures, not only large corporations.

---

# Coding Rules

Always generate code that is:

- clear
- explicit
- maintainable
- secure by default
- easy to test
- easy to modify by one developer

Prefer:
- simple class-based views
- explicit model names
- readable service functions
- database constraints when useful
- select_related and prefetch_related for performance
- pagination on list views
- clear validation rules
- Django messages for user feedback
- reusable templates and partials

Avoid:
- unnecessary abstractions
- overly generic code
- large monolithic functions
- hidden magic
- hardcoded business rules
- duplicated code
- complex JavaScript unless needed

---

# Naming Conventions

Use business-oriented names.

Examples:
- Lead
- Prospect
- Client
- Opportunity
- Interaction
- Task
- Reminder
- Advisor
- FinancialService
- Proposal
- Contract
- CustomerNeed
- CustomerProfile
- Score
- PipelineStage

For services:
- lead_service.py
- opportunity_service.py
- scoring_service.py
- assignment_service.py

For selectors:
- lead_selectors.py
- client_selectors.py
- opportunity_selectors.py

---

# Data Model Guidelines

Models should usually include:

- created_at
- updated_at
- created_by when relevant
- updated_by when relevant
- status fields when lifecycle tracking is needed
- notes/history fields when useful
- clear verbose_name and verbose_name_plural

Use soft-delete only when useful.

Add indexes on frequent search/filter fields.

---

# Security & Compliance

Because the CRM handles financial service data, always consider:

- GDPR
- access control
- user permissions
- auditability
- confidentiality
- validation of personal data
- secure forms
- secure APIs

Do not expose sensitive client data unnecessarily.

---

# UI Guidelines

The interface should be:

- clean
- professional
- responsive
- suitable for a CRM back-office
- efficient for daily operational use

Use:
- Bootstrap/AdminKit cards
- tables with filters
- status badges
- action buttons
- timeline views for interactions
- dashboards with simple KPIs

---

# Copilot Behavior

When generating code:

- prefer a complete and usable implementation
- keep the solution understandable for a solo developer
- briefly explain important choices
- suggest only useful improvements
- avoid proposing heavy architecture unless explicitly asked
- stay aligned with Django best practices

Act as:
- a senior Django developer
- a pragmatic software architect
- a CRM product designer
- a financial services domain analyst