Entity Model Documentation

Overview

The Entity model represents organizational structures within a tenant, supporting hierarchical relationships for corporations, divisions, departments, and teams.

Model Structure

Core Fields

Field	Type	Description	Constraints
entity_id	UUID	Unique identifier for the entity	Primary key, auto-generated
tenant_id	UUID	Associated tenant identifier	Foreign key to Tenant
name	String	Display name of the entity	Required, max 255 chars
code	String	Short code/abbreviation	Required, unique within tenant
entity_type	EntityType (Enum)	Organizational level	Required
status	EntityStatus (Enum)	Current operational status	Required
parent_id	UUID (Optional)	Parent entity for hierarchy	Self-referential FK
created_at	DateTime	Creation timestamp	Auto-set
updated_at	DateTime	Last modification timestamp	Auto-updated

EntityType Enum

enum EntityType {
    Corporation,  // Top-level organization
    Division,     // Major organizational unit
    Department,   // Functional area
    Team          // Working group
}

EntityStatus Enum

enum EntityStatus {
    Active,      // Normal operations
    Inactive,    // Temporarily disabled
    Suspended    // Compliance/legal hold
}

Database Schema

Primary Storage Pattern

Key: /{tenant_id}/entities/{entity_id}
Value: JSON serialized Entity object

Secondary Indexes

Code lookup: /{tenant_id}/entity_by_code/{code} -> entity_id
Parent hierarchy: /{tenant_id}/entities_by_parent/{parent_id} -> [entity_ids]
Type index: /{tenant_id}/entities_by_type/{entity_type} -> [entity_ids]

Example Data

{
  "entity_id": "d0b94a88-0137-4f59-9ff9-2c01cac3cc1c",
  "tenant_id": "10b23632-fa88-4abe-bf76-1af8fbf7b7ae",
  "name": "Test Entity",
  "code": "TST-001",
  "entity_type": "Corporation",
  "status": "Active",
  "parent_id": null,
  "created_at": "2025-08-04T09:15:51.272168109Z",
  "updated_at": "2025-08-04T09:15:51.272168109Z"
}

Hierarchical Structure

Valid Parent-Child Relationships

Corporation
    └── Division
        └── Department
            └── Team

Business Rules

1. Corporation entities cannot have parents
2. Teams cannot have children
3. Parent must be one level above child
4. Circular references prevented

Related Code

Source Files

• Model Definition: /src/models/entity.rs
• Repository: /src/db/repositories/entity_repository.rs
• API Handler: /src/api/handlers/entity_handlers.rs
• DTO: /src/api/dto/entity.rs
• Tests: /src/db/repositories/tests/entity_repository_tests.rs

Key Methods

impl Entity {
    fn new(tenant_id: Uuid, name: String, code: String, entity_type: EntityType) -> Self
    fn with_parent(self, parent_id: Uuid) -> Self
    fn activate(&mut self)
    fn deactivate(&mut self)
}

Repository Operations

trait EntityRepository {
    async fn create(&self, entity: &Entity) -> Result<()>
    async fn get_by_id(&self, tenant_id: &Uuid, entity_id: &Uuid) -> Result<Option<Entity>>
    async fn get_by_code(&self, tenant_id: &Uuid, code: &str) -> Result<Option<Entity>>
    async fn list_by_parent(&self, tenant_id: &Uuid, parent_id: Option<&Uuid>) -> Result<Vec<Entity>>
    async fn update(&self, entity: &Entity) -> Result<()>
    async fn delete(&self, tenant_id: &Uuid, entity_id: &Uuid) -> Result<()>
}

API Endpoints

Create Entity

• POST /api/entities
• Body: CreateEntityRequest
• Response: Entity
• Auth: Admin or Manager

Get Entity

• GET /api/entities/{entity_id}
• Response: Entity
• Auth: Any authenticated user

Update Entity

• PUT /api/entities/{entity_id}
• Body: UpdateEntityRequest
• Response: Entity
• Auth: Admin or Manager

List Entities

• GET /api/entities?parent_id={uuid}&type={type}&status={status}
• Response: Vec<Entity>
• Auth: Any authenticated user

Get Entity Hierarchy

• GET /api/entities/{entity_id}/tree
• Response: EntityTree
• Auth: Any authenticated user

Relationships

Many-to-One

• Tenant: Each entity belongs to one tenant
• Parent Entity: Optional hierarchical parent

One-to-Many

• Child Entities: Can have multiple subordinate entities
• Projects: Entity can own multiple projects
• Members: Entity can have assigned users

Business Logic

Entity Creation

1. Code must be unique within tenant
2. Type must align with parent's type
3. Corporation type cannot have parent
4. Status defaults to Active

Status Transitions

Active <-> Inactive (reversible)
Active -> Suspended (requires admin)
Suspended -> Active (requires admin approval)

Hierarchy Operations

• Get Ancestors: Walk up parent chain
• Get Descendants: Recursive child query
• Move Entity: Update parent_id with validation
• Delete Protection: Cannot delete with active children

Security Considerations

1. Access Control

   • View: Any authenticated user in tenant
   • Create/Update: Admin or Manager roles
   • Delete: Admin only
   • Cross-tenant access blocked

2. Data Integrity

   • Code uniqueness enforced
   • Parent-child type validation
   • Circular reference prevention
   • Cascade rules for status changes

Use Cases

Corporate Structure

ACME Corporation (ACME)
├── North America Division (NA-DIV)
│   ├── Sales Department (NA-SALES)
│   │   ├── Inside Sales Team (NA-IS)
│   │   └── Field Sales Team (NA-FS)
│   └── Marketing Department (NA-MKTG)
└── Europe Division (EU-DIV)

Project Assignment

• Projects linked to entities for ownership
• Resource allocation by entity
• Reporting aggregated by hierarchy
• Access inherited from entity membership

Performance Optimizations

1. Indexes

   • Primary: (tenant_id, entity_id)
   • Code lookup: (tenant_id, code)
   • Hierarchy: (tenant_id, parent_id)
   • Type filter: (tenant_id, entity_type)

2. Caching

   • Entity hierarchy cached
   • Code-to-ID mapping cached
   • Tree structure pre-computed

Audit Integration

Entity operations tracked in audit log:

• CREATE: New entity established
• UPDATE: Name/code/status changes
• MOVE: Parent reassignment
• DELETE: Entity removed

Future Extensions

1. Custom Attributes

   • Industry-specific fields
   • Compliance metadata
   • Cost center codes
   • Geographic regions

2. Advanced Features

   • Matrix organization support
   • Temporary assignments
   • Virtual teams
   • Cross-entity projects

---

Last Updated: 2025-08-29 Version: 1.0