0
# Core Framework
1

2
The foundational components of Creme CRM that provide entity management, relationships, permissions, and core Django models. These components form the base layer upon which all CRM functionality is built.
3

4
## Capabilities
5

6
### Entity System
7

8
Base entity class and core functionality for all business objects in Creme CRM.
9

10
```python { .api }
11
class CremeEntity(CremeModel):
12
    """
13
    Base class for all business entities in Creme CRM.
14
    Provides common functionality like properties, relationships, permissions, and history.
15

16
    Fields:
17
    - created: CreationDateTimeField, creation timestamp (auto-set, non-clonable)
18
    - modified: ModificationDateTimeField, last modification timestamp (auto-set)
19
    - entity_type: CTypeForeignKey, content type (auto-set, non-editable)
20
    - header_filter_search_field: CharField(200), searchable field content (auto-generated)
21
    - is_deleted: BooleanField, soft deletion flag (default: False)
22
    - user: CremeUserForeignKey, owner user
23
    - description: TextField, entity description (optional)
24
    - uuid: UUIDField, unique identifier (auto-generated, non-editable)
25
    - sandbox: ForeignKey(Sandbox), isolation/security context (optional)
26
    - extra_data: JSONField, additional data storage (default: {})
27

28
    Manager: CremeEntityManager
29
    Meta: Ordered by header_filter_search_field
30

31
    Methods:
32
    - get_absolute_url(): Get entity detail URL
33
    - get_edit_absolute_url(): Get entity edit URL
34
    - get_delete_url(): Get entity deletion URL
35
    - get_lv_absolute_url(): Get list view URL
36
    - trash(): Soft delete the entity
37
    - restore(): Restore soft deleted entity
38
    - clone(): Create a copy of the entity
39
    """
40

41
class CremeModel(models.Model):
42
    """
43
    Base model class for Creme CRM models.
44
    Provides common functionality for all models.
45

46
    Attributes:
47
    - created: datetime, creation timestamp
48
    - modified: datetime, last modification timestamp
49
    """
50

51
class MinionModel(models.Model):
52
    """
53
    Base class for auxiliary models that support main entities.
54
    Used for configuration and supporting data structures.
55
    """
56
```
57

58
### User Management
59

60
Extended user model and authentication system.
61

62
```python { .api }
63
class CremeUser(AbstractUser):
64
    """
65
    Extended Django user model with CRM-specific fields and functionality.
66

67
    Attributes:
68
    - displayed_name: str, display name for UI
69
    - language: str, preferred language code
70
    - time_zone: str, user timezone
71
    - role: UserRole, assigned role for permissions
72
    - is_team: bool, indicates team user account
73
    - json_settings: JSONField, user preferences storage
74

75
    Methods:
76
    - get_teams(): Get teams this user belongs to
77
    - has_perm_to_access(app_label): Check app access permission
78
    - has_perm_to_view(entity): Check entity view permission
79
    - has_perm_to_change(entity): Check entity edit permission
80
    - has_perm_to_delete(entity): Check entity delete permission
81
    - has_perm_to_link(entity): Check entity link permission
82
    - has_perm_to_unlink(entity): Check entity unlink permission
83
    """
84

85
class UserRole(models.Model):
86
    """
87
    Role-based permission system for users.
88

89
    Attributes:
90
    - name: str, role name
91
    - allowed_apps: ManyToMany, accessible applications
92
    - admin_4_apps: ManyToMany, applications with admin rights
93
    - creatable_ctypes: ManyToMany, entities user can create
94
    - exportable_ctypes: ManyToMany, entities user can export
95

96
    Methods:
97
    - can_access(app_label): Check if role allows app access
98
    - can_admin(app_label): Check if role has admin rights for app
99
    - can_create(ctype): Check if role can create entity type
100
    - can_export(ctype): Check if role can export entity type
101
    """
102
```
103

104
### Relationship System
105

106
Entity relationship management with typed connections.
107

108
```python { .api }
109
class Relation(models.Model):
110
    """
111
    Relationship between two entities with a specific type.
112

113
    Attributes:
114
    - user: CremeUser, user who created the relationship
115
    - type: RelationType, type of relationship
116
    - subject_entity: CremeEntity, source entity
117
    - object_entity: CremeEntity, target entity
118
    - symmetric_relation: Relation, reverse relation for bidirectional types
119

120
    Methods:
121
    - delete(): Delete relationship and symmetric counterpart
122
    - get_symmetric_relation(): Get the reverse relationship
123
    """
124

125
class RelationType(models.Model):
126
    """
127
    Definition of relationship types between entities.
128

129
    Attributes:
130
    - id: str, unique identifier
131
    - predicate: str, relationship description (subject -> object)
132
    - symmetric_type: RelationType, reverse type for bidirectional relations
133
    - is_copiable: bool, whether relation should be copied when cloning entities
134
    - enabled: bool, whether this relation type is active
135
    - subject_ctypes: ManyToMany, allowed subject entity types
136
    - object_ctypes: ManyToMany, allowed object entity types
137
    - subject_properties: ManyToMany, required subject properties
138
    - object_properties: ManyToMany, required object properties
139

140
    Methods:
141
    - is_compatible(subject_ctype, object_ctype): Check type compatibility
142
    - get_compatible_subject_ctypes(): Get allowed subject types
143
    - get_compatible_object_ctypes(): Get allowed object types
144
    """
145

146
class SemiFixedRelationType(models.Model):
147
    """
148
    Predefined relationship types with specific configurations.
149
    Used for system-defined relationships like 'has' or 'owns'.
150

151
    Attributes:
152
    - relation_type: RelationType, the actual relation type
153
    - predicate: str, relationship description
154
    - object_entity: CremeEntity, fixed target entity (optional)
155
    """
156
```
157

158
### Property System
159

160
Flexible property assignment to entities.
161

162
```python { .api }
163
class CremeProperty(models.Model):
164
    """
165
    Property assigned to an entity, providing flexible attributes.
166

167
    Attributes:
168
    - type: CremePropertyType, property type definition
169
    - creme_entity: CremeEntity, entity this property belongs to
170
    - value: str, optional property value
171

172
    Methods:
173
    - __str__(): String representation of property
174
    """
175

176
class CremePropertyType(models.Model):
177
    """
178
    Definition of property types that can be assigned to entities.
179

180
    Attributes:
181
    - uuid: str, unique identifier
182
    - text: str, human-readable description
183
    - is_custom: bool, whether this is a user-defined property type
184
    - is_copiable: bool, whether property should be copied when cloning entities
185
    - subject_ctypes: ManyToMany, allowed entity types for this property
186

187
    Methods:
188
    - can_be_assigned_to(entity_type): Check if property can be assigned to entity type
189
    - generate_uuid(): Generate unique UUID for new property types
190
    """
191
```
192

193
### Permission System
194

195
Fine-grained access control and security.
196

197
```python { .api }
198
class EntityCredentials(models.Model):
199
    """
200
    Entity-level permissions for users and roles.
201

202
    Attributes:
203
    - role: UserRole, role these credentials apply to
204
    - value: int, permission bitmask (VIEW, CHANGE, DELETE, LINK, UNLINK)
205
    - set_type: int, whether permissions are granted or forbidden
206
    - ctype: ContentType, entity type these permissions apply to
207
    - efilter: EntityFilter, filter to limit which entities permissions apply to
208

209
    Constants:
210
    - VIEW: Permission to view entities
211
    - CHANGE: Permission to modify entities
212
    - DELETE: Permission to delete entities
213
    - LINK: Permission to create relationships with entities
214
    - UNLINK: Permission to remove relationships from entities
215

216
    Methods:
217
    - get_permissions(): Get list of permission names
218
    - has_perm(perm): Check if specific permission is included
219
    """
220

221
class SetCredentials(models.Model):
222
    """
223
    Permission sets that can be assigned to users for specific entity types.
224

225
    Attributes:
226
    - role: UserRole, role these credentials belong to
227
    - value: int, permission bitmask
228
    - set_type: int, grant or forbid permissions
229
    - ctype: ContentType, entity type
230
    - efilter: EntityFilter, entity filter for conditional permissions
231

232
    Methods:
233
    - can_view(): Check if view permission is granted
234
    - can_change(): Check if change permission is granted
235
    - can_delete(): Check if delete permission is granted
236
    - can_link(): Check if link permission is granted
237
    - can_unlink(): Check if unlink permission is granted
238
    """
239

240
class Sandbox(models.Model):
241
    """
242
    User sandboxing system for isolating user data.
243

244
    Attributes:
245
    - uuid: str, unique sandbox identifier
246
    - user: CremeUser, sandbox owner
247
    - type: ContentType, entity type this sandbox applies to
248
    - role: UserRole, role for sandbox permissions
249

250
    Methods:
251
    - check_perm(user, perm): Check if user has permission in this sandbox
252
    - get_related_entities(): Get entities associated with this sandbox
253
    """
254
```
255

256
### Model Resolution
257

258
Dynamic model resolution based on configuration.
259

260
```python { .api }
261
def get_concrete_model(model_setting: str) -> type[models.Model]:
262
    """
263
    Get the concrete model class that is active in this project.
264

265
    Parameters:
266
    - model_setting: str, settings key containing model path
267

268
    Returns:
269
    type[models.Model]: The actual model class
270

271
    Raises:
272
    - ImproperlyConfigured: If setting is malformed or model doesn't exist
273

274
    Example:
275
    ContactModel = get_concrete_model('PERSONS_CONTACT_MODEL')
276
    """
277

278
def get_world_settings_model():
279
    """
280
    Get the WorldSettings model that is active in this project.
281

282
    Returns:
283
    type[WorldSettings]: The WorldSettings model class
284
    """
285
```
286

287
### Configuration Models
288

289
System configuration and customization support.
290

291
```python { .api }
292
class FieldsConfig(models.Model):
293
    """
294
    Configuration for field visibility and behavior per entity type.
295

296
    Attributes:
297
    - content_type: ContentType, entity type this config applies to
298
    - descriptions: JSONField, field configuration data
299

300
    Methods:
301
    - is_field_hidden(field_name): Check if field should be hidden
302
    - is_field_required(field_name): Check if field is required
303
    - get_4_model(model): Get field configuration for model
304
    - create_4_model(model, **kwargs): Create configuration for model
305
    """
306

307
class EntityFilter(models.Model):
308
    """
309
    Saved filters for entity queries with conditions.
310

311
    Attributes:
312
    - id: str, unique filter identifier
313
    - name: str, human-readable filter name
314
    - entity_type: ContentType, entity type this filter applies to
315
    - filter_type: int, filter type (regular, private, etc.)
316
    - user: CremeUser, filter owner (for private filters)
317
    - is_custom: bool, whether this is a user-defined filter
318
    - use_or: bool, whether conditions use OR logic (default: AND)
319

320
    Methods:
321
    - can_view(user): Check if user can view this filter
322
    - can_edit(user): Check if user can edit this filter
323
    - can_delete(user): Check if user can delete this filter
324
    - get_conditions(): Get filter conditions
325
    - filter_queryset(queryset): Apply filter to queryset
326
    """
327

328
class EntityFilterCondition(models.Model):
329
    """
330
    Individual condition within an entity filter.
331

332
    Attributes:
333
    - filter: EntityFilter, parent filter
334
    - type: int, condition type (field, relation, property, etc.)
335
    - name: str, field/condition name
336
    - value: JSONField, condition value and parameters
337

338
    Methods:
339
    - decode_value(): Parse condition value
340
    - apply_to_queryset(queryset): Apply condition to queryset
341
    """
342
```
343

344
## Common Constants
345

346
```python { .api }
347
# Permission constants
348
VIEW = 1
349
CHANGE = 2
350
DELETE = 4
351
LINK = 8
352
UNLINK = 16
353

354
# Deletion behavior
355
CREME_REPLACE = 1      # Replace deleted entity with another
356
CREME_REPLACE_NULL = 2 # Set foreign keys to null on deletion
357

358
# Root user credentials
359
ROOT_USERNAME = "root"
360
ROOT_PASSWORD = "root"
361

362
# Core relation types
363
REL_SUB_HAS = "creme_core-subject_has"
364
REL_OBJ_HAS = "creme_core-object_has"
365
```